icon: add new shortcode #412

exampleSite/content/_index.en.md

@@ -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" %}})

exampleSite/content/basics/migration/_index.en.md

@@ -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" %}}).
 
 ---
 

exampleSite/content/cont/i18n/_index.en.md

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

exampleSite/content/cont/i18n/_index.pir.md

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

exampleSite/content/cont/icons.en.md

@@ -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.

exampleSite/content/cont/icons.pir.md

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

exampleSite/content/cont/markdown.en.md

@@ -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

exampleSite/content/cont/tags.en.md

@@ -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.

exampleSite/content/cont/tags.pir.md

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

exampleSite/content/shortcodes/attachments.en.md

@@ -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)` |
 

exampleSite/content/shortcodes/badge.en.md

@@ -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

exampleSite/content/shortcodes/badge.pir.md

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

exampleSite/content/shortcodes/button.en.md

@@ -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` |

exampleSite/content/shortcodes/icon.en.md

@@ -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

exampleSite/content/shortcodes/icon.pir.md

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

exampleSite/content/shortcodes/notice.en.md

@@ -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

layouts/partials/shortcodes/icon.html

@@ -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 }}

layouts/shortcodes/icon.html

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

theme.toml

@@ -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",