icon: add new shortcode #412

This commit is contained in:
Sören Weber 2022-12-02 18:31:54 +01:00
parent 04779085e9
commit 350f7abd7f
No known key found for this signature in database
GPG key ID: BEC6D55545451B6D
19 changed files with 163 additions and 67 deletions

View file

@ -28,7 +28,7 @@ See [what's new]({{% relref "basics/migration" %}}) within the latest update.
- [Multilingual mode]({{%relref "cont/i18n" %}}) for English, Arabic, Simplified Chinese, Traditional Chinese, Dutch, Finnish (Suomi), French, German, Hindi, Indonesian, Italian, Japanese, Korean, Polish, Portuguese, Russian, Spanish, Turkish, Vietnamese
- Support for languages written right to left
- [Unrestricted menu configuration]({{%relref "cont/menushortcuts" %}}) relating to amount of items and level of nesting
- [Font Awesome icons]({{%relref "cont/icons" %}})
- [Font Awesome icons]({{%relref "shortcodes/icon" %}})
- [Tagging support]({{%relref "cont/tags" %}})
- [Image resizing, shadow...]({{%relref "cont/markdown#images" %}})
- [Syntax highlighting]({{%relref "cont/syntaxhighlight" %}})

View file

@ -18,7 +18,9 @@ This document shows you what's new in the latest release. For a detailed list of
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} The new [`badge` shortcode]({{% relref "shortcodes/badge" %}}) is now available to add highly configurable markers to your content as you can see it on this page.
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} The theme now supports some of GFM (GitHub Flavored Markdown) syntax and Hudo Markdown extensions, namely [task lists]({{% relref "cont/markdown#tasks" %}}), [defintion lists]({{% relref "cont/markdown#defintions" %}}) and [footnotes]({{% relref "cont/markdown#footnotes" %}}).
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} The new [`icon` shortcode]({{% relref "shortcodes/icon" %}}) simplyfies the usage of icons. This can even be combined with also new `badge` shortcode.
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} The theme now supports some of GFM (GitHub Flavored Markdown) syntax and Hugo Markdown extensions, namely [task lists]({{% relref "cont/markdown#tasks" %}}), [defintion lists]({{% relref "cont/markdown#defintions" %}}) and [footnotes]({{% relref "cont/markdown#footnotes" %}}).
---

View file

@ -1,6 +1,6 @@
+++
title = "Multilingual and i18n"
weight = 7
weight = 6
+++
The Relearn theme is fully compatible with Hugo multilingual mode.

View file

@ -1,5 +1,5 @@
+++
title = "Multilingual an' i18n"
weight = 7
weight = 6
+++
{{< piratify >}}

View file

@ -1,41 +0,0 @@
+++
title = "Icons and logos"
weight = 6
+++
The Relearn theme for Hugo loads the [**Font Awesome**](https://fontawesome.com) library, allowing you to easily display any icon or logo available in the Font Awesome free collection.
## Finding an icon
Browse through the available icons in the [Font Awesome Gallery](https://fontawesome.com/v5/search?m=free). Notice that the **free** filter is enabled, as only the free icons are available by default.
Once on the Font Awesome page for a specific icon, for example the page for the [heart](https://fontawesome.com/v5/icons/heart?s=solid), copy the HTML reference and paste into the Markdown content.
The HTML to include the heart icon is:
```html
<i class="fas fa-heart"></i>
```
## Including in markdown
Paste the `<i>` HTML into markup and Font Awesome will load the relevant icon.
```html
Built with <i class="fas fa-heart"></i> by Relearn and Hugo
```
Which appears as
Built with <i class="fas fa-heart"></i> by Relearn and Hugo
## Customising icons
Font Awesome provides many ways to modify the icon
- Change color (by default the icon will inherit the parent color)
- Increase or decrease size
- Rotate
- Combine with other icons
Check the full documentation on [web fonts with CSS](https://fontawesome.com/how-to-use/web-fonts-with-css) for more.

View file

@ -1,5 +0,0 @@
+++
title = "Ay'cons an' logos"
weight = 6
+++
{{< piratify >}}

View file

@ -24,7 +24,7 @@ John Gruber, the author of Markdown, puts it like this:
Without further delay, let us go over the main elements of Markdown and what the resulting HTML looks like:
{{% notice tip %}}
<i class="fas fa-bookmark"></i> Bookmark this page and the [official Commonmark reference](https://commonmark.org/help/) for easy future reference!
{{% icon bookmark %}} Bookmark this page and the [official Commonmark reference](https://commonmark.org/help/) for easy future reference!
{{% /notice %}}
## Paragraphs

View file

@ -1,7 +1,7 @@
+++
tags = ["documentation", "tutorial"]
title = "Tags"
weight = 8
weight = 7
+++
The Relearn theme supports one default taxonomy of Hugo: the *tag* feature.

View file

@ -1,6 +1,6 @@
+++
tags = ["documentat'n", "tutorrrial"]
title = "Tags"
weight = 8
weight = 7
+++
{{< piratify >}}

View file

@ -61,7 +61,7 @@ Be aware that if you use a multilingual website, you will need to have as many f
|:------------|:--------------|:------------|
| **style** | `transparent` | The color scheme used to highlight the box content.<br><br>- by severity: `info`, `note`, `tip`, `warning`<nd color: `primary`, `secondary`<br>- by color: `blue`, `green`, `grey`, `orange`, `red`<br>- by special color: `default`,t` |
| **title** | see notes | Arbitrary text for the box title. Depending on the **style** there may be a default title. Any given value will overwault.<br><br>- for severity styles: the matching title for the severity<br>- for all other colors: `Attachments`<br><br>If you wa you have to set this parameter to `" "` (a non empty string filled with spaces) |
| **icon** | see notes | [Font Awesome icon name]({{%relref "cont/icons#finding-an-icon" %}}) set to the left of the title. Depending le** there may be a default icon. Any given value will overwrite the default.<br><br>- for severity styles: a nice matching iseverity<br>- for all other colors: `paperclip`<br><br>If you want no icon, you have to set this parameter to `" "` (a non empty d with spaces) |
| **icon** | see notes | [Font Awesome icon name]({{%relref "shortcodes/icon#finding-an-icon" %}}) set to the left of the title. Depending le** there may be a default icon. Any given value will overwrite the default.<br><br>- for severity styles: a nice matching iseverity<br>- for all other colors: `paperclip`<br><br>If you want no icon, you have to set this parameter to `" "` (a non empty d with spaces) |
| **sort** | `asc` | Sorting the output in `asc`ending or `desc`ending order. |
| **pattern** | `.*` | A [regular expressions](https://en.wikipedia.org/wiki/Regular_expression), used to filter the attachments by file name. For example:<br><br>- to match a file suffix of 'jpg', use `.*jpg` (not `*.jpg`)<br>- to match file names ending in `jpg` or `png`, use `.*(jpg\|png)` |

View file

@ -7,7 +7,7 @@ The `badge` shortcode displays little markers in your text with adjustable color
{{% badge %}}Important{{% /badge %}}
{{% badge style="primary" title="Version" %}}6.6.6{{% /badge %}}
{{% badge style="red" icon="skull-crossbones" %}}Captain{{% /badge %}}
{{% badge style="red" icon="angle-double-up" %}}Captain{{% /badge %}}
{{% badge style="info" %}}Awesome{{% /badge %}}
## Usage
@ -20,7 +20,7 @@ While the examples are using shortcodes with named parameter you are free to als
````go
{{%/* badge %}}Important{{% /badge */%}}
{{%/* badge style="primary" title="Version" %}}6.6.6{{% /badge */%}}
{{%/* badge style="red" icon="skull-crossbones" %}}Captain{{% /badge */%}}
{{%/* badge style="red" icon="angle-double-up" %}}Captain{{% /badge */%}}
{{%/* badge style="info" %}}Awesome{{% /badge */%}}
````
@ -41,7 +41,7 @@ While the examples are using shortcodes with named parameter you are free to als
{{ partial "shortcodes/badge.html" (dict
"context" .
"style" "red"
"icon" "skull-crossbones"
"icon" "angle-double-up"
"content" "Captain"
)}}
{{ partial "shortcodes/badge.html" (dict
@ -59,7 +59,7 @@ While the examples are using shortcodes with named parameter you are free to als
| Name | Default | Notes |
|:----------------------|:----------------|:------------|
| **style** | `default` | The color scheme used to paint the badge.<br><br>- by severity: `info`, `note`, `tip`, `warning`<br>- by brand color: `primary`, `secondary`<br>- by color: `blue`, `green`, `grey`, `orange`, `red`<br>- by special color: `default`, `transparent` |
| **icon** | see notes | [Font Awesome icon name]({{%relref "cont/icons#finding-an-icon" %}}) set to the left of the title. Depending on the **style** there may be a default icon. Any given value will overwrite the default.<br><br>- for severity styles: a nice matching icon for the severity<br>- for all other colors: _&lt;empty&gt;_<br><br>If you want no icon for a severity style, you have to set this parameter to `" "` (a non empty string filled with spaces) |
| **icon** | see notes | [Font Awesome icon name]({{%relref "shortcodes/icon#finding-an-icon" %}}) set to the left of the title. Depending on the **style** there may be a default icon. Any given value will overwrite the default.<br><br>- for severity styles: a nice matching icon for the severity<br>- for all other colors: _&lt;empty&gt;_<br><br>If you want no icon for a severity style, you have to set this parameter to `" "` (a non empty string filled with spaces) |
| **title** | see notes | Arbitrary text for the badge title. Depending on the **style** there may be a default title. Any given value will overwrite the default.<br><br>- for severity styles: the matching title for the severity<br>- for all other colors: _&lt;empty&gt;_<br><br>If you want no title for a severity style, you have to set this parameter to `" "` (a non empty string filled with spaces) |
| _**&lt;content&gt;**_ | _&lt;empty&gt;_ | Arbitrary text for the badge. |
@ -148,24 +148,24 @@ While the examples are using shortcodes with named parameter you are free to als
````go
{{%/* badge icon="star" %}}6.6.6{{% /badge */%}}
{{%/* badge style="info" title=" " %}}Awesome{{% /badge */%}}
{{%/* badge style="red" icon="skull-crossbones" %}}Captain{{% /badge */%}}
{{%/* badge style="red" icon="angle-double-up" %}}Captain{{% /badge */%}}
````
{{% badge icon="star" %}}6.6.6{{% /badge %}}
{{% badge style="info" title=" " %}}Awesome{{% /badge %}}
{{% badge style="red" icon="skull-crossbones" %}}Captain{{% /badge %}}
{{% badge style="red" icon="angle-double-up" %}}Captain{{% /badge %}}
#### All Set
````go
{{%/* badge icon="star" title="Version" %}}6.6.6{{% /badge */%}}
{{%/* badge style="info" %}}Awesome{{% /badge */%}}
{{%/* badge style="red" icon="skull-crossbones" title="Rank" %}}Captain{{% /badge */%}}
{{%/* badge style="red" icon="angle-double-up" title="Rank" %}}Captain{{% /badge */%}}
````
{{% badge icon="star" title="Version" %}}6.6.6{{% /badge %}}
{{% badge style="info" %}}Awesome{{% /badge %}}
{{% badge style="red" icon="skull-crossbones" title="Rank" %}}Captain{{% /badge %}}
{{% badge style="red" icon="angle-double-up" title="Rank" %}}Captain{{% /badge %}}
#### Override for Severity
@ -177,6 +177,24 @@ While the examples are using shortcodes with named parameter you are free to als
### Other
#### With Icon Content
You can combine the badge with the [`icon` shortcode]({{% relref "shortcodes/icon" %}}) to create even more stunning variants.
In this case you need to declare `{{</* badge */>}}` instead of `{{%/* badge */%}}`. Note, that in this case it is not possible to put markdown in the content.
````go
{{</* badge style="primary" title="Rank" >}}{{% icon skull-crossbones %}}{{< /badge */>}}
{{</* badge style="primary" title="Rank" >}}{{% icon skull-crossbones %}} Pirate{{< /badge */>}}
````
{{< badge style="primary" icon="angle-double-up" >}}{{% icon skull-crossbones %}}{{< /badge >}}
{{< badge style="primary" icon="angle-double-up" >}}{{% icon skull-crossbones %}} Pirate{{< /badge >}}
{{< badge style="primary" title="Rank" >}}{{% icon skull-crossbones %}}{{< /badge >}}
{{< badge style="primary" title="Rank" >}}{{% icon skull-crossbones %}} Pirate{{< /badge >}}
{{< badge style="primary" icon="angle-double-up" title="Rank" >}}{{% icon skull-crossbones %}}{{< /badge >}}
{{< badge style="primary" icon="angle-double-up" title="Rank" >}}{{% icon skull-crossbones %}} Pirate{{< /badge >}}
#### Inside of Text
````go

View file

@ -1,5 +1,5 @@
+++
descrption = "Nice buttons on yer plank"
title = "Button"
descrption = "Marker badges t' display 'n yer text"
title = "Badge"
+++
{{< piratify >}}

View file

@ -49,7 +49,7 @@ Once the button is clicked, it opens another browser tab for the given URL.
|:----------------------|:----------------|:------------|
| **href** | _&lt;empty&gt;_ | Either the destination URL for the button or JavaScript code to be executed on click. If this parameter is not set, the button will do nothing but is still displayed as clickable.<br><br>- if starting with `javascript:` all following text will be executed in your browser<br>- every other string will be interpreted as URL|
| **style** | `transparent` | The color scheme used to paint the button.<br><br>- by severity: `info`, `note`, `tip`, `warning`<br>- by brand color: `primary`, `secondary`<br>- by color: `blue`, `green`, `grey`, `orange`, `red`<br>- by special color: `default`, `transparent` |
| **icon** | see notes | [Font Awesome icon name]({{%relref "cont/icons#finding-an-icon" %}}) set to the left of the title. Depending on the **style** there may be a default icon. Any given value will overwrite the default.<br><br>- for severity styles: a nice matching icon for the severity<br>- for all other colors: _&lt;empty&gt;_<br><br>If you want no icon for a severity style, you have to set this parameter to `" "` (a non empty string filled with spaces) |
| **icon** | see notes | [Font Awesome icon name]({{%relref "shortcodes/icon#finding-an-icon" %}}) set to the left of the title. Depending on the **style** there may be a default icon. Any given value will overwrite the default.<br><br>- for severity styles: a nice matching icon for the severity<br>- for all other colors: _&lt;empty&gt;_<br><br>If you want no icon for a severity style, you have to set this parameter to `" "` (a non empty string filled with spaces) |
| **iconposition** | `left` | Places the icon to the `left` or `right` of the title. |
| **target** | see notes | The destination frame/window if **href** is an URL. Otherwise the parameter is not used. This behaves similar to normal links. If the parameter is not given it defaults to:<br><br>- `_blank` for any address starting with `http://` or `https://`<br>- no specific value for all other links |
| **type** | see notes | The [button type](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#attr-type) if **href** is JavaScript. Otherwise the parameter is not used. If the parameter is not given it defaults to `button` |

View file

@ -0,0 +1,99 @@
+++
aliases = "/en/cont/icons"
description = "Nice icons for your page"
title = "Icon"
+++
The `icon` shortcode displays icons in your text.
The theme uses the [**Font Awesome**](https://fontawesome.com) library, allowing you to easily display any icon or logo available in the Font Awesome free collection.
{{% icon exclamation-triangle %}}
{{% icon angle-double-up %}}
{{% icon skull-crossbones %}}
## Usage
While the examples are using shortcodes with positional parameter you are free to also call this shortcode from your own partials.
{{< tabs groupId="shortcode-parameter">}}
{{% tab name="shortcode" %}}
````go
{{%/* icon icon="exclamation-triangle" */%}}
{{%/* icon icon="angle-double-up" */%}}
{{%/* icon icon="skull-crossbones" */%}}
````
{{% /tab %}}
{{% tab name="shortcode (positional)" %}}
````go
{{%/* icon exclamation-triangle */%}}
{{%/* icon angle-double-up */%}}
{{%/* icon skull-crossbones */%}}
````
{{% /tab %}}
{{% tab name="partial" %}}
````go
{{ partial "shortcodes/icon.html" (dict
"context" .
"icon" "exclamation-triangle"
)}}
{{ partial "shortcodes/icon.html" (dict
"context" .
"icon" "angle-double-up"
)}}
{{ partial "shortcodes/icon.html" (dict
"context" .
"icon" "skull-crossbones"
)}}
````
{{% /tab %}}
{{< /tabs >}}
### Parameter
| Name | Position | Default | Notes |
|:----------------------|:---------|:----------------|:------------|
| **icon** | 1 | _&lt;empty&gt;_ | [Font Awesome icon name]({{%relref "#finding-an-icon" %}}) to be displayed. It will be displayed in the text color of its according context. |
## Finding an icon
Browse through the available icons in the [Font Awesome Gallery](https://fontawesome.com/v5/search?m=free). Notice that the **free** filter is enabled, as only the free icons are available by default.
Once on the Font Awesome page for a specific icon, for example the page for the [heart](https://fontawesome.com/v5/icons/heart?s=solid), copy the icon name and paste into the Markdown content.
## Customising Icons
Font Awesome provides many ways to modify the icon
- Change color (by default the icon will inherit the parent color)
- Increase or decrease size
- Rotate
- Combine with other icons
Check the full documentation on [web fonts with CSS](https://fontawesome.com/how-to-use/web-fonts-with-css) for more.
## Examples
### Standard Use
````go
Built with {{%/* icon heart */%}} by Relearn and Hugo
````
Built with {{% icon heart %}} by Relearn and Hugo
### Advanced HTML Usage
While the shortcode simplyfies using standard icons, the icon customisation and other advanced features of the Font Awesome library requires you to use HTML directly. Just paste the `<i>` HTML into markup and Font Awesome will load the relevant icon.
````html
Built with <i class="fas fa-heart"></i> by Relearn and Hugo
````
Built with <i class="fas fa-heart"></i> by Relearn and Hugo

View file

@ -0,0 +1,6 @@
+++
aliases = "/pir/cont/icons"
descrption = "Nice ay'cons fer yer plank"
title = "Icon"
+++
{{< piratify >}}

View file

@ -53,7 +53,7 @@ It is all about the boxes.
|:----------|:---------|:----------|:------------|
| **style** | 1 | `default` | The color scheme used to highlight the box content.<br><br>- by severity: `info`, `note`, `tip`, `warning`<br>- by brand color: `primary`, `secondary`<br>- by color: `blue`, `green`, `grey`, `orange`, `red`<br>- by special color: `default`, `transparent` |
| **title** | 2 | see notes | Arbitrary text for the box title. Depending on the **style** there may be a default title. Any given value will overwrite the default.<br><br>- for severity styles: the matching title for the severity<br>- for all other colors: _&lt;empty&gt;_<br><br>If you want no title for a severity style, you have to set this parameter to `" "` (a non empty string filled with spaces) |
| **icon** | 3 | see notes | [Font Awesome icon name]({{%relref "cont/icons#finding-an-icon" %}}) set to the left of the title. Depending on the **style** there may be a default icon. Any given value will overwrite the default.<br><br>- for severity styles: a nice matching icon for the severity<br>- for all other colors: _&lt;empty&gt;_<br><br>If you want no icon for a severity style, you have to set this parameter to `" "` (a non empty string filled with spaces) |
| **icon** | 3 | see notes | [Font Awesome icon name]({{%relref "shortcodes/icon#finding-an-icon" %}}) set to the left of the title. Depending on the **style** there may be a default icon. Any given value will overwrite the default.<br><br>- for severity styles: a nice matching icon for the severity<br>- for all other colors: _&lt;empty&gt;_<br><br>If you want no icon for a severity style, you have to set this parameter to `" "` (a non empty string filled with spaces) |
| _**&lt;content&gt;**_ | | _&lt;empty&gt;_ | Arbitrary text to be displayed in box. |
## Examples

View file

@ -0,0 +1,11 @@
{{- $context := .context }}
{{- $icon := .icon | default "" }}
{{- $icon = trim $icon " " }}
{{- if and $icon (not (findRE ".*?\\bfa-\\w.*?" $icon)) }}
{{- $icon = printf "fa-fw fas fa-%s" $icon }}
{{- end }}
{{- with $context }}
{{- if $icon }}
<i class="{{ $icon }}"></i>
{{- end }}
{{- end }}

View file

@ -0,0 +1,5 @@
{{- $_hugo_config := `{ "version": 1 }` }}
{{- partial "shortcodes/icon.html" (dict
"context" .
"icon" (.Get "icon" | default (.Get 0))
) }}

View file

@ -10,8 +10,9 @@ features = ["badges", "breadcrumbs", "boxes", "buttons",
"dark", "docs", "documentation",
"expand",
"favicon", "file inclusion", "file system support", "font awesome",
"gfm",
"hidden pages",
"i18n", "ie11", "image resizing", "include", "internet explorer",
"i18n", "icons", "ie11", "image resizing", "include", "internet explorer",
"light", "lightbox", "logo",
"math", "mathjax", "menu", "mermaid", "multilingual", "mobile",
"nested sections", "notice",