docs: move exampleSite to docs #1003

2025-05-24 10:44:12 +00:00 · 2025-01-29 23:30:53 +01:00 · 2025-01-29 23:30:53 +01:00 · db9ca5d295
commit db9ca5d295
parent df03dac58f
827 changed files with 656 additions and 652 deletions
--- a/docs/content/shortcodes/_index.en.md
+++ b/docs/content/shortcodes/_index.en.md
@ -0,0 +1,18 @@
+++
+categories = ["reference"]
+menuPre = "<i class='fa-fw fas fa-shapes'></i> "
+ordersectionsby = "title"
+title = "Shortcodes"
+type = "chapter"
+weight = 4
+++
+
+Hugo uses Markdown as its content format. However, there are a lot of things that Markdown doesn't support well.
+
+You could use pure HTML to expand your possibilities. But this happens to be a bad idea. Everyone uses Markdown because it's pure and simple to read. You should avoid HTML to keep it as simple and portable as possible.
+
+To avoid Markdown's limitations, Hugo created [shortcodes](https://gohugo.io/content-management/shortcodes/). A shortcode is a simple snippet inside of a page.
+
+The Relearn theme provides many shortcodes on top of [Hugo's existing ones](https://gohugo.io/content-management/shortcodes/#embedded-shortcodes).
+
+{{% children containerstyle="div" style="h2" description=true %}}
--- a/docs/content/shortcodes/_index.pir.md
+++ b/docs/content/shortcodes/_index.pir.md
@ -0,0 +1,9 @@
+++
+categories = ["reference"]
+menuPre = "<i class='fa-fw fas fa-shapes'></i> "
+ordersectionsby = "title"
+title = "Shorrrtcodes"
+type = "chapter"
+weight = 4
+++
+{{< piratify >}}
--- a/docs/content/shortcodes/attachments/index.en.files/BachGavotteShort.mp3
+++ b/docs/content/shortcodes/attachments/index.en.files/BachGavotteShort.mp3
--- a/docs/content/shortcodes/attachments/index.en.files/Carroll_AliceAuPaysDesMerveilles.pdf
+++ b/docs/content/shortcodes/attachments/index.en.files/Carroll_AliceAuPaysDesMerveilles.pdf
--- a/docs/content/shortcodes/attachments/index.en.files/adivorciarsetoca00cape.pdf
+++ b/docs/content/shortcodes/attachments/index.en.files/adivorciarsetoca00cape.pdf
--- a/docs/content/shortcodes/attachments/index.en.files/hugo.png
+++ b/docs/content/shortcodes/attachments/index.en.files/hugo.png
--- a/docs/content/shortcodes/attachments/index.en.files/hugo.txt
+++ b/docs/content/shortcodes/attachments/index.en.files/hugo.txt
@ -0,0 +1 @@
+This is a small text
--- a/docs/content/shortcodes/attachments/index.en.files/movieselectricsheep-flock-244-32500-2.mp4
+++ b/docs/content/shortcodes/attachments/index.en.files/movieselectricsheep-flock-244-32500-2.mp4
--- a/docs/content/shortcodes/attachments/index.en.md
+++ b/docs/content/shortcodes/attachments/index.en.md
@ -0,0 +1,116 @@
+++
+categories = ["howto", "reference"]
+description = "List of files attached to a page"
+hidden = "true"
+title = "Attachments"
+++
+
+{{% notice warning %}}
+This shortcode is deprecated in favor of the new [`resources` shortcode](shortcodes/resources). See [migration instructions](#migration) below.
+
+The examples on this page were removed.
+{{% /notice %}}
+
+The `attachments` shortcode displays a list of files attached to a page with adjustable color, title and icon.
+
+## Migration
+
+While this shortcode will still be available for some time, it does not receive support anymore. Start to migrate early, as it will be removed with the next major update of the theme.
+
+The [`resources` shortcode](shortcodes/resources) leverages Hugo's resource feature for page bundles. It has all the same parameter as the `attachments` shortcode but applies the `pattern` directly on a resources `Name` attribute.
+
+To migrate your pages apply the following steps:
+
+1. If a page is not already a [page bundle](https://gohugo.io/content-management/page-bundles/) convert it
+2. Move your files to a valid destination inside of your page bundle (depending if you have a branch or a leaf bundle)
+3. Change the calls from the `attachments` shortcode to the [`resources` shortcode](shortcodes/resources) and adjust the `pattern` parameter to the new directory layout and the resources [`Name` attribute](https://gohugo.io/methods/resource/name/).
+
+Multilanguage features are not supported directly by the shortcode anymore but rely on Hugo's handling for resource translations.
+
+## Usage
+
+While the examples are using shortcodes with named parameter you are free to also call this shortcode from your own partials.
+
+{{< tabs groupid="shortcode-parameter">}}
+{{% tab title="shortcode" %}}
+
+````go
+{{%/* attachments sort="asc" /*/%}}
+````
+
+{{% /tab %}}
+{{% tab title="partial" %}}
+
+````go
+{{ partial "shortcodes/attachments.html" (dict
+  "page" .
+  "sort" "asc"
+)}}
+````
+
+{{% /tab %}}
+{{< /tabs >}}
+
+### Parameter
+
+| Name        | Default         | Notes       |
+|-------------|-----------------|-------------|
+| **style**   | `transparent`   | The style scheme used for the box.<br><br>- by severity: `caution`, `important`, `info`, `note`, `tip`, `warning`<br>- by brand color: `primary`, `secondary`, `accent`<br>- by color: `blue`, `cyan`, `green`, `grey`, `magenta`, `orange`, `red`<br>- by special color: `default`, `transparent`, `code`<br><br>You can also [define your own styles](shortcodes/notice#defining-own-styles). |
+| **color**   | see notes       | The [CSS color value](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value) to be used. If not set, the chosen color depends on the **style**. Any given value will overwrite the default.<br><br>- for severity styles: a nice matching color for the severity<br>- for all other styles: the corresponding color |
+| **title**   | 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 styles: `Attachments`<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**    | see notes       | [Font Awesome icon name](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 styles: `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)` |
+
+## Setup
+
+### Single language
+
+The shortcode lists files found in a specific directory. The name of the directory depends on your page type (either branch bundle, leaf bundle or page).
+
+1. If your page is a leaf bundle, attachments must be placed in a nested `index.files` directory, accordingly.
+
+    > * content
+    >   * _index.md
+    >   * page
+    >     * index.md
+    >     * **index.files**
+    >       * attachment.pdf
+
+2. If your page is a branch bundle, attachments must be placed in a nested `_index.files` directory, accordingly.
+
+    {{% badge style="warning" title=" " %}}Warning{{% /badge %}} This is only available for Hugo < `0.112.0`
+
+    > * content
+    >   * _index.md
+    >   * page
+    >     * _index.md
+    >     * **_index.files**
+    >       * attachment.pdf
+
+3. For simple pages, attachments must be placed in a directory named like your page and ending with `.files`.
+
+    {{% badge style="warning" title=" " %}}Warning{{% /badge %}} This is only available for Hugo < `0.112.0`
+
+    > * content
+    >   * _index.md
+    >   * **page.files**
+    >     * attachment.pdf
+    >   * page.md
+
+### Multilingual
+
+Be aware that if you use a multilingual website, you will need to have as many directories as languages and the language code must be part of the directory name.
+
+Eg. for a site in English and Piratish:
+
+  > * content
+  >   * index.en.md
+  >   * index.pir.md
+  >   * page
+  >     * index.en.md
+  >     * index.pir.md
+  >     * **index.en.files**
+  >       * attachment.pdf
+  >     * **index.pir.files**
+  >       * attachment.pdf
--- a/docs/content/shortcodes/attachments/index.pir.files/NoTreasure.txt
+++ b/docs/content/shortcodes/attachments/index.pir.files/NoTreasure.txt
@ -0,0 +1 @@
+Harrr, nothn' to see herre
--- a/docs/content/shortcodes/attachments/index.pir.md
+++ b/docs/content/shortcodes/attachments/index.pir.md
@ -0,0 +1,7 @@
+++
+categories = ["howto", "reference"]
+description = "Th' Attachments shorrrtcode displays a list o' files attached t' a plank"
+hidden = "true"
+title = "Attachments"
+++
+{{< piratify >}}
--- a/docs/content/shortcodes/badge.en.md
+++ b/docs/content/shortcodes/badge.en.md
@ -0,0 +1,234 @@
+++
+categories = ["howto", "reference"]
+description = "Marker badges to display in your text"
+title = "Badge"
+++
+
+The `badge` shortcode displays little markers in your text with adjustable color, title and icon.
+
+{{% badge %}}Important{{% /badge %}}
+{{% badge style="primary" title="Version" %}}6.6.6{{% /badge %}}
+{{% badge style="red" icon="angle-double-up" %}}Captain{{% /badge %}}
+{{% badge style="info" %}}New{{% /badge %}}
+{{% badge color="fuchsia" icon="fa-fw fab fa-hackerrank" %}}Awesome{{% /badge %}}
+
+## Usage
+
+{{< tabs groupid="shortcode-parameter">}}
+{{% tab title="shortcode" %}}
+
+````go
+{{%/* badge %}}Important{{% /badge */%}}
+{{%/* badge style="primary" title="Version" %}}6.6.6{{% /badge */%}}
+{{%/* badge style="red" icon="angle-double-up" %}}Captain{{% /badge */%}}
+{{%/* badge style="info" %}}New{{% /badge */%}}
+{{%/* badge color="fuchsia" icon="fa-fw fab fa-hackerrank" %}}Awesome{{% /badge */%}}
+````
+
+{{% /tab %}}
+{{% tab title="partial" %}}
+
+````go
+{{ partial "shortcodes/badge.html" (dict
+    "page"    .
+    "content" "Important"
+)}}
+{{ partial "shortcodes/badge.html" (dict
+  "page"  .
+  "style" "primary"
+  "title" "Version"
+  "content" "6.6.6"
+)}}
+{{ partial "shortcodes/badge.html" (dict
+  "page"  .
+  "style" "red"
+  "icon"  "angle-double-up"
+  "content" "Captain"
+)}}
+{{ partial "shortcodes/badge.html" (dict
+  "page"  .
+  "style" "info"
+  "content" "New"
+)}}
+{{ partial "shortcodes/badge.html" (dict
+  "page"  .
+  "color" "fuchsia"
+  "icon"  "fab fa-hackerrank"
+  "content" "Awesome"
+)}}
+````
+
+{{% /tab %}}
+{{< /tabs >}}
+
+### Parameter
+
+| Name                  | Default         | Notes       |
+|-----------------------|-----------------|-------------|
+| **style**             | `default`       | The style scheme used for the badge.<br><br>- by severity: `caution`, `important`, `info`, `note`, `tip`, `warning`<br>- by brand color: `primary`, `secondary`, `accent`<br>- by color: `blue`, `cyan`, `green`, `grey`, `magenta`, `orange`, `red`<br>- by special color: `default`, `transparent`, `code`<br><br>You can also [define your own styles](shortcodes/notice#defining-own-styles). |
+| **color**             | see notes       | The [CSS color value](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value) to be used. If not set, the chosen color depends on the **style**. Any given value will overwrite the default.<br><br>- for severity styles: a nice matching color for the severity<br>- for all other styles: the corresponding color |
+| **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 styles: _&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**              | see notes       | [Font Awesome icon name](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 styles: _&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 for the badge. |
+
+## Examples
+
+### Style
+
+#### By Severity
+
+````go
+{{%/* badge style="caution" %}}Magenta{{% /badge */%}}
+{{%/* badge style="important" %}}Cyan{{% /badge */%}}
+{{%/* badge style="info" %}}Blue{{% /badge */%}}
+{{%/* badge style="note" %}}Orange{{% /badge */%}}
+{{%/* badge style="tip" %}}Green{{% /badge */%}}
+{{%/* badge style="warning" %}}Red{{% /badge */%}}
+````
+
+{{% badge style="caution" %}}Magenta{{% /badge %}}
+{{% badge style="important" %}}Cyan{{% /badge %}}
+{{% badge style="info" %}}Blue{{% /badge %}}
+{{% badge style="note" %}}Orange{{% /badge %}}
+{{% badge style="tip" %}}Green{{% /badge %}}
+{{% badge style="warning" %}}Red{{% /badge %}}
+
+#### By Brand Colors
+
+````go
+{{%/* badge style="primary" icon="bullhorn" title="Announcement" %}}Mandatory{{% /badge */%}}
+{{%/* badge style="secondary" icon="bullhorn" title="Announcement" %}}Optional{{% /badge */%}}
+{{%/* badge style="accent" icon="bullhorn" title="Announcement" %}}Special{{% /badge */%}}
+````
+
+{{% badge style="primary" icon="bullhorn" title="Announcement" %}}Mandatory{{% /badge %}}
+{{% badge style="secondary" icon="bullhorn" title="Announcement" %}}Optional{{% /badge %}}
+{{% badge style="accent" icon="bullhorn" title="Announcement" %}}Special{{% /badge %}}
+
+#### By Color
+
+````go
+{{%/* badge style="blue" icon="palette" title="Color" %}}Blue{{% /badge */%}}
+{{%/* badge style="cyan" icon="palette" title="Color" %}}Cyan{{% /badge */%}}
+{{%/* badge style="green" icon="palette" title="Color" %}}Green{{% /badge */%}}
+{{%/* badge style="grey" icon="palette" title="Color" %}}Grey{{% /badge */%}}
+{{%/* badge style="magenta" icon="palette" title="Color" %}}Magenta{{% /badge */%}}
+{{%/* badge style="orange" icon="palette" title="Color" %}}Orange{{% /badge */%}}
+{{%/* badge style="red" icon="palette" title="Color" %}}Red{{% /badge */%}}
+````
+
+{{% badge style="blue" icon="palette" title="Color" %}}Blue{{% /badge %}}
+{{% badge style="cyan" icon="palette" title="Color" %}}Cyan{{% /badge %}}
+{{% badge style="green" icon="palette" title="Color" %}}Green{{% /badge %}}
+{{% badge style="grey" icon="palette" title="Color" %}}Grey{{% /badge %}}
+{{% badge style="magenta" icon="palette" title="Color" %}}Magenta{{% /badge %}}
+{{% badge style="orange" icon="palette" title="Color" %}}Orange{{% /badge %}}
+{{% badge style="red" icon="palette" title="Color" %}}Red{{% /badge %}}
+
+#### By Special Color
+
+````go
+{{%/* badge style="default" icon="palette" title="Color" %}}Default{{% /badge */%}}
+{{%/* badge style="transparent" icon="palette" title="Color" %}}Transparent{{% /badge */%}}
+````
+
+{{% badge style="default" icon="palette" title="Color" %}}Default{{% /badge %}}
+{{% badge style="transparent" icon="palette" title="Color" %}}Transparent{{% /badge %}}
+
+### Variants
+
+#### Without Icon and Title Text
+
+````go
+{{%/* badge %}}6.6.6{{% /badge */%}}
+{{%/* badge style="info" icon=" " title=" " %}}Awesome{{% /badge */%}}
+{{%/* badge style="red" %}}Captain{{% /badge */%}}
+````
+
+{{% badge %}}6.6.6{{% /badge %}}
+{{% badge style="info" icon=" " title=" " %}}Awesome{{% /badge %}}
+{{% badge style="red" %}}Captain{{% /badge %}}
+
+#### Without Icon
+
+````go
+{{%/* badge title="Version" %}}6.6.6{{% /badge */%}}
+{{%/* badge style="info" icon=" " %}}Awesome{{% /badge */%}}
+{{%/* badge style="red" title="Rank" %}}Captain{{% /badge */%}}
+````
+
+{{% badge title="Version" %}}6.6.6{{% /badge %}}
+{{% badge style="info" icon=" " %}}Awesome{{% /badge %}}
+{{% badge style="red" title="Rank" %}}Captain{{% /badge %}}
+
+#### Without Title Text
+
+````go
+{{%/* badge icon="star" %}}6.6.6{{% /badge */%}}
+{{%/* badge style="info" title=" " %}}Awesome{{% /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="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="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="angle-double-up" title="Rank" %}}Captain{{% /badge %}}
+
+#### Override for Severity
+
+````go
+{{%/* badge style="info" icon="rocket" title="Feature" %}}Awesome{{% /badge */%}}
+````
+
+{{% badge style="info" icon="rocket" title="Feature" %}}Awesome{{% /badge %}}
+
+### Other
+
+#### With User-Defined Color, Font Awesome Brand Icon and Markdown Title and Content
+
+````go
+{{%/* badge color="fuchsia" icon="fa-fw fab fa-hackerrank" title="**Font**" %}}**Awesome**{{% /badge */%}}
+````
+
+{{% badge color="fuchsia" icon="fa-fw fab fa-hackerrank" title="**Font**" %}}**Awesome**{{% /badge %}}
+
+#### With Icon Content
+
+You can combine the badge with the [`icon` shortcode](shortcodes/icon) to create even more stunning visuals.
+
+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" 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 */>}}
+````
+
+{{< 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
+Lorem ipsum dolor sit amet, graecis denique ei vel, at duo primis mandamus. {{%/* badge style="blue" icon="rocket" %}}Awesome{{% /badge */%}} Et legere ocurreret pri, animal tacimates complectitur ad cum. Cu eum inermis inimicus efficiendi. Labore officiis his ex, soluta officiis concludaturque ei qui, vide sensibus vim ad.
+````
+
+Lorem ipsum dolor sit amet, graecis denique ei vel, at duo primis mandamus. {{% badge style="blue" icon="rocket" %}}Awesome{{% /badge %}} Et legere ocurreret pri, animal tacimates complectitur ad cum. Cu eum inermis inimicus efficiendi. Labore officiis his ex, soluta officiis concludaturque ei qui, vide sensibus vim ad.
--- a/docs/content/shortcodes/badge.pir.md
+++ b/docs/content/shortcodes/badge.pir.md
@ -0,0 +1,6 @@
+++
+categories = ["howto", "reference"]
+description = "Marker badges t' display 'n yer text"
+title = "Badge"
+++
+{{< piratify >}}
--- a/docs/content/shortcodes/button.en.md
+++ b/docs/content/shortcodes/button.en.md
@ -0,0 +1,229 @@
+++
+categories = ["howto", "reference"]
+description = "Clickable buttons"
+title = "Button"
+++
+
+The `button` shortcode displays a clickable button with adjustable color, title and icon.
+
+{{% button href="https://gohugo.io/" %}}Get Hugo{{% /button %}}
+{{% button href="https://gohugo.io/" style="warning" icon="dragon" %}}Get Hugo{{% /button %}}
+
+## Usage
+
+{{< tabs groupid="shortcode-parameter">}}
+{{% tab title="shortcode" %}}
+
+````go
+{{%/* button href="https://gohugo.io/" %}}Get Hugo{{% /button */%}}
+{{%/* button href="https://gohugo.io/" style="warning" icon="dragon" %}}Get Hugo{{% /button */%}}
+````
+
+{{% /tab %}}
+{{% tab title="partial" %}}
+
+````go
+{{ partial "shortcodes/button.html" (dict
+    "page" .
+    "href" "https://gohugo.io/"
+    "content" "Get Hugo"
+)}}
+{{ partial "shortcodes/button.html" (dict
+  "page" .
+  "href" "https://gohugo.io/"
+  "style" "warning"
+  "icon" "dragon"
+  "content" "Get Hugo"
+)}}
+````
+
+{{% /tab %}}
+{{< /tabs >}}
+
+### Parameter
+
+| Name                  | Default         | Notes       |
+|-----------------------|-----------------|-------------|
+| **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 style scheme used for the button.<br><br>- by severity: `caution`, `important`, `info`, `note`, `tip`, `warning`<br>- by brand color: `primary`, `secondary`, `accent`<br>- by color: `blue`, `cyan`, `green`, `grey`, `magenta`, `orange`, `red`<br>- by special color: `default`, `transparent`, `code`<br><br>You can also [define your own styles](shortcodes/notice#defining-own-styles). |
+| **color**             | see notes       | The [CSS color value](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value) to be used. If not set, the chosen color depends on the **style**. Any given value will overwrite the default.<br><br>- for severity styles: a nice matching color for the severity<br>- for all other styles: the corresponding color |
+| **icon**              | see notes       | [Font Awesome icon name](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 styles: _&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>- the setting of `externalLinkTarget` or `_blank` if not set, 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` |
+| _**&lt;content&gt;**_ | see notes       | Arbitrary text for the button 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 styles: _&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) |
+
+## Examples
+
+### Style
+
+#### By Severity
+
+````go
+{{%/* button href="https://gohugo.io/" style="caution" %}}Get Hugo{{% /button */%}}
+{{%/* button href="https://gohugo.io/" style="important" %}}Get Hugo{{% /button */%}}
+{{%/* button href="https://gohugo.io/" style="info" %}}Get Hugo{{% /button */%}}
+{{%/* button href="https://gohugo.io/" style="note" %}}Get Hugo{{% /button */%}}
+{{%/* button href="https://gohugo.io/" style="tip" %}}Get Hugo{{% /button */%}}
+{{%/* button href="https://gohugo.io/" style="warning" %}}Get Hugo{{% /button */%}}
+````
+
+{{% button href="https://gohugo.io/" style="caution" %}}Get Hugo{{% /button %}}
+{{% button href="https://gohugo.io/" style="important" %}}Get Hugo{{% /button %}}
+{{% button href="https://gohugo.io/" style="info" %}}Get Hugo{{% /button %}}
+{{% button href="https://gohugo.io/" style="note" %}}Get Hugo{{% /button %}}
+{{% button href="https://gohugo.io/" style="tip" %}}Get Hugo{{% /button %}}
+{{% button href="https://gohugo.io/" style="warning" %}}Get Hugo{{% /button %}}
+
+
+#### By Brand Colors
+
+````go
+{{%/* button href="https://gohugo.io/" style="primary" %}}Get Hugo{{% /button */%}}
+{{%/* button href="https://gohugo.io/" style="secondary" %}}Get Hugo{{% /button */%}}
+{{%/* button href="https://gohugo.io/" style="accent" %}}Get Hugo{{% /button */%}}
+````
+
+{{% button href="https://gohugo.io/" style="primary" %}}Get Hugo{{% /button %}}
+{{% button href="https://gohugo.io/" style="secondary" %}}Get Hugo{{% /button %}}
+{{% button href="https://gohugo.io/" style="accent" %}}Get Hugo{{% /button %}}
+
+#### By Color
+
+````go
+{{%/* button href="https://gohugo.io/" style="blue" %}}Get Hugo{{% /button */%}}
+{{%/* button href="https://gohugo.io/" style="cyan" %}}Get Hugo{{% /button */%}}
+{{%/* button href="https://gohugo.io/" style="green" %}}Get Hugo{{% /button */%}}
+{{%/* button href="https://gohugo.io/" style="grey" %}}Get Hugo{{% /button */%}}
+{{%/* button href="https://gohugo.io/" style="magenta" %}}Get Hugo{{% /button */%}}
+{{%/* button href="https://gohugo.io/" style="orange" %}}Get Hugo{{% /button */%}}
+{{%/* button href="https://gohugo.io/" style="red" %}}Get Hugo{{% /button */%}}
+````
+
+{{% button href="https://gohugo.io/" style="blue" %}}Get Hugo{{% /button %}}
+{{% button href="https://gohugo.io/" style="cyan" %}}Get Hugo{{% /button %}}
+{{% button href="https://gohugo.io/" style="green" %}}Get Hugo{{% /button %}}
+{{% button href="https://gohugo.io/" style="grey" %}}Get Hugo{{% /button %}}
+{{% button href="https://gohugo.io/" style="magenta" %}}Get Hugo{{% /button %}}
+{{% button href="https://gohugo.io/" style="orange" %}}Get Hugo{{% /button %}}
+{{% button href="https://gohugo.io/" style="red" %}}Get Hugo{{% /button %}}
+
+#### By Special Color
+
+````go
+{{%/* button href="https://gohugo.io/" style="default" %}}Get Hugo{{% /button */%}}
+{{%/* button href="https://gohugo.io/" style="transparent" %}}Get Hugo{{% /button */%}}
+````
+
+{{% button href="https://gohugo.io/" style="default" %}}Get Hugo{{% /button %}}
+{{% button href="https://gohugo.io/" style="transparent" %}}Get Hugo{{% /button %}}
+
+### Icon
+
+#### Empty
+
+````go
+{{%/* button href="https://gohugo.io/" icon=" " %}}{{% /button */%}}
+````
+
+{{% button href="https://gohugo.io/" icon=" " %}}{{% /button %}}
+
+#### Only
+
+````go
+{{%/* button href="https://gohugo.io/" icon="download" %}}{{% /button */%}}
+````
+
+{{% button href="https://gohugo.io/" icon="download" %}}{{% /button %}}
+
+#### To the Left
+
+````go
+{{%/* button href="https://gohugo.io/" icon="download" %}}Get Hugo{{% /button */%}}
+````
+
+{{% button href="https://gohugo.io/" icon="download" %}}Get Hugo{{% /button %}}
+
+#### To the Right
+
+````go
+{{%/* button href="https://gohugo.io/" icon="download" iconposition="right" %}}Get Hugo{{% /button */%}}
+````
+
+{{% button href="https://gohugo.io/" icon="download" iconposition="right" %}}Get Hugo{{% /button %}}
+
+#### Override for Severity
+
+````go
+{{%/* button href="https://gohugo.io/" icon="dragon" style="warning" %}}Get Hugo{{% /button */%}}
+````
+
+{{% button href="https://gohugo.io/" icon="dragon" style="warning" %}}Get Hugo{{% /button %}}
+
+### Target
+
+````go
+{{%/* button href="https://gohugo.io/" target="_self" %}}Get Hugo in same window{{% /button */%}}
+{{%/* button href="https://gohugo.io/" %}}Get Hugo in new Window/Frame (default){{% /button */%}}
+````
+{{% button href="https://gohugo.io/" target="_self" %}}Get Hugo in same Window/Frame{{% /button %}}
+{{% button href="https://gohugo.io/" %}}Get Hugo in new Window/Frame (default){{% /button %}}
+
+### Other
+
+#### With User-Defined Color, Font Awesome Brand Icon and Markdown Title
+
+````go
+{{%/* button href="https://gohugo.io/" color="fuchsia" icon="fa-fw fab fa-hackerrank" %}}Get **Hugo**{{% /button */%}}
+````
+
+{{% button href="https://gohugo.io/" color="fuchsia" icon="fa-fw fab fa-hackerrank" %}}Get **Hugo**{{% /button %}}
+
+#### Severity Style with All Defaults
+
+````go
+{{%/* button href="https://gohugo.io/" style="tip" %}}{{% /button */%}}
+````
+
+{{% button href="https://gohugo.io/" style="tip" %}}{{% /button %}}
+
+#### Button to Internal Page
+
+````go
+{{%/* button href="/index.html" %}}Home{{% /button */%}}
+````
+
+{{% button href="/index.html" %}}Home{{% /button %}}
+
+#### Button with JavaScript Action
+
+If your JavaScript action does not change the focus afterwards, make sure to call `this.blur()` in the end to unselect the button.
+
+````go
+{{%/* button style="primary" icon="bullhorn" href="javascript:alert('Hello world!');this.blur();" %}}Shout it out{{% /button */%}}
+````
+
+{{% button style="primary" icon="bullhorn" href="javascript:alert('Hello world!');this.blur();" %}}Shout it out{{% /button %}}
+
+#### Button within a `form` Element
+
+To use native HTML elements in your Markdown, add this in your `hugo.toml`
+
+````toml
+[markup.goldmark.renderer]
+    unsafe = true
+````
+
+````html
+<form action="../../search.html" method="get">
+  <input name="search-by-detail" class="search-by" type="search">
+  {{%/* button type="submit" style="secondary" icon="search" %}}Search{{% /button */%}}
+</form>
+````
+
+<form action="../../search.html" method="get">
+  <div class="searchform" style="width: 20vw;">
+    <input name="search-by-detail" class="search-by" type="search" placeholder="Search...">
+    {{% button type="submit" style="secondary" icon="search" %}}Search{{% /button %}}
+  </div>
+</form>
--- a/docs/content/shortcodes/button.pir.md
+++ b/docs/content/shortcodes/button.pir.md
@ -0,0 +1,6 @@
+++
+categories = ["howto", "reference"]
+description = "Clickable buttons"
+title = "Button"
+++
+{{< piratify >}}
--- a/docs/content/shortcodes/children/_index.en.md
+++ b/docs/content/shortcodes/children/_index.en.md
@ -0,0 +1,87 @@
+++
+alwaysopen = false
+categories = ["howto", "reference"]
+frontmatter = ["ordersectionsby"]
+options = ["ordersectionsby"]
+description = "List the child pages of a page"
+title = "Children"
+++
+
+The `children` shortcode lists the child pages of the current page and its descendants.
+
+{{% children sort="title" %}}
+
+## Usage
+
+{{< tabs groupid="shortcode-parameter">}}
+{{% tab title="shortcode" %}}
+
+````go
+{{%/* children sort="title" */%}}
+````
+
+{{% /tab %}}
+{{% tab title="partial" %}}
+
+````go
+{{ partial "shortcodes/children.html" (dict
+  "page" .
+  "sort" "title"
+)}}
+````
+
+{{% /tab %}}
+{{< /tabs >}}
+
+### Parameter
+
+| Name               | Default           | Notes       |
+|--------------------|-------------------|-------------|
+| **containerstyle** | `ul`              | Choose the style used to group all children. It could be any HTML tag name. |
+| **style**          | `li`              | Choose the style used to display each descendant. It could be any HTML tag name. |
+| **showhidden**     | `false`           | When `true`, child pages hidden from the menu will be displayed as well. |
+| **description**    | `false`           | When `true` shows a short text under each page in the list. When no description or summary exists for the page, the first 70 words of the content is taken - [read more info about summaries on gohugo.io](https://gohugo.io/content/summaries/). |
+| **depth**          | `1`               | The depth of descendants to display. For example, if the value is `2`, the shortcode will display two levels of child pages.  To get all descendants, set this value to a high  number eg. `999`. |
+| **sort**           | `auto`            | The sort criteria of the displayed list.<br><br>- `auto` defaults to `ordersectionsby` of the page's {{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}}<br>&nbsp;&nbsp;&nbsp;&nbsp;or to `ordersectionsby` of the configuration {{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}}<br>&nbsp;&nbsp;&nbsp;&nbsp;or to `weight`<br>- `weight`<br>- `title`<br>- `modifieddate`<br>- `expirydate`<br>- `publishdate`<br>- `date`<br>- `length`<br>- `default` adhering to Hugo's default sort criteria|
+
+## Examples
+
+### All Default
+
+````go
+{{%/* children */%}}
+````
+
+{{% children %}}
+
+### With Description
+
+````go
+{{%/* children description="true" */%}}
+````
+
+{{%children description="true" %}}
+
+### Infinite Depth and Hidden Pages
+
+````go
+{{%/* children depth="999" showhidden="true" */%}}
+````
+
+{{% children depth="999" showhidden="true" %}}
+
+### Heading Styles for Container and Elements
+
+````go
+{{%/* children containerstyle="div" style="h2" depth="3" description="true" */%}}
+````
+
+{{% children containerstyle="div" style="h2" depth="3" description="true" %}}
+
+### Divs for Group and Element Styles
+
+````go
+{{%/* children containerstyle="div" style="div" depth="3" */%}}
+````
+
+{{% children containerstyle="div" style="div" depth="3" %}}
--- a/docs/content/shortcodes/children/_index.pir.md
+++ b/docs/content/shortcodes/children/_index.pir.md
@ -0,0 +1,9 @@
+++
+alwaysopen = false
+categories = ["howto", "reference"]
+frontmatter = ["ordersectionsby"]
+options = ["ordersectionsby"]
+description = "List th' child planks on a plank"
+title = "Children"
+++
+{{< piratify >}}
--- a/docs/content/shortcodes/children/children-1/_index.en.md
+++ b/docs/content/shortcodes/children/children-1/_index.en.md
@ -0,0 +1,13 @@
+++
+alwaysopen = false
+description = "This is a demo child page"
+tags = ["children", "non-hidden"]
+title = "page 1"
+weight = 10
+++
+
+This is a demo child page.
+
+## Subpages of this page
+
+{{% children showhidden="true" %}}
--- a/docs/content/shortcodes/children/children-1/_index.pir.md
+++ b/docs/content/shortcodes/children/children-1/_index.pir.md
@ -0,0 +1,8 @@
+++
+alwaysopen = false
+description = "This be a demo child plank"
+tags = ["children", "non-hidden"]
+title = "plank 1"
+weight = 10
+++
+{{< piratify >}}
--- a/docs/content/shortcodes/children/children-1/children-1-1/_index.en.md
+++ b/docs/content/shortcodes/children/children-1/children-1-1/_index.en.md
@ -0,0 +1,12 @@
+++
+alwaysopen = true
+description = "This is a demo child page"
+tags = ["children", "non-hidden"]
+title = "page 1-1"
+++
+
+This is a demo child page with a hidden child. You can still access the hidden child [directly](shortcodes/children/children-1/children-1-1/children-1-1-1) or via the search.
+
+## Subpages of this page
+
+{{% children showhidden="true" %}}
--- a/docs/content/shortcodes/children/children-1/children-1-1/_index.pir.md
+++ b/docs/content/shortcodes/children/children-1/children-1-1/_index.pir.md
@ -0,0 +1,7 @@
+++
+alwaysopen = true
+description = "This be a demo child plank"
+tags = ["children", "non-hidden"]
+title = "plank 1-1"
+++
+{{< piratify >}}
--- a/docs/content/shortcodes/children/children-1/children-1-1/children-1-1-1/_index.en.md
+++ b/docs/content/shortcodes/children/children-1/children-1-1/children-1-1-1/_index.en.md
@ -0,0 +1,12 @@
+++
+description = "This is a hidden demo child page"
+hidden = true
+tags = ["children", "the hidden"]
+title = "page 1-1-1 (hidden)"
+++
+
+This is a **hidden** demo child page. This page and all its children are hidden in the menu, arrow navigation and children shortcode as long as you aren't viewing this page or its children directly.
+
+## Subpages of this page
+
+{{% children showhidden="true" %}}
--- a/docs/content/shortcodes/children/children-1/children-1-1/children-1-1-1/_index.pir.md
+++ b/docs/content/shortcodes/children/children-1/children-1-1/children-1-1-1/_index.pir.md
@ -0,0 +1,7 @@
+++
+description = "This be a hidden demo child plank"
+hidden = true
+tags = ["children", "the hidden"]
+title = "plank 1-1-1 (hidden)"
+++
+{{< piratify >}}
--- a/docs/content/shortcodes/children/children-1/children-1-1/children-1-1-1/children-1-1-1-1/_index.en.md
+++ b/docs/content/shortcodes/children/children-1/children-1-1/children-1-1-1/children-1-1-1-1/_index.en.md
@ -0,0 +1,11 @@
+++
+description = "This is a non-hidden demo child page of a hidden parent page"
+tags = ["children", "the hidden"]
+title = "page 1-1-1-1"
+++
+
+This is a **non-hidden** demo child page of a hidden parent page with a hidden child. You can still access the hidden child [directly](shortcodes/children/children-1/children-1-1/children-1-1-1/children-1-1-1-1/children-1-1-1-1-1) or via the search.
+
+## Subpages of this page
+
+{{% children showhidden="true" %}}
--- a/docs/content/shortcodes/children/children-1/children-1-1/children-1-1-1/children-1-1-1-1/_index.pir.md
+++ b/docs/content/shortcodes/children/children-1/children-1-1/children-1-1-1/children-1-1-1-1/_index.pir.md
@ -0,0 +1,6 @@
+++
+description = "This be a non-hidden demo child plank o' a hidden parrrent plank"
+tags = ["children", "the hidden"]
+title = "plank 1-1-1-1"
+++
+{{< piratify >}}
--- a/docs/content/shortcodes/children/children-1/children-1-1/children-1-1-1/children-1-1-1-1/children-1-1-1-1-1/_index.en.md
+++ b/docs/content/shortcodes/children/children-1/children-1-1/children-1-1-1/children-1-1-1-1/children-1-1-1-1-1/_index.en.md
@ -0,0 +1,12 @@
+++
+description = "This is a hidden demo child page"
+hidden = true
+tags = ["children", "the hidden"]
+title = "page 1-1-1-1-1 (hidden)"
+++
+
+This is a **hidden** demo child page. This page and all its children are hidden in the menu, arrow navigation and children shortcode as long as you aren't viewing this page or its children directly.
+
+## Subpages of this page
+
+{{% children showhidden="true" %}}
--- a/docs/content/shortcodes/children/children-1/children-1-1/children-1-1-1/children-1-1-1-1/children-1-1-1-1-1/_index.pir.md
+++ b/docs/content/shortcodes/children/children-1/children-1-1/children-1-1-1/children-1-1-1-1/children-1-1-1-1-1/_index.pir.md
@ -0,0 +1,7 @@
+++
+description = "This be a hidden demo child plank"
+hidden = true
+tags = ["children", "the hidden"]
+title = "plank 1-1-1-1-1 (hidden)"
+++
+{{< piratify >}}
--- a/docs/content/shortcodes/children/children-1/children-1-1/children-1-1-1/children-1-1-1-1/children-1-1-1-1-1/children-1-1-1-1-1-1/_index.en.md
+++ b/docs/content/shortcodes/children/children-1/children-1-1/children-1-1-1/children-1-1-1-1/children-1-1-1-1-1/children-1-1-1-1-1-1/_index.en.md
@ -0,0 +1,7 @@
+++
+description = "This is a non-hidden demo child page of a hidden parent page"
+tags = ["children", "the hidden"]
+title = "page 1-1-1-1-1-1"
+++
+
+This is a **non-hidden** demo child page of a hidden parent page.
--- a/docs/content/shortcodes/children/children-1/children-1-1/children-1-1-1/children-1-1-1-1/children-1-1-1-1-1/children-1-1-1-1-1-1/_index.pir.md
+++ b/docs/content/shortcodes/children/children-1/children-1-1/children-1-1-1/children-1-1-1-1/children-1-1-1-1-1/children-1-1-1-1-1-1/_index.pir.md
@ -0,0 +1,6 @@
+++
+description = "This be a non-hidden demo child plank on a hidden parrrent plank"
+tags = ["children", "the hidden"]
+title = "plank 1-1-1-1-1-1"
+++
+{{< piratify >}}
--- a/docs/content/shortcodes/children/children-1/children-1-1/children-1-1-2/_index.en.md
+++ b/docs/content/shortcodes/children/children-1/children-1-1/children-1-1-2/_index.en.md
@ -0,0 +1,15 @@
+++
+description = "This is a demo child page"
+tags = ["children", "headless", "non-hidden"]
+title = "page 1-1-2 (headless)"
+[_build]
+  render = "never"
+++
+
+This is a headless child page.
+
+While the heading is displayed in the theme for hierarchical views like the menu, the `children` shortcode, the chapter print feature and the breadcrumbs, its content will never be displayed and will not be accessible by search. Also its terms will not appear on the taxonomy pages.
+
+## Subpages of this page
+
+{{% children showhidden="true" %}}
--- a/docs/content/shortcodes/children/children-1/children-1-1/children-1-1-2/_index.pir.md
+++ b/docs/content/shortcodes/children/children-1/children-1-1/children-1-1-2/_index.pir.md
@ -0,0 +1,8 @@
+++
+description = "This be a demo child plank"
+tags = ["children", "headless", "non-hidden"]
+title = "plank 1-1-2 (headless)"
+[_build]
+  render = "never"
+++
+{{< piratify >}}
--- a/docs/content/shortcodes/children/children-1/children-1-1/children-1-1-2/children-1-1-2-1/_index.en.md
+++ b/docs/content/shortcodes/children/children-1/children-1-1/children-1-1-2/children-1-1-2-1/_index.en.md
@ -0,0 +1,7 @@
+++
+description = "This is a demo child page"
+tags = ["children", "non-hidden"]
+title = "page 1-1-2-1"
+++
+
+This is a plain demo child page 1-1-2-1.
--- a/docs/content/shortcodes/children/children-1/children-1-1/children-1-1-2/children-1-1-2-1/_index.pir.md
+++ b/docs/content/shortcodes/children/children-1/children-1-1/children-1-1-2/children-1-1-2-1/_index.pir.md
@ -0,0 +1,6 @@
+++
+description = "This be a demo child plank"
+tags = ["children", "non-hidden"]
+title = "plank 1-1-2-1"
+++
+{{< piratify >}}
--- a/docs/content/shortcodes/children/children-1/children-1-1/children-1-1-2/children-1-1-2-2/_index.en.md
+++ b/docs/content/shortcodes/children/children-1/children-1-1/children-1-1-2/children-1-1-2-2/_index.en.md
@ -0,0 +1,7 @@
+++
+description = "This is a demo child page"
+tags = ["children", "non-hidden"]
+title = "page 1-1-2-2"
+++
+
+This is a plain demo child page 1-1-2-2.
--- a/docs/content/shortcodes/children/children-1/children-1-1/children-1-1-2/children-1-1-2-2/_index.pir.md
+++ b/docs/content/shortcodes/children/children-1/children-1-1/children-1-1-2/children-1-1-2-2/_index.pir.md
@ -0,0 +1,6 @@
+++
+description = "This be a demo child plank"
+tags = ["children", "non-hidden"]
+title = "plank 1-1-2-2"
+++
+{{< piratify >}}
--- a/docs/content/shortcodes/children/children-1/children-1-1/children-1-1-3/_index.en.md
+++ b/docs/content/shortcodes/children/children-1/children-1-1/children-1-1-3/_index.en.md
@ -0,0 +1,7 @@
+++
+description = "This is a demo child page"
+tags = ["children", "non-hidden"]
+title = "page 1-1-3"
+++
+
+This is a plain demo child page 1-1-3.
--- a/docs/content/shortcodes/children/children-1/children-1-1/children-1-1-3/_index.pir.md
+++ b/docs/content/shortcodes/children/children-1/children-1-1/children-1-1-3/_index.pir.md
@ -0,0 +1,6 @@
+++
+description = "This be a demo child plank"
+tags = ["children", "non-hidden"]
+title = "plank 1-1-3"
+++
+{{< piratify >}}
--- a/docs/content/shortcodes/children/children-2/_index.en.md
+++ b/docs/content/shortcodes/children/children-2/_index.en.md
@ -0,0 +1,10 @@
+++
+alwaysopen = false
+tags = ["children", "non-hidden"]
+title = "page 2"
+weight = 20
+++
+
+This is a demo child page with no description.
+
+So its content is used as description.
--- a/docs/content/shortcodes/children/children-2/_index.pir.md
+++ b/docs/content/shortcodes/children/children-2/_index.pir.md
@ -0,0 +1,7 @@
+++
+alwaysopen = false
+tags = ["children", "non-hidden"]
+title = "plank 2"
+weight = 20
+++
+{{< piratify >}}
--- a/docs/content/shortcodes/children/children-3/_index.en.md
+++ b/docs/content/shortcodes/children/children-3/_index.en.md
@ -0,0 +1,13 @@
+++
+alwaysopen = false
+description = "This is a demo child page"
+tags = ["children", "non-hidden"]
+title = "page 3"
+weight = 30
+++
+
+This is a demo child page.
+
+## Subpages of this page
+
+{{% children showhidden="true" %}}
--- a/docs/content/shortcodes/children/children-3/_index.pir.md
+++ b/docs/content/shortcodes/children/children-3/_index.pir.md
@ -0,0 +1,8 @@
+++
+alwaysopen = false
+description = "This be a demo child plank"
+tags = ["children", "non-hidden"]
+title = "plank 3"
+weight = 30
+++
+{{< piratify >}}
--- a/docs/content/shortcodes/children/children-3/test3.en.md
+++ b/docs/content/shortcodes/children/children-3/test3.en.md
@ -0,0 +1,7 @@
+++
+description = "This is a plain page test nested in a parent"
+tags = ["children", "non-hidden"]
+title = "page 3-1"
+++
+
+This is a plain demo child page 3-1.
--- a/docs/content/shortcodes/children/children-3/test3.pir.md
+++ b/docs/content/shortcodes/children/children-3/test3.pir.md
@ -0,0 +1,6 @@
+++
+description = "This be a plain plank test nested 'n a parrrent"
+tags = ["children", "non-hidden"]
+title = "plank 3-1"
+++
+{{< piratify >}}
--- a/docs/content/shortcodes/children/children-4/_index.en.md
+++ b/docs/content/shortcodes/children/children-4/_index.en.md
@ -0,0 +1,10 @@
+++
+alwaysopen = false
+description = "This is a hidden demo child page"
+hidden = true
+tags = ["children", "the hidden"]
+title = "page 4 (hidden)"
+weight = 40
+++
+
+This is a **hidden** demo child page. This page and all its children are hidden in the menu, arrow navigation and children shortcode as long as you aren't viewing this page or its children directly.
--- a/docs/content/shortcodes/children/children-4/_index.pir.md
+++ b/docs/content/shortcodes/children/children-4/_index.pir.md
@ -0,0 +1,9 @@
+++
+alwaysopen = false
+description = "This be a hidden demo child plank"
+hidden = true
+tags = ["children", "the hidden"]
+title = "plank 4 (hidden)"
+weight = 40
+++
+{{< piratify >}}
--- a/docs/content/shortcodes/children/test.en.md
+++ b/docs/content/shortcodes/children/test.en.md
@ -0,0 +1,10 @@
+---
+description: |
+  This is a plain page test, and the beginning of a YAML multiline description...
+tags:
+  - "Children"
+title: "page X"
+weight: 1
+---
+
+This is a plain demo child page X.
--- a/docs/content/shortcodes/children/test.pir.md
+++ b/docs/content/shortcodes/children/test.pir.md
@ -0,0 +1,9 @@
+---
+description: |
+  This be a plain plank test, an' th' beginn'n o' a YAML multiline description…
+tags:
+  - "Children"
+title: "plank X"
+weight: 1
+---
+{{< piratify >}}
--- a/docs/content/shortcodes/expand.en.md
+++ b/docs/content/shortcodes/expand.en.md
@ -0,0 +1,127 @@
+++
+categories = ["howto", "reference"]
+description = "Expandable/collapsible sections of text"
+title = "Expand"
+++
+
+The `expand` shortcode displays an expandable/collapsible section of text.
+
+{{% expand title="Expand me..." %}}Thank you!
+
+That's some text with a footnote[^1]
+
+[^1]: And that's the footnote.
+
+That's some more text with a footnote.[^someid]
+
+[^someid]:
+    Anything of interest goes here.
+
+    Blue light glows blue.
+{{% /expand %}}
+
+## Usage
+
+{{< tabs groupid="shortcode-parameter">}}
+{{% tab title="callout" %}}
+
+````md
+> [!transparent]- Expand me...
+> Thank you!
+````
+
+{{% /tab %}}
+{{% tab title="shortcode" %}}
+
+````go
+{{%/* expand title="Expand me..." */%}}Thank you!{{%/* /expand */%}}
+````
+
+{{% /tab %}}
+{{% tab title="shortcode (positional)" %}}
+
+````go
+{{%/* expand "Expand me..." */%}}Thank you!{{%/* /expand */%}}
+````
+
+{{% /tab %}}
+{{% tab title="partial" %}}
+
+````go
+{{ partial "shortcodes/expand.html" (dict
+  "page"  .
+  "title" "Expand me..."
+  "content" "Thank you!"
+)}}
+````
+
+{{% /tab %}}
+{{< /tabs >}}
+
+[Extended callout syntax](https://gohugo.io/render-hooks/blockquotes/#extended-syntax) is available in other Markdown parsers like Obsidian and therefore is the recommend syntax for generating portable Markdown.
+
+The [`notice` shortcode](shortcodes/notice) is also capable of displaying expandable/collapsible sections of text but with additional parameter for color and additional icons.
+
+The theme supports Hugo’s built-in [`details` shortcode](https://gohugo.io/content-management/shortcodes/#details) by mapping the parameter to the theme's `expand` shortcode.
+
+### Parameter
+
+| Name                  | Position | Default          | Notes       |
+|-----------------------|----------|------------------|-------------|
+| **title**             | 1        | `"Expand me..."` | Arbitrary text to appear next to the expand/collapse icon. |
+| **expanded**          | 2        | `false`          | How the content is displayed.<br><br>- `true`: the content is initially shown<br>- `false`: the content is initially hidden |
+| _**&lt;content&gt;**_ |          | _&lt;empty&gt;_  | Arbitrary text to be displayed on expand. |
+
+## Examples
+
+### All Defaults
+
+````go
+{{%/* expand */%}}Yes, you did it!{{%/* /expand */%}}
+````
+
+{{% expand %}}Yes, you did it!{{% /expand %}}
+
+### Initially Expanded
+
+````go
+{{%/* expand title="Expand me..." expanded="true" */%}}No need to press you!{{%/* /expand */%}}
+````
+
+{{% expand title="Expand me..." expanded="true" %}}No need to press you!{{% /expand %}}
+
+### Arbitrary Text
+
+````go
+{{%/* expand title="Show me almost **endless** possibilities" */%}}
+You can add standard markdown syntax:
+
+- multiple paragraphs
+- bullet point lists
+- _emphasized_, **bold** and even **_bold emphasized_** text
+- [links](https://example.com)
+- etc.
+
+```plaintext
+...and even source code
+```
+
+> the possibilities are endless (almost - including other shortcodes may or may not work)
+{{%/* /expand */%}}
+````
+
+{{% expand title="Show me almost **endless** possibilities" %}}
+You can add standard markdown syntax:
+
+- multiple paragraphs
+- bullet point lists
+- _emphasized_, **bold** and even **_bold emphasized_** text
+- [links](https://example.com)
+- etc.
+
+```plaintext
+...and even source code
+```
+
+> the possibilities are endless (almost - including other shortcodes may or may not work)
+{{% /expand %}}
--- a/docs/content/shortcodes/expand.pir.md
+++ b/docs/content/shortcodes/expand.pir.md
@ -0,0 +1,6 @@
+++
+categories = ["howto", "reference"]
+description = "Expand'ble/collaps'ble sections of text"
+title = "Expand"
+++
+{{< piratify >}}
--- a/docs/content/shortcodes/highlight.en.md
+++ b/docs/content/shortcodes/highlight.en.md
@ -0,0 +1,215 @@
+++
+categories = ["howto", "reference"]
+description = "Render code with a syntax highlighter"
+frontmatter = ["highlightWrap"]
+options = ["disableHoverBlockCopyToClipBoard", "disableInlineCopyToClipBoard", "highlightWrap"]
+title = "Highlight"
+++
+
+The `highlight` shortcode renders your code with a syntax highlighter.
+
+{{< highlight lineNos="true" type="py" wrap="true" title="python" >}}
+print("Hello World!")
+{{< /highlight >}}
+
+## Usage
+
+{{< tabs groupid="shortcode-parameter">}}
+{{% tab title="codeodefence" %}}
+
+````md
+```py {lineNos="true" wrap="true" title="python"}
+print("Hello World!")
+```
+````
+
+{{% /tab %}}
+{{% tab title="shortcode" %}}
+
+````go
+{{</* highlight lineNos="true" type="py" wrap="true" title="python" */>}}
+print("Hello World!")
+{{</* /highlight */>}}
+````
+
+{{% /tab %}}
+{{% tab title="shortcode (positional)" %}}
+
+````go
+{{</* highlight py "lineNos=true,wrap=true,title=python" */>}}
+print("Hello World!")
+{{</* /highlight */>}}
+````
+
+{{% /tab %}}
+{{% tab title="partial" %}}
+
+````go
+{{ partial "shortcodes/highlight.html" (dict
+  "page"    .
+  "content" "print(\"Hello World!\")"
+  "lineNos" "true"
+  "type"    "py"
+  "wrap"    "true"
+  "title"   "python"
+)}}
+````
+
+{{% /tab %}}
+{{% tab title="partial (compat)" %}}
+
+````go
+{{ partial "shortcodes/highlight.html" (dict
+  "page"    .
+  "content" "print(\"Hello World!\")"
+  "options" "lineNos=true,wrap=true,title=python"
+  "type"    "py"
+)}}
+````
+
+{{% /tab %}}
+{{< /tabs >}}
+
+This shortcode is fully compatible with Hugo's [`highlight` shortcode](https://gohugo.io/content-management/syntax-highlighting/#highlight-shortcode) but **offers some extensions**.
+
+It is called interchangeably in the same way as Hugo's own shortcode by providing positional parameter or simply by using Markdown codefences.
+
+You are free to also call this shortcode from your own partials. In this case it resembles Hugo's [`highlight` function](https://gohugo.io/functions/highlight/) syntax if you call it using compatibility syntax.
+
+Codefence syntax is widely available in other Markdown parsers like GitHub and therefore is the recommend syntax for generating portable Markdown.
+
+The [`tab` shortcode](shortcodes/tab) is also capable of displaying code but with limited options.
+
+### Parameter
+
+| Name                  | Position | Default          | Notes       |
+|-----------------------|--------- | -----------------|-------------|
+| **type**              | 1        | _&lt;empty&gt;_  | The language of the code to highlight. Choose from one of the [supported languages](https://gohugo.io/content-management/syntax-highlighting/#list-of-chroma-highlighting-languages). Case-insensitive. |
+| **title**             |          | _&lt;empty&gt;_  | **Extension**. Arbitrary title for code. This displays the code like a [single tab](shortcodes/tab) if `hl_inline=false` (which is Hugo's default). |
+| **wrap**              |          | see notes        | **Extension**. When `true` the content may wrap on long lines otherwise it will be scrollable.<br><br>The default value can be set in your `hugo.toml` and overwritten via front matter. [See below](#setting-wrap-of-long-lines). |
+| **options**           | 2        | _&lt;empty&gt;_  | An optional, comma-separated list of zero or more [Hugo supported options](https://gohugo.io/functions/highlight/#options) as well as extension parameter from this table. |
+| _**&lt;option&gt;**_  |          | _&lt;empty&gt;_  | Any of [Hugo's supported options](https://gohugo.io/functions/highlight/#options). |
+| _**&lt;content&gt;**_ |          | _&lt;empty&gt;_  | Your code to highlight. |
+
+## Settings
+
+### Setting Default Values for Hugo's Options
+
+Default values for [Hugo's supported options](https://gohugo.io/functions/highlight/#options) can be set via [goldmark settings](https://gohugo.io/getting-started/configuration-markup/#highlight).
+
+If used together with wrapping of long lines, use this recommended settings. Otherwise, line numbers will shift if code wraps.
+
+{{< multiconfig file=hugo >}}
+[markup]
+  [markup.highlight]
+    lineNumbersInTable = false
+{{< /multiconfig >}}
+
+### Setting Wrap of Long Lines
+
+{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} {{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} By default, code will be wrapped if the line is not long enough.
+
+You can disable wrapping by setting `highlightWrap=false` or by setting the [`wrap` parameter](#parameter) individually for each code block.
+
+{{< multiconfig >}}
+highlightWrap=false
+{{< /multiconfig >}}
+
+### Copy to Clipboard for Inline Code
+
+{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} By default inline code has a button to copy the code to the clipboard.
+
+If you want to disable this feature, set `disableInlineCopyToClipBoard=true`.
+
+{{< multiconfig file=hugo >}}
+[params]
+  disableInlineCopyToClipBoard = true
+{{< /multiconfig >}}
+
+### Copy to Clipboard for Block Code
+
+{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} By default block code has a button to copy the code to the clipboard that is only visible on hover.
+
+Set `disableHoverBlockCopyToClipBoard=true` to disable the hover effect and always show the button.
+
+{{< multiconfig file=hugo >}}
+[params]
+  disableHoverBlockCopyToClipBoard = true
+{{< /multiconfig >}}
+
+### Setting a Specific Color Scheme
+
+You can configure the color style used for code blocks in your [color variants stylesheet](configuration/branding/modules#change-syntax-highlighting) file using the `--CODE-theme` variable. This requires further configuration as described in the above link.
+
+## Examples
+
+### Line Numbers with Starting Offset
+
+As mentioned above, line numbers in a `table` layout will shift if code is wrapping, so better use `inline`. To make things easier for you, set `lineNumbersInTable = false` in your `hugo.toml` and add `lineNos = true` when calling the shortcode instead of the specific values `table` or `inline`.
+
+````go
+{{</* highlight lineNos="true" lineNoStart="666" type="py" */>}}
+# the hardest part is to start writing code; here's a kickstart; just copy and paste this; it's free; the next lines will cost you serious credits
+print("Hello")
+print(" ")
+print("World")
+print("!")
+{{</* /highlight */>}}
+````
+
+{{< highlight lineNos="true" lineNoStart="666" type="py" >}}
+# the hardest part is to start writing code; here's a kickstart; just copy and paste this; it's free; the next lines will cost you serious credits
+print("Hello")
+print(" ")
+print("World")
+print("!")
+{{< /highlight >}}
+
+### Markdown Codefence with Title
+
+
+````md
+```py { title="python" }
+# a bit shorter
+print("Hello World!")
+```
+````
+
+```py { title="python" }
+# a bit shorter
+print("Hello World!")
+```
+
+
+
+### With Wrap
+
+````go
+{{</* highlight type="py" wrap="true" hl_lines="2" */>}}
+# Quicksort Python One-liner
+lambda L: [] if L==[] else qsort([x for x in L[1:] if x< L[0]]) + L[0:1] + qsort([x for x in L[1:] if x>=L[0]])
+# Some more stuff
+{{</* /highlight */>}}
+````
+
+{{< highlight type="py" wrap="true" hl_lines="2" >}}
+# Quicksort Python One-liner
+lambda L: [] if L==[] else qsort([x for x in L[1:] if x< L[0]]) + L[0:1] + qsort([x for x in L[1:] if x>=L[0]])
+# Some more stuff
+{{< /highlight >}}
+
+### Without Wrap
+
+````go
+{{</* highlight type="py" wrap="false" hl_lines="2" */>}}
+# Quicksort Python One-liner
+lambda L: [] if L==[] else qsort([x for x in L[1:] if x< L[0]]) + L[0:1] + qsort([x for x in L[1:] if x>=L[0]])
+# Some more stuff
+{{</* /highlight */>}}
+````
+
+{{< highlight type="py" wrap="false" hl_lines="2">}}
+# Quicksort Python One-liner
+lambda L: [] if L==[] else qsort([x for x in L[1:] if x< L[0]]) + L[0:1] + qsort([x for x in L[1:] if x>=L[0]])
+# Some more stuff
+{{< /highlight >}}
--- a/docs/content/shortcodes/highlight.pir.md
+++ b/docs/content/shortcodes/highlight.pir.md
@ -0,0 +1,8 @@
+++
+categories = ["howto", "reference"]
+description = "Render code with a syntax highlighter"
+frontmatter = ["highlightWrap"]
+options = ["disableHoverBlockCopyToClipBoard", "disableInlineCopyToClipBoard", "highlightWrap"]
+title = "Highlight"
+++
+{{< piratify >}}
--- a/docs/content/shortcodes/icon.en.md
+++ b/docs/content/shortcodes/icon.en.md
@ -0,0 +1,102 @@
+++
+categories = ["howto", "reference"]
+description = "Nice icons for your page"
+title = "Icon"
+++
+
+The `icon` shortcode displays icons using the [Font Awesome](https://fontawesome.com) library.
+
+{{% icon exclamation-triangle %}}
+{{% icon angle-double-up %}}
+{{% icon skull-crossbones %}}
+
+## Usage
+
+{{< tabs groupid="shortcode-parameter">}}
+{{% tab title="shortcode" %}}
+
+````go
+{{%/* icon icon="exclamation-triangle" */%}}
+{{%/* icon icon="angle-double-up" */%}}
+{{%/* icon icon="skull-crossbones" */%}}
+````
+
+{{% /tab %}}
+{{% tab title="shortcode (positional)" %}}
+
+````go
+{{%/* icon exclamation-triangle */%}}
+{{%/* icon angle-double-up */%}}
+{{%/* icon skull-crossbones */%}}
+````
+
+{{% /tab %}}
+{{% tab title="partial" %}}
+
+````go
+{{ partial "shortcodes/icon.html" (dict
+    "page" .
+    "icon" "exclamation-triangle"
+)}}
+{{ partial "shortcodes/icon.html" (dict
+    "page" .
+    "icon" "angle-double-up"
+)}}
+{{ partial "shortcodes/icon.html" (dict
+    "page" .
+    "icon" "skull-crossbones"
+)}}
+````
+
+{{% /tab %}}
+{{< /tabs >}}
+
+### Parameter
+
+| Name                  | Position | Default         | Notes       |
+|-----------------------|----------|-----------------|-------------|
+| **icon**              | 1        | _&lt;empty&gt;_ | [Font Awesome icon name](#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/v6/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/v6/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://docs.fontawesome.com/web/style/styling) for more.
+
+## Examples
+
+### Standard Usage
+
+````go
+Built with {{%/* icon heart */%}} by Relearn and Hugo
+````
+
+Built with {{% icon heart %}} by Relearn and Hugo
+
+### Advanced HTML Usage
+
+While the shortcode simplifies using standard icons, the icon customization and other advanced features of the Font Awesome library require you to use HTML directly. 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
+
+To use these native HTML elements in your Markdown, add this in your `hugo.toml`:
+
+````toml
+[markup.goldmark.renderer]
+    unsafe = true
+````
--- a/docs/content/shortcodes/icon.pir.md
+++ b/docs/content/shortcodes/icon.pir.md
@ -0,0 +1,6 @@
+++
+categories = ["howto", "reference"]
+description = "Nice ay'cons fer yer plank"
+title = "Icon"
+++
+{{< piratify >}}
--- a/docs/content/shortcodes/include/INCLUDE_ME.md
+++ b/docs/content/shortcodes/include/INCLUDE_ME.md
@ -0,0 +1,15 @@
+You can add standard markdown syntax:
+
+- multiple paragraphs
+- bullet point lists
+- _emphasized_, **bold** and even **_bold emphasized_** text
+- [links](https://example.com)
+- etc.[^etc]
+
+[^etc]: Et Cetera (English: /ɛtˈsɛtərə/), abbreviated to etc., etc, et cet., is a Latin expression that is used in English to mean "and other similar things", or "and so forth"
+
+```plaintext
+...and even source code
+```
+
+> the possibilities are endless (almost - including other shortcodes may or may not work) (almost - including other shortcodes may or may not work)
--- a/docs/content/shortcodes/include/index.en.md
+++ b/docs/content/shortcodes/include/index.en.md
@ -0,0 +1,73 @@
+++
+categories = ["howto", "reference"]
+description = "Displays content from other files"
+frontmatter = ["include.errorlevel"]
+options = ["include.errorlevel"]
+title = "Include"
+++
+
+The `include` shortcode includes other pages, resources or files from your project.
+
+## Usage
+
+{{< tabs groupid="shortcode-parameter">}}
+{{% tab title="shortcode" %}}
+
+````go
+{{%/* include file="shortcodes/include/INCLUDE_ME.md" */%}}
+````
+
+{{% /tab %}}
+{{% tab title="shortcode (positional)" %}}
+
+````go
+{{%/* include "shortcodes/include/INCLUDE_ME.md" */%}}
+````
+
+{{% /tab %}}
+{{% tab title="partial" %}}
+
+````go
+{{ partial "shortcodes/include .html" (dict
+  "page" .
+  "file" "shortcodes/include/INCLUDE_ME.md"
+)}}
+````
+
+{{% /tab %}}
+{{< /tabs >}}
+
+The included files can even contain Markdown and will be taken into account when generating the table of contents.
+
+### Parameter
+
+| Name                 | Position | Default          | Notes       |
+|----------------------|----------|------------------|-------------|
+| **file**             | 1        | _&lt;empty&gt;_  | The path to the page, resource or file to be included. Page and resource paths adhere to [Hugo's logical path](https://gohugo.io/methods/page/path/). If not found by logical path it falls back to [Hugo's build-in `readFile` function](https://gohugo.io/functions/readfile/) |
+| **hidefirstheading** | 2        | `false`          | When `true` and the included file contains headings, the first heading will be hidden. This comes in handy, eg. if you include otherwise standalone Markdown files. |
+
+## Settings
+
+### Enabling Link Warnings
+
+{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} {{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} You can use `include.errorlevel` to control what should happen if a local link can not be resolved to a resource.
+
+If not set or empty, any unresolved link is written as given into the resulting output. If set to `warning` the same happens and an additional warning is printed in the built console. If set to `error` an error message is printed and the build is aborted.
+
+Please note that this can not resolve files inside of your `static` directory. The file must be a resource of the page or the site.
+
+Link warnings are also available for [images & links](authoring/frontmatter/linking#enabling-link-and-image-link-warnings) and the [openapi](shortcodes/openapi#enabling-link-warnings) shortcode.
+
+{{< multiconfig >}}
+include.errorlevel = 'warning'
+{{< /multiconfig >}}
+
+## Examples
+
+### Arbitrary Content
+
+````go
+{{%/* include "shortcodes/include/INCLUDE_ME.md" */%}}
+````
+
+{{% include "shortcodes/include/INCLUDE_ME.md" %}}
--- a/docs/content/shortcodes/include/index.pir.md
+++ b/docs/content/shortcodes/include/index.pir.md
@ -0,0 +1,8 @@
+++
+categories = ["howto", "reference"]
+description = "Displays content from other Marrrkdown files"
+frontmatter = ["include.errorlevel"]
+options = ["include.errorlevel"]
+title = "Include"
+++
+{{< piratify >}}
--- a/docs/content/shortcodes/math.en.md
+++ b/docs/content/shortcodes/math.en.md
@ -0,0 +1,195 @@
+++
+categories = ["howto", "reference"]
+description = "Beautiful math and chemical formulae"
+frontmatter = ["customMathJaxURL", "math", "math.force", "mathJaxInitialize"]
+options = ["customMathJaxURL", "math", "math.force", "mathJaxInitialize"]
+title = "Math"
+++
+
+If this is not enough, the `math` shortcode helps you rendering math and chemical formulae using the [MathJax](https://mathjax.org/) library.
+
+{{< math align="center" >}}
+$$\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)$$
+{{< /math >}}
+
+## Usage
+
+{{< tabs groupid="shortcode-parameter">}}
+{{% tab title="passthrough" %}}
+
+````md
+$$\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)$$
+````
+
+{{% /tab %}}
+{{% tab title="codefence" %}}
+
+````md
+```math {align="center"}
+$$\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)$$
+```
+````
+
+{{% /tab %}}
+{{% tab title="shortcode" %}}
+
+````go
+{{</* math align="center" */>}}
+$$\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)$$
+{{</* /math */>}}
+````
+
+{{% /tab %}}
+{{% tab title="partial" %}}
+
+````go
+{{ partial "shortcodes/math.html" (dict
+  "page"    .
+  "content" "$$left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)$$"
+  "align"   "center"
+)}}
+````
+
+{{% /tab %}}
+{{< /tabs >}}
+
+You can also use [pure Markdown](authoring/markdown#subscript-and-superscript) for writing simple math expressions.
+
+Passthrough syntax is only available by [further configuration](#passthrough-configuration) and has limited features as it does not provide any of the below parameter. Nevertheless, it is widely available in other Markdown parsers like GitHub and therefore is the recommend syntax for generating portable Markdown.
+
+### Parameter
+
+| Name                  | Default          | Notes       |
+|-----------------------|------------------|-------------|
+| **align**             | `center`         | The vertical alignment.<br><br>Allowed values are `left`, `center` or `right`. |
+| _**&lt;content&gt;**_ | _&lt;empty&gt;_  | Your formulae. |
+
+## Settings
+
+### Providing Initialization Options for the MathJax Library
+
+{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} {{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} The MathJax library is configured with default settings for initialization.
+
+You can overwrite the settings by providing a JSON object in `mathJaxInitialize`. See [MathJax's documentation](https://docs.mathjax.org/en/latest/options/index.html) for all allowed settings.
+
+Keep in mind that initialization settings of your pages front matter overwrite all settings of your configuration options.
+
+{{< multiconfig >}}
+mathJaxInitialize = '{ "chtml": { "displayAlign": "left" }, { "tex": { "inlineMath": [["\(", "\)"], ["@", "@"]], displayMath: [["\[", "\]"], ["@@", "@@"]] }, "options": { "enableMenu": false }'
+{{< /multiconfig >}}
+
+### Loading an External Version of the MathJax Library
+
+{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} {{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} The theme uses the shipped MathJax library by default.
+
+In case you want do use a different version of the MathJax library but don't want to override the shipped version, you can set `customMathJaxURL` to the URL of the external MathJax library.
+
+{{< multiconfig >}}
+customMathJaxURL = 'https://unpkg.com/mathjax/es5/tex-mml-chtml.js'
+{{< /multiconfig >}}
+
+### Force Loading of the MathJax Library
+
+{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} {{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} The MathJax library will be loaded if the page contains a `math` shortcode or codefence.
+
+You can force loading the MathJax library if no shortcode or codefence was used by setting `math=true`. If a shortcode or codefence was found, the option has no effect. This must be set in case you are using the [passthrough configuration](#passthrough-configuration) to render math.
+
+Instead of `math=true` you can also use the alias `math.force=true`.
+
+{{< multiconfig >}}
+math = true
+{{< /multiconfig >}}
+
+### Passthrough Configuration
+
+You can use your math without enclosing it in a shortcode or codefence by using a [passthrough configuration](https://gohugo.io/content-management/mathematics/#step-1)
+
+{{< multiconfig file=hugo >}}
+[markup]
+  [markup.goldmark]
+    [markup.goldmark.extensions]
+      [markup.goldmark.extensions.passthrough]
+        enable = true
+        [markup.goldmark.extensions.passthrough.delimiters]
+          inline = [['\(', '\)'], ['$',  '$']]
+          block  = [['\[', '\]'], ['$$', '$$']]
+{{< /multiconfig >}}
+
+In this case you have to [force load](#force-loading-of-the-mathjax-library) the MathJax library either in your `hugo.toml` or in your page's front matter as the theme doesn't know if math is used.
+
+[See the example](#passthrough-block-math) on how a passthrough configurations makes using math really easy.
+
+## Examples
+
+### Passthrough Block Math
+
+With [passthrough configuration](#passthrough-configuration) enabled you can just drop your math without enclosing it by shortcodes or codefences but no other [parameters](#parameter) are available.
+
+In this case you have to [force load](#force-loading-of-the-mathjax-library) the MathJax library by setting `math=true` either in your `hugo.toml` or in your page's front matter.
+
+In passthrough default configuration, block math is generated if you use two consecutive `$$` as a delimiter around your formulae.
+
+````md
+$$\left|
+\begin{array}{cc}
+a & b \\
+c & d
+\end{array}\right|$$
+````
+
+$$\left|
+\begin{array}{cc}
+a & b \\
+c & d
+\end{array}\right|$$
+
+### Passthrough Inline Math
+
+The same usage restrictions as of the [previous example](#passthrough-block-math) apply here as well.
+
+In passthrough default configuration, inline math is generated if you use a single `$` as a delimiter around your formulae.
+
+````md
+Euclid already knew, $\sqrt{2}$ is irrational.
+````
+
+Euclid already knew, $\sqrt{2}$ is irrational.
+
+### Codefence Block Math with Right Alignment
+
+If you are using codefences, more [parameter](#parameter) are available. Your formulae still needs to be enclosed by `$` or `$$` as delimiters respectively.
+
+
+````md
+```math {align="right"}
+$$\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)$$
+```
+````
+
+````math {align="right"}
+$$\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)$$
+````
+
+### Shortcode Block Math with Right Alignment
+
+You can also use shortcode syntax. Your formulae still needs to be enclosed by `$` or `$$` as delimiters respectively.
+
+````md
+{{</* math align="right" */>}}
+$$\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)$$
+{{</* /math */>}}
+````
+
+{{< math align="right" >}}
+$$\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)$$
+{{< /math >}}
+
+### Chemical Formulae
+
+The MathJax library can also be used for chemical formulae.
+
+````md
+$$\ce{Hg^2+ ->[I-] HgI2 ->[I-] [Hg^{II}I4]^2-}$$
+`````
+
+$$\ce{Hg^2+ ->[I-] HgI2 ->[I-] [Hg^{II}I4]^2-}$$
--- a/docs/content/shortcodes/math.pir.md
+++ b/docs/content/shortcodes/math.pir.md
@ -0,0 +1,8 @@
+++
+categories = ["howto", "reference"]
+description = "Beaut'fl math and chemical formulae"
+frontmatter = ["customMathJaxURL", "math", "math.force", "mathJaxInitialize"]
+options = ["customMathJaxURL", "math", "math.force", "mathJaxInitialize"]
+title = "Math"
+++
+{{< piratify >}}
--- a/docs/content/shortcodes/mermaid.en.md
+++ b/docs/content/shortcodes/mermaid.en.md
@ -0,0 +1,884 @@
+++
+categories = ["howto", "reference"]
+description = "Generate diagrams and flowcharts from text"
+frontmatter = ["customMermaidURL", "mermaid.force", "mermaidInitialize", "mermaidZoom"]
+options = ["customMermaidURL", "mermaid.force", "mermaidInitialize", "mermaidZoom"]
+title = "Mermaid"
+++
+
+The `mermaid` shortcode generates diagrams and flowcharts from text in a similar manner as Markdown using the [Mermaid](https://mermaidjs.github.io/) library.
+
+````mermaid {align="center" zoom="true"}
+graph LR;
+  If --> Then
+  Then --> Else
+````
+
+## Usage
+
+{{< tabs groupid="shortcode-parameter">}}
+{{% tab title="codefence" %}}
+
+````md
+```mermaid {align="center" zoom="true"}
+graph LR;
+  If --> Then
+  Then --> Else
+```
+````
+
+{{% /tab %}}
+{{% tab title="shortcode" %}}
+
+````go
+{{</* mermaid align="center" zoom="true" */>}}
+graph LR;
+  If --> Then
+  Then --> Else
+{{</* /mermaid */>}}
+````
+
+{{% /tab %}}
+{{% tab title="partial" %}}
+
+````go
+{{ partial "shortcodes/mermaid.html" (dict
+  "page"    .
+  "content" "graph LR;\n  If --> Then\n  Then --> Else"
+  "align"   "center"
+  "zoom"    "true"
+)}}
+
+````
+
+{{% /tab %}}
+{{< /tabs >}}
+
+Codefence syntax is widely available in other Markdown parsers like GitHub and therefore is the recommend syntax for generating portable Markdown.
+
+### Parameter
+
+| Name                  | Default          | Notes       |
+|-----------------------|------------------|-------------|
+| **align**             | `center`         | The vertical alignment.<br><br>Allowed values are `left`, `center` or `right`. |
+| **zoom**              | see notes        | Whether the graph is pan- and zoomable.<br><br>If not set the value is determined by the [`mermaidZoom` setting](#configuring-pan-and-zoom) of your configurations options or the pages front matter or `false` if not set at all.<br><br>- `false`: no pan or zoom<br>- `true`: pan and zoom active |
+| _**&lt;content&gt;**_ | _&lt;empty&gt;_  | Your Mermaid graph. |
+
+## Settings
+
+### Configuring Pan and Zoom
+
+{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} {{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} The generated graphs can be panned by dragging them and zoomed by using the mousewheel. On mobile devices you can use finger gestures.
+
+By default this is disabled. Set `mermaidZoom=true` to enable it.
+
+Individual settings of a graphs [`zoom` parameter](#parameter) have precedence over the page's front matter and configuration options in that order.
+
+{{< multiconfig >}}
+mermaidZoom = true
+{{< /multiconfig >}}
+
+### Providing Initialization Options for the Mermaid Library
+
+{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} {{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} The Mermaid library is configured with default settings for initialization.
+
+You can overwrite the settings by providing a JSON object in `mermaidInitialize`. See [Mermaid's documentation](https://mermaid-js.github.io/mermaid/#/Setup?id=mermaidapi-configuration-defaults) for all allowed settings.
+
+> [!NOTE]
+> Using the `theme` setting in the initialization options is unsupported. To set the theme globally edit the `--MERMAID-theme` variable of your [color variant](configuration/branding/colors/#modifying-variants).
+
+Keep in mind that initialization settings of your pages front matter overwrite all settings of your configuration options.
+
+In addition, you can merge settings for each individual graph through [diagram directives](https://mermaid-js.github.io/mermaid/#/directives?id=directives) on top of the settings of your page's front matter or configuration options.
+
+{{< multiconfig >}}
+mermaidInitialize = '{ "securityLevel": "loose" }'
+{{< /multiconfig >}}
+
+### Loading an External Version of the Mermaid Library
+
+{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} {{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} The theme uses the shipped Mermaid library by default.
+
+In case you want do use a different version of the Mermaid library but don't want to override the shipped version, you can set `customMermaidURL` to the URL of the external Mermaid library.
+
+{{< multiconfig >}}
+customMermaidURL = 'https://unpkg.com/mermaid/dist/mermaid.min.js'
+{{< /multiconfig >}}
+
+### Force Loading of the Mermaid Library
+
+{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} {{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} The Mermaid library will be loaded if the page contains an `mermaid` shortcode or codefence.
+
+You can force loading the Mermaid library if no shortcode or codefence was used by setting `mermaid.force=true`. If a shortcode or codefence was found, this option has no effect. This comes handy in case you are using scripting to render a graph.
+
+{{< multiconfig >}}
+mermaid.force = true
+{{< /multiconfig >}}
+
+### Setting a Specific Mermaid Theme
+
+While you can configure the Mermaid theme to render your graph by using one of the [initialization options](#providing-initialization-options-for-the-mermaid-library), the recommended way is to set the default value using the `--MERMAID-theme` variable in your [color variant stylesheet](configuration/branding/generator). This allows your graphs to look pretty when the user switches the color variant.
+
+## Examples
+
+### Flowchart with YAML-Title
+
+````md
+```mermaid
+---
+title: Example Diagram
+---
+graph LR;
+  A[Hard edge] -->|Link text| B(Round edge)
+  B --> C{<strong>Decision</strong>}
+  C -->|One| D[Result one]
+  C -->|Two| E[Result two]
+```
+````
+
+````mermaid
+---
+title: Example Diagram
+---
+graph LR;
+  A[Hard edge] -->|Link text| B(Round edge)
+  B --> C{<strong>Decision</strong>}
+  C -->|One| D[Result one]
+  C -->|Two| E[Result two]
+````
+
+### Sequence Diagram with Configuration Directive
+
+````md
+```mermaid
+%%{init:{"fontFamily":"monospace", "sequence":{"showSequenceNumbers":true}}}%%
+sequenceDiagram
+  Alice->>John: Hello John, how are you?
+  loop Healthcheck
+      John->>John: Fight against hypochondria
+  end
+  Note right of John: Rational thoughts!
+  John-->>Alice: Great!
+  John->>Bob: How about you?
+  Bob-->>John: Jolly good!
+```
+````
+
+````mermaid
+%%{init:{"fontFamily":"monospace", "sequence":{"showSequenceNumbers":true}}}%%
+sequenceDiagram
+  Alice->>John: Hello John, how are you?
+  loop Healthcheck
+      John->>John: Fight against hypochondria
+  end
+  Note right of John: Rational thoughts!
+  John-->>Alice: Great!
+  John->>Bob: How about you?
+  Bob-->>John: Jolly good!
+````
+
+### Class Diagram
+
+````md
+```mermaid
+classDiagram
+  Animal <|-- Duck
+  Animal <|-- Fish
+  Animal <|-- Zebra
+  Animal : +int age
+  Animal : +String gender
+  Animal: +isMammal()
+  Animal: +mate()
+  class Duck{
+    +String beakColor
+    +swim()
+    +quack()
+  }
+  class Fish{
+    -int sizeInFeet
+    -canEat()
+  }
+  class Zebra{
+    +bool is_wild
+    +run()
+  }
+```
+````
+
+````mermaid
+classDiagram
+  Animal <|-- Duck
+  Animal <|-- Fish
+  Animal <|-- Zebra
+  Animal : +int age
+  Animal : +String gender
+  Animal: +isMammal()
+  Animal: +mate()
+  class Duck{
+    +String beakColor
+    +swim()
+    +quack()
+  }
+  class Fish{
+    -int sizeInFeet
+    -canEat()
+  }
+  class Zebra{
+    +bool is_wild
+    +run()
+  }
+````
+
+### State Diagram Aligned to the Right Using Shortcode Syntax
+
+````go
+{{</* mermaid align="right" */>}}
+stateDiagram-v2
+  open: Open Door
+  closed: Closed Door
+  locked: Locked Door
+  open   --> closed: Close
+  closed --> locked: Lock
+  locked --> closed: Unlock
+  closed --> open: Open
+{{</* /mermaid */>}}
+````
+
+{{< mermaid align="right" >}}
+stateDiagram-v2
+  open: Open Door
+  closed: Closed Door
+  locked: Locked Door
+  open   --> closed: Close
+  closed --> locked: Lock
+  locked --> closed: Unlock
+  closed --> open: Open
+{{< /mermaid >}}
+
+### Entity Relationship Model with Non-Default Mermaid Theme
+
+````md
+```mermaid
+%%{init:{"theme":"forest"}}%%
+erDiagram
+  CUSTOMER }|..|{ DELIVERY-ADDRESS : has
+  CUSTOMER ||--o{ ORDER : places
+  CUSTOMER ||--o{ INVOICE : "liable for"
+  DELIVERY-ADDRESS ||--o{ ORDER : receives
+  INVOICE ||--|{ ORDER : covers
+  ORDER ||--|{ ORDER-ITEM : includes
+  PRODUCT-CATEGORY ||--|{ PRODUCT : contains
+  PRODUCT ||--o{ ORDER-ITEM : "ordered in"
+```
+````
+
+````mermaid
+%%{init:{"theme":"forest"}}%%
+erDiagram
+  CUSTOMER }|..|{ DELIVERY-ADDRESS : has
+  CUSTOMER ||--o{ ORDER : places
+  CUSTOMER ||--o{ INVOICE : "liable for"
+  DELIVERY-ADDRESS ||--o{ ORDER : receives
+  INVOICE ||--|{ ORDER : covers
+  ORDER ||--|{ ORDER-ITEM : includes
+  PRODUCT-CATEGORY ||--|{ PRODUCT : contains
+  PRODUCT ||--o{ ORDER-ITEM : "ordered in"
+````
+
+### User Journey
+
+````md
+```mermaid
+journey
+  title My working day
+  section Go to work
+    Make tea: 5: Me
+    Go upstairs: 3: Me
+    Do work: 1: Me, Cat
+  section Go home
+    Go downstairs: 5: Me
+    Sit down: 3: Me
+```
+````
+
+````mermaid
+journey
+  title My working day
+  section Go to work
+    Make tea: 5: Me
+    Go upstairs: 3: Me
+    Do work: 1: Me, Cat
+  section Go home
+    Go downstairs: 5: Me
+    Sit down: 3: Me
+````
+
+### GANTT Chart
+
+````md
+```mermaid
+gantt
+  dateFormat  YYYY-MM-DD
+  title Adding GANTT diagram functionality to Mermaid
+  section A section
+  Completed task            :done,    des1, 2014-01-06,2014-01-08
+  Active task               :active,  des2, 2014-01-09, 3d
+  Future task               :         des3, after des2, 5d
+  Future task2              :         des4, after des3, 5d
+  section Critical tasks
+  Completed task in the critical line :crit, done, 2014-01-06,24h
+  Implement parser and jison          :crit, done, after des1, 2d
+  Create tests for parser             :crit, active, 3d
+  Future task in critical line        :crit, 5d
+  Create tests for renderer           :2d
+  Add to Mermaid                      :1d
+```
+````
+
+````mermaid
+gantt
+  dateFormat  YYYY-MM-DD
+  title Adding GANTT diagram functionality to Mermaid
+  section A section
+  Completed task            :done,    des1, 2014-01-06,2014-01-08
+  Active task               :active,  des2, 2014-01-09, 3d
+  Future task               :         des3, after des2, 5d
+  Future task2              :         des4, after des3, 5d
+  section Critical tasks
+  Completed task in the critical line :crit, done, 2014-01-06,24h
+  Implement parser and jison          :crit, done, after des1, 2d
+  Create tests for parser             :crit, active, 3d
+  Future task in critical line        :crit, 5d
+  Create tests for renderer           :2d
+  Add to Mermaid                      :1d
+````
+
+### Pie Chart without Zoom
+
+````md
+```mermaid {zoom="false"}
+pie title Pets adopted by volunteers
+  "Dogs" : 386
+  "Cats" : 85
+  "Rats" : 15
+```
+````
+
+````mermaid {zoom="false"}
+pie title Pets adopted by volunteers
+  "Dogs" : 386
+  "Cats" : 85
+  "Rats" : 15
+````
+
+### Quadrant Chart
+
+````md
+```mermaid
+quadrantChart
+  title Reach and engagement of campaigns
+  x-axis Low Reach --> High Reach
+  y-axis Low Engagement --> High Engagement
+  quadrant-1 We should expand
+  quadrant-2 Need to promote
+  quadrant-3 Re-evaluate
+  quadrant-4 May be improved
+  Campaign A: [0.3, 0.6]
+  Campaign B: [0.45, 0.23]
+  Campaign C: [0.57, 0.69]
+  Campaign D: [0.78, 0.34]
+  Campaign E: [0.40, 0.34]
+  Campaign F: [0.35, 0.78]
+```
+````
+
+````mermaid
+quadrantChart
+  title Reach and engagement of campaigns
+  x-axis Low Reach --> High Reach
+  y-axis Low Engagement --> High Engagement
+  quadrant-1 We should expand
+  quadrant-2 Need to promote
+  quadrant-3 Re-evaluate
+  quadrant-4 May be improved
+  Campaign A: [0.3, 0.6]
+  Campaign B: [0.45, 0.23]
+  Campaign C: [0.57, 0.69]
+  Campaign D: [0.78, 0.34]
+  Campaign E: [0.40, 0.34]
+  Campaign F: [0.35, 0.78]
+````
+
+### Requirement Diagram
+
+````md
+```mermaid
+requirementDiagram
+
+  requirement test_req {
+    id: 1
+    text: the test text.
+    risk: high
+    verifymethod: test
+  }
+
+  element test_entity {
+    type: simulation
+  }
+
+  test_entity - satisfies -> test_req
+```
+````
+
+````mermaid
+requirementDiagram
+
+  requirement test_req {
+    id: 1
+    text: the test text.
+    risk: high
+    verifymethod: test
+  }
+
+  element test_entity {
+    type: simulation
+  }
+
+  test_entity - satisfies -> test_req
+````
+
+### Git Graph
+
+````md
+```mermaid
+gitGraph
+  commit
+  commit
+  branch develop
+  checkout develop
+  commit
+  commit
+  checkout main
+  merge develop
+  commit
+  commit
+```
+````
+
+````mermaid
+gitGraph
+  commit
+  commit
+  branch develop
+  checkout develop
+  commit
+  commit
+  checkout main
+  merge develop
+  commit
+  commit
+````
+
+### C4 Diagrams
+
+````md
+```mermaid
+C4Context
+  title System Context diagram for Internet Banking System
+  Enterprise_Boundary(b0, "BankBoundary0") {
+    Person(customerA, "Banking Customer A", "A customer of the bank, with personal bank accounts.")
+    Person(customerB, "Banking Customer B")
+    Person_Ext(customerC, "Banking Customer C", "desc")
+    Person(customerD, "Banking Customer D", "A customer of the bank, <br/> with personal bank accounts.")
+
+    System(SystemAA, "Internet Banking System", "Allows customers to view information about their bank accounts, and make payments.")
+
+    Enterprise_Boundary(b1, "BankBoundary") {
+      SystemDb_Ext(SystemE, "Mainframe Banking System", "Stores all of the core banking information about customers, accounts, transactions, etc.")
+
+      System_Boundary(b2, "BankBoundary2") {
+        System(SystemA, "Banking System A")
+        System(SystemB, "Banking System B", "A system of the bank, with personal bank accounts. next line.")
+      }
+
+      System_Ext(SystemC, "E-mail system", "The internal Microsoft Exchange e-mail system.")
+      SystemDb(SystemD, "Banking System D Database", "A system of the bank, with personal bank accounts.")
+
+      Boundary(b3, "BankBoundary3", "boundary") {
+        SystemQueue(SystemF, "Banking System F Queue", "A system of the bank.")
+        SystemQueue_Ext(SystemG, "Banking System G Queue", "A system of the bank, with personal bank accounts.")
+      }
+    }
+  }
+
+  BiRel(customerA, SystemAA, "Uses")
+  BiRel(SystemAA, SystemE, "Uses")
+  Rel(SystemAA, SystemC, "Sends e-mails", "SMTP")
+  Rel(SystemC, customerA, "Sends e-mails to")
+
+  UpdateElementStyle(customerA, $fontColor="red", $bgColor="grey", $borderColor="red")
+  UpdateRelStyle(customerA, SystemAA, $textColor="blue", $lineColor="blue", $offsetX="5")
+  UpdateRelStyle(SystemAA, SystemE, $textColor="blue", $lineColor="blue", $offsetY="-10")
+  UpdateRelStyle(SystemAA, SystemC, $textColor="blue", $lineColor="blue", $offsetY="-40", $offsetX="-50")
+  UpdateRelStyle(SystemC, customerA, $textColor="red", $lineColor="red", $offsetX="-50", $offsetY="20")
+
+  UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")
+```
+````
+
+````mermaid
+C4Context
+  title System Context diagram for Internet Banking System
+  Enterprise_Boundary(b0, "BankBoundary0") {
+    Person(customerA, "Banking Customer A", "A customer of the bank, with personal bank accounts.")
+    Person(customerB, "Banking Customer B")
+    Person_Ext(customerC, "Banking Customer C", "desc")
+    Person(customerD, "Banking Customer D", "A customer of the bank, <br/> with personal bank accounts.")
+
+    System(SystemAA, "Internet Banking System", "Allows customers to view information about their bank accounts, and make payments.")
+
+    Enterprise_Boundary(b1, "BankBoundary") {
+      SystemDb_Ext(SystemE, "Mainframe Banking System", "Stores all of the core banking information about customers, accounts, transactions, etc.")
+
+      System_Boundary(b2, "BankBoundary2") {
+        System(SystemA, "Banking System A")
+        System(SystemB, "Banking System B", "A system of the bank, with personal bank accounts. next line.")
+      }
+
+      System_Ext(SystemC, "E-mail system", "The internal Microsoft Exchange e-mail system.")
+      SystemDb(SystemD, "Banking System D Database", "A system of the bank, with personal bank accounts.")
+
+      Boundary(b3, "BankBoundary3", "boundary") {
+        SystemQueue(SystemF, "Banking System F Queue", "A system of the bank.")
+        SystemQueue_Ext(SystemG, "Banking System G Queue", "A system of the bank, with personal bank accounts.")
+      }
+    }
+  }
+
+  BiRel(customerA, SystemAA, "Uses")
+  BiRel(SystemAA, SystemE, "Uses")
+  Rel(SystemAA, SystemC, "Sends e-mails", "SMTP")
+  Rel(SystemC, customerA, "Sends e-mails to")
+
+  UpdateElementStyle(customerA, $fontColor="red", $bgColor="grey", $borderColor="red")
+  UpdateRelStyle(customerA, SystemAA, $textColor="blue", $lineColor="blue", $offsetX="5")
+  UpdateRelStyle(SystemAA, SystemE, $textColor="blue", $lineColor="blue", $offsetY="-10")
+  UpdateRelStyle(SystemAA, SystemC, $textColor="blue", $lineColor="blue", $offsetY="-40", $offsetX="-50")
+  UpdateRelStyle(SystemC, customerA, $textColor="red", $lineColor="red", $offsetX="-50", $offsetY="20")
+
+  UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")
+````
+
+### Mindmaps
+
+````md
+```mermaid
+mindmap
+  root((mindmap))
+    Origins
+      Long history
+      ::icon(fa fa-book)
+      Popularisation
+        British popular psychology author Tony Buzan
+    Research
+      On effectiveness<br/>and features
+      On Automatic creation
+        Uses
+            Creative techniques
+            Strategic planning
+            Argument mapping
+    Tools
+      Pen and paper
+      Mermaid
+```
+````
+
+````mermaid
+mindmap
+  root((mindmap))
+    Origins
+      Long history
+      ::icon(fa fa-book)
+      Popularisation
+        British popular psychology author Tony Buzan
+    Research
+      On effectiveness<br/>and features
+      On Automatic creation
+        Uses
+            Creative techniques
+            Strategic planning
+            Argument mapping
+    Tools
+      Pen and paper
+      Mermaid
+````
+
+### Timeline
+
+````md
+```mermaid
+timeline
+  title History of Social Media Platform
+  2002 : LinkedIn
+  2004 : Facebook
+       : Google
+  2005 : Youtube
+  2006 : Twitter
+```
+````
+
+````mermaid
+timeline
+  title History of Social Media Platform
+  2002 : LinkedIn
+  2004 : Facebook
+       : Google
+  2005 : Youtube
+  2006 : Twitter
+````
+
+### ZenUML
+
+ZenUML is currently not available with the Mermaid version shipped with the theme due to further required dependencies. Use [sequence diagrams](#sequence-diagram-with-configuration-directive) instead.
+
+<!--
+````md
+```mermaid
+zenuml
+    title Annotators
+    @Actor Alice
+    @Database Bob
+    Alice->Bob: Hi Bob
+    Bob->Alice: Hi Alice
+```
+````
+
+````mermaid
+zenuml
+    title Annotators
+    @Actor Alice
+    @Database Bob
+    Alice->Bob: Hi Bob
+    Bob->Alice: Hi Alice
+````
+-->
+
+### Sankey
+
+````md
+```mermaid
+sankey-beta
+  %% source,target,value
+  Electricity grid,Over generation / exports,104.453
+  Electricity grid,Heating and cooling - homes,113.726
+  Electricity grid,H2 conversion,27.14
+```
+````
+
+````mermaid
+sankey-beta
+  %% source,target,value
+  Electricity grid,Over generation / exports,104.453
+  Electricity grid,Heating and cooling - homes,113.726
+  Electricity grid,H2 conversion,27.14
+````
+
+### XYChart
+
+````md
+```mermaid
+xychart-beta
+  title "Sales Revenue"
+  x-axis [jan, feb, mar, apr, may, jun, jul, aug, sep, oct, nov, dec]
+  y-axis "Revenue (in $)" 4000 --> 11000
+  bar [5000, 6000, 7500, 8200, 9500, 10500, 11000, 10200, 9200, 8500, 7000, 6000]
+  line [5000, 6000, 7500, 8200, 9500, 10500, 11000, 10200, 9200, 8500, 7000, 6000]
+```
+````
+
+````mermaid
+xychart-beta
+  title "Sales Revenue"
+  x-axis [jan, feb, mar, apr, may, jun, jul, aug, sep, oct, nov, dec]
+  y-axis "Revenue (in $)" 4000 --> 11000
+  bar [5000, 6000, 7500, 8200, 9500, 10500, 11000, 10200, 9200, 8500, 7000, 6000]
+  line [5000, 6000, 7500, 8200, 9500, 10500, 11000, 10200, 9200, 8500, 7000, 6000]
+````
+
+### Block Diagram
+
+````md
+```mermaid
+block-beta
+  columns 1
+    db(("DB"))
+    blockArrowId6<["&nbsp;&nbsp;&nbsp;"]>(down)
+    block:ID
+      A
+      B["A wide one in the middle"]
+      C
+    end
+    space
+    D
+    ID --> D
+    C --> D
+    style B fill:#969,stroke:#333,stroke-width:4px
+```
+````
+
+````mermaid
+block-beta
+  columns 1
+    db(("DB"))
+    blockArrowId6<["&nbsp;&nbsp;&nbsp;"]>(down)
+    block:ID
+      A
+      B["A wide one in the middle"]
+      C
+    end
+    space
+    D
+    ID --> D
+    C --> D
+    style B fill:#969,stroke:#333,stroke-width:4px
+````
+
+### Packet
+
+````md
+```mermaid
+---
+title: "TCP Packet"
+---
+packet-beta
+  0-15: "Source Port"
+  16-31: "Destination Port"
+  32-63: "Sequence Number"
+  64-95: "Acknowledgment Number"
+  96-99: "Data Offset"
+  100-105: "Reserved"
+  106: "URG"
+  107: "ACK"
+  108: "PSH"
+  109: "RST"
+  110: "SYN"
+  111: "FIN"
+  112-127: "Window"
+  128-143: "Checksum"
+  144-159: "Urgent Pointer"
+  160-191: "(Options and Padding)"
+  192-255: "Data (variable length)"
+```
+````
+
+````mermaid
+---
+title: "TCP Packet"
+---
+packet-beta
+  0-15: "Source Port"
+  16-31: "Destination Port"
+  32-63: "Sequence Number"
+  64-95: "Acknowledgment Number"
+  96-99: "Data Offset"
+  100-105: "Reserved"
+  106: "URG"
+  107: "ACK"
+  108: "PSH"
+  109: "RST"
+  110: "SYN"
+  111: "FIN"
+  112-127: "Window"
+  128-143: "Checksum"
+  144-159: "Urgent Pointer"
+  160-191: "(Options and Padding)"
+  192-255: "Data (variable length)"
+````
+
+### Kanban
+
+````md
+```mermaid
+---
+config:
+  kanban:
+    ticketBaseUrl: 'https://mermaidchart.atlassian.net/browse/#TICKET#'
+---
+kanban
+  Todo
+    [Create Documentation]
+    docs[Create Blog about the new diagram]
+  [In progress]
+    id6[Create renderer so that it works in all cases. We also add som extra text here for testing purposes. And some more just for the extra flare.]
+  id9[Ready for deploy]
+    id8[Design grammar]@{ assigned: 'knsv' }
+  id10[Ready for test]
+    id4[Create parsing tests]@{ ticket: MC-2038, assigned: 'K.Sveidqvist', priority: 'High' }
+    id66[last item]@{ priority: 'Very Low', assigned: 'knsv' }
+  id11[Done]
+    id5[define getData]
+    id2[Title of diagram is more than 100 chars when user duplicates diagram with 100 char]@{ ticket: MC-2036, priority: 'Very High'}
+    id3[Update DB function]@{ ticket: MC-2037, assigned: knsv, priority: 'High' }
+
+  id12[Can't reproduce]
+    id3[Weird flickering in Firefox]
+```
+````
+
+````mermaid
+---
+config:
+  kanban:
+    ticketBaseUrl: 'https://mermaidchart.atlassian.net/browse/#TICKET#'
+---
+kanban
+  Todo
+    [Create Documentation]
+    docs[Create Blog about the new diagram]
+  [In progress]
+    id6[Create renderer so that it works in all cases. We also add som extra text here for testing purposes. And some more just for the extra flare.]
+  id9[Ready for deploy]
+    id8[Design grammar]@{ assigned: 'knsv' }
+  id10[Ready for test]
+    id4[Create parsing tests]@{ ticket: MC-2038, assigned: 'K.Sveidqvist', priority: 'High' }
+    id66[last item]@{ priority: 'Very Low', assigned: 'knsv' }
+  id11[Done]
+    id5[define getData]
+    id2[Title of diagram is more than 100 chars when user duplicates diagram with 100 char]@{ ticket: MC-2036, priority: 'Very High'}
+    id3[Update DB function]@{ ticket: MC-2037, assigned: knsv, priority: 'High' }
+
+  id12[Can't reproduce]
+    id3[Weird flickering in Firefox]
+````
+
+### Architecture
+
+````md
+```mermaid
+architecture-beta
+  group api(cloud)[API]
+
+  service db(database)[Database] in api
+  service disk1(disk)[Storage] in api
+  service disk2(disk)[Storage] in api
+  service server(server)[Server] in api
+
+  db:L -- R:server
+  disk1:T -- B:server
+  disk2:T -- B:db
+```
+````
+
+````mermaid
+architecture-beta
+  group api(cloud)[API]
+
+  service db(database)[Database] in api
+  service disk1(disk)[Storage] in api
+  service disk2(disk)[Storage] in api
+  service server(server)[Server] in api
+
+  db:L -- R:server
+  disk1:T -- B:server
+  disk2:T -- B:db
+````
--- a/docs/content/shortcodes/mermaid.pir.md
+++ b/docs/content/shortcodes/mermaid.pir.md
@ -0,0 +1,8 @@
+++
+categories = ["howto", "reference"]
+description = "Generrrat'n o' diagrrram an' flowcharrrt frrrom text"
+frontmatter = ["customMermaidURL", "mermaid.force", "mermaidInitialize", "mermaidZoom"]
+options = ["customMermaidURL", "mermaid.force", "mermaidInitialize", "mermaidZoom"]
+title = "Merrrmaid"
+++
+{{< piratify true >}}
--- a/docs/content/shortcodes/notice.en.md
+++ b/docs/content/shortcodes/notice.en.md
@ -0,0 +1,379 @@
+++
+categories = ["howto", "reference"]
+description = "Disclaimers to help you structure your page"
+options = ["boxStyle"]
+title = "Notice"
+++
+
+The `notice` shortcode shows various types of disclaimers with adjustable color, title and icon to help you structure your page.
+
+{{% notice style="primary" title="There may be pirates" icon="skull-crossbones" %}}
+It is all about the boxes.
+{{% /notice %}}
+
+## Usage
+
+{{< tabs groupid="shortcode-parameter">}}
+{{% tab title="callout" %}}
+
+````md
+> [!primary] There may be pirates
+> It is all about the boxes.
+````
+
+{{% /tab %}}
+{{% tab title="shortcode" %}}
+
+````go
+{{%/* notice style="primary" title="There may be pirates" icon="skull-crossbones" */%}}
+It is all about the boxes.
+{{%/* /notice */%}}
+````
+
+{{% /tab %}}
+{{% tab title="shortcode (positional)" %}}
+
+````go
+{{%/* notice primary "There may be pirates" "skull-crossbones" */%}}
+It is all about the boxes.
+{{%/* /notice */%}}
+````
+
+{{% /tab %}}
+{{% tab title="partial" %}}
+
+````go
+{{ partial "shortcodes/notice.html" (dict
+  "page"  .
+  "style" "primary"
+  "title" "There may be pirates"
+  "icon" "skull-crossbones"
+  "content" "It is all about the boxes."
+)}}
+````
+
+{{% /tab %}}
+{{< /tabs >}}
+
+Callout syntax has limited features as it does not provide all of the below parameter. Nevertheless, it is widely available in other Markdown parsers like [GitHub](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts) or [Obsidian](https://help.obsidian.md/Editing+and+formatting/Callouts#Change+the+title) and therefore is the recommend syntax for generating portable Markdown.
+
+If you want to display a transparent expandable box without any border, you can also use the [`expand` shortcode](/shortcodes/expand).
+
+### Parameter
+
+| Name                  | Position | Default         | Notes       |
+|-----------------------|----------|-----------------|-------------|
+| **groupid**           |          | _&lt;empty&gt;_ | Arbitrary name of the group the box belongs to.<br><br>Expandable boxes with the same **groupid** sychronize their open state. |
+| **style**             | 1        | `default`       | The style scheme used for the box.<br><br>- by severity: `caution`, `important`, `info`, `note`, `tip`, `warning`<br>- by brand color: `primary`, `secondary`, `accent`<br>- by color: `blue`, `cyan`, `green`, `grey`, `magenta`, `orange`, `red`<br>- by special color: `default`, `transparent`, `code`<br><br>You can also [define your own styles](#defining-own-styles). |
+| **color**             |          | see notes       | The [CSS color value](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value) to be used. If not set, the chosen color depends on the **style**. Any given value will overwrite the default.<br><br>- for severity styles: a nice matching color for the severity<br>- for all other styles: the corresponding color<br><br>This is not available using callout syntax. |
+| **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 styles: _&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](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 styles: _&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)<br><br>This is not available using callout syntax. |
+| **expanded**          |          | _&lt;empty&gt;_ | Whether to draw an expander and how the content is displayed.<br><br>- _&lt;empty&gt;_: no expander is drawn and the content is permanently shown<br>- `true`: the expander is drawn and the content is initially shown<br>- `false`: the expander is drawn and the content is initially hidden |
+| _**&lt;content&gt;**_ |          | _&lt;empty&gt;_ | Arbitrary text to be displayed in box. |
+
+## Settings
+
+### Defining own Styles
+
+{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} Besides the predefined `style` values [from above](#parameter), you are able to define your own.
+
+{{< multiconfig file=hugo >}}
+[params]
+boxStyle = [
+	{ identifier = 'magic', i18n = '', title = 'Magic', icon = 'rainbow', color = 'gold' }
+]
+{{< /multiconfig >}}
+
+The `style` parameter used in a shortcode must match the `identifier` in the configuration. The title for the style will be determined from the configured `title`. If no `title` but a `i18n` is set, the title will be taken from the translation files by that key. The `title` may be empty in which case, the box does not contain a default title. `icon` and `color` are working similar.
+
+You can also redefine the predefined styles if you're not satisfied with the default values.
+
+Below is a [usage example](#user-defined-style).
+
+## Examples
+
+### By Severity Using Callout Syntax
+
+````md
+> [!CAUTION]
+> Advises about risks or negative outcomes of certain actions.
+
+> [!IMPORTANT]
+> Key information users need to know to achieve their goal.
+
+> [!INFO]
+> Information that users <ins>_might_</ins> find interesting.
+
+> [!NOTE]
+> Useful information that users should know, even when skimming content.
+
+> [!TIP]
+> Helpful advice for doing things better or more easily.
+
+> [!WARNING]
+> Urgent info that needs immediate user attention to avoid problems.
+````
+
+> [!CAUTION]
+> Advises about risks or negative outcomes of certain actions.
+
+> [!IMPORTANT]
+> Key information users need to know to achieve their goal.
+
+> [!INFO]
+> Information that users <ins>_might_</ins> find interesting.
+
+> [!NOTE]
+> Useful information that users should know, even when skimming content.
+
+> [!TIP]
+> Helpful advice for doing things better or more easily.
+
+> [!WARNING]
+> Urgent info that needs immediate user attention to avoid problems.
+
+### By Brand Colors with Title and Icon Variantion
+
+````go
+{{%/* notice style="primary" title="Primary" */%}}
+A **primary** disclaimer
+{{%/* /notice */%}}
+
+{{%/* notice style="secondary" title="Secondary" */%}}
+A **secondary** disclaimer
+{{%/* /notice */%}}
+
+{{%/* notice style="accent" icon="stopwatch" */%}}
+An **accent** disclaimer
+{{%/* /notice */%}}
+````
+
+{{% notice style="primary" title="Primary" %}}
+A **primary** disclaimer
+{{% /notice %}}
+
+{{% notice style="secondary" title="Secondary" %}}
+A **secondary** disclaimer
+{{% /notice %}}
+
+{{% notice style="accent" icon="stopwatch" %}}
+An **accent** disclaimer
+{{% /notice %}}
+
+### By Color
+
+````go
+{{%/* notice style="blue" title="Blue"*/%}}
+A **blue** disclaimer
+{{%/* /notice */%}}
+
+{{%/* notice style="cyan" title="Cyan" */%}}
+A **cyan** disclaimer
+{{%/* /notice */%}}
+
+{{%/* notice style="green" title="Green" */%}}
+A **green** disclaimer
+{{%/* /notice */%}}
+
+{{%/* notice style="grey" icon="bug" */%}}
+A **grey** disclaimer
+{{%/* /notice */%}}
+
+{{%/* notice style="magenta" title="Magenta" */%}}
+A **magenta** disclaimer
+{{%/* /notice */%}}
+
+{{%/* notice style="orange" title="Orange" icon="bug" */%}}
+A **orange** disclaimer
+{{%/* /notice */%}}
+
+{{%/* notice style="red" title="Red" */%}}
+A **red** disclaimer
+{{%/* /notice */%}}
+````
+
+{{% notice style="blue" title="Blue" %}}
+A **blue** disclaimer
+{{% /notice %}}
+
+{{% notice style="cyan" title="Cyan" %}}
+A **cyan** disclaimer
+{{% /notice %}}
+
+{{% notice style="green" title="Green" %}}
+A **green** disclaimer
+{{% /notice %}}
+
+{{% notice style="grey" icon="bug" %}}
+A **grey** disclaimer
+{{% /notice %}}
+
+{{% notice style="magenta" title="Magenta" %}}
+A **magenta** disclaimer
+{{% /notice %}}
+
+{{% notice style="orange" title="Orange" icon="bug" %}}
+A **orange** disclaimer
+{{% /notice %}}
+
+{{% notice style="red" title="Red" %}}
+A **red** disclaimer
+{{% /notice %}}
+
+### By Special Color
+
+````go
+{{%/* notice style="default" title="Default" icon="skull-crossbones" */%}}
+Just some grey default color.
+{{%/* /notice */%}}
+
+{{%/* notice style="code" title="Code" icon="skull-crossbones" */%}}
+Colored like a code fence.
+{{%/* /notice */%}}
+
+{{%/* notice style="transparent" title="Transparent" icon="skull-crossbones" */%}}
+No visible borders.
+{{%/* /notice */%}}
+````
+
+{{% notice style="default" title="Default" icon="skull-crossbones" %}}
+Just some grey default color.
+{{% /notice %}}
+
+{{% notice style="code" title="Code" icon="skull-crossbones" %}}
+Colored like a code fence.
+{{% /notice %}}
+
+{{% notice style="transparent" title="Transparent" icon="skull-crossbones" %}}
+No visible borders.
+{{% /notice %}}
+
+### Various Features
+
+#### With User-Defined Color, Font Awesome Brand Icon and Markdown in Title and Content
+
+````go
+{{%/* notice color="fuchsia" title="**Hugo** is _awesome_" icon="fa-fw fab fa-hackerrank" */%}}
+{{% include "shortcodes/include/INCLUDE_ME.md" %}}
+{{%/* /notice */%}}
+````
+
+{{% notice color="fuchsia" title="**Hugo** is _awesome_" icon="fa-fw fab fa-hackerrank" %}}
+{{% include "shortcodes/include/INCLUDE_ME.md" %}}
+{{% /notice %}}
+
+#### Expandable Content Area with `groupid`
+
+If you give multiple expandable boxes the same `groupid`, at most one will be open at any given time. If you open one of the boxes, all other boxes of the same group will close.
+
+````go
+{{%/* notice style="green" title="Expand me..." groupid="notice-toggle" expanded="true" */%}}
+No need to press you!
+{{%/* /notice */%}}
+
+{{%/* notice style="red" title="Expand me..." groupid="notice-toggle" expanded="false" */%}}
+Thank you!
+{{%/* /notice */%}}
+````
+
+{{% notice style="green" title="Expand me..." groupid="notice-toggle" expanded="true" %}}
+No need to press you!
+{{% /notice %}}
+
+{{% notice style="red" title="Expand me..." groupid="notice-toggle" expanded="false" %}}
+Thank you!
+{{% /notice %}}
+
+#### No Content or No Title
+
+````go
+{{%/* notice style="accent" title="Just a bar" */%}}
+{{%/* /notice */%}}
+
+{{%/* notice style="accent" */%}}
+Just a box
+{{%/* /notice */%}}
+````
+
+{{% notice style="accent" title="Just a bar" %}}
+{{% /notice %}}
+
+{{% notice style="accent" %}}
+Just a box
+{{% /notice %}}
+
+#### Various Callouts
+
+````go
+> [!caution] Callouts can have custom titles
+> Like this one.
+
+> [!caution] Title-only callout
+
+> [!note]- Are callouts foldable?
+> Yes! In a foldable callout, the contents are hidden when the callout is collapsed
+
+> [!note]+ Are callouts foldable?
+> Yes! In a foldable callout, the contents are hidden when the callout is collapsed
+
+> [!info] Can callouts be nested?
+> > [!important] Yes!, they can.
+> > > [!tip]  You can even use multiple layers of nesting.
+````
+
+> [!caution] Callouts can have custom titles
+> Like this one.
+
+> [!caution] Title-only callout
+
+> [!note]- Are callouts foldable?
+> Yes! In a foldable callout, the contents are hidden when the callout is collapsed
+
+> [!note]+ Are callouts foldable?
+> Yes! In a foldable callout, the contents are hidden when the callout is collapsed
+
+> [!info] Can callouts be nested?
+> > [!important] Yes!, they can.
+> > > [!tip]  You can even use multiple layers of nesting.
+
+#### Code with Collapsed Colored Borders
+
+````
+> [!secondary]
+> ```c
+> // With colored border in Markdown syntax
+> printf("Hello World!");
+> ```
+
+{{%/* notice style="red" */%}}
+```c
+// With colored border in Shortcode syntax
+printf("Hello World!");
+```
+{{%/* /notice */%}}
+````
+
+> [!secondary]
+> ```c
+> // With colored border in Markdown syntax
+> printf("Hello World!");
+> ```
+
+{{% notice style="red" %}}
+```c
+// With colored border in Shortcode syntax
+printf("Hello World!");
+```
+{{% /notice %}}
+
+#### User-defined Style
+
+Self-defined styles can be [configured](#defining-own-styles) in your `hugo.toml` and used for every shortcode, that accepts a `style` parameter.
+
+````
+> [!magic]
+> Maaagic!
+````
+
+> [!magic]
+> Maaagic!
--- a/docs/content/shortcodes/notice.pir.md
+++ b/docs/content/shortcodes/notice.pir.md
@ -0,0 +1,7 @@
+++
+categories = ["howto", "reference"]
+description = "Disclaimers to help you structure your page"
+options = ["boxStyle"]
+title = "Notice"
+++
+{{< piratify >}}
--- a/docs/content/shortcodes/openapi/_index.en.md
+++ b/docs/content/shortcodes/openapi/_index.en.md
@ -0,0 +1,92 @@
+++
+aliases = "/shortcodes/swagger"
+categories = ["howto", "reference"]
+description = "UI for your OpenAPI / Swagger specifications"
+frontmatter = ["customOpenapiURL", "openapi.errorlevel", "openapi.force"]
+options = ["customOpenapiURL", "openapi.errorlevel", "openapi.force"]
+title = "OpenAPI"
+++
+
+The `openapi` shortcode displays your OpenAPI / Swagger specifications using the [Swagger UI](https://github.com/swagger-api/swagger-ui) library.
+
+## Usage
+
+{{< tabs groupid="shortcode-parameter">}}
+{{% tab title="shortcode" %}}
+
+````go
+{{</* openapi src="https://petstore3.openapi.io/api/v3/openapi.json" */>}}
+````
+
+{{% /tab %}}
+{{% tab title="partial" %}}
+
+````go
+{{ partial "shortcodes/openapi.html" (dict
+  "page" .
+  "src"  "https://petstore3.openapi.io/api/v3/openapi.json"
+)}}
+````
+
+{{% /tab %}}
+{{< /tabs >}}
+
+If you want to print out (or generate a PDF) from your OpenAPI documentation, don't initiate printing directly from the page because the elements are optimized for interactive usage in a browser.
+
+Instead, open the [print preview](authoring/frontmatter/topbar) in your browser and initiate printing from that page. This page is optimized for reading and expands most of the available sections.
+
+### Parameter
+
+| Name                 | Default          | Notes       |
+|----------------------|------------------|-------------|
+| **src**              | _&lt;empty&gt;_  | The path to the to the OpenAPI specification resource or URL to be used. Resource paths adhere to [Hugo's logical path](https://gohugo.io/methods/page/path/). |
+
+## Settings
+
+### Enabling Link Warnings
+
+{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} {{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} You can use `openapi.errorlevel` to control what should happen if a local OpenAPI specification link can not be resolved to a resource.
+
+If not set or empty, any unresolved link is written as given into the resulting output. If set to `warning` the same happens and an additional warning is printed in the built console. If set to `error` an error message is printed and the build is aborted.
+
+Please note that this can not resolve files inside of your `static` directory. The file must be a resource of the page or the site.
+
+Link warnings are also available for [images & links](authoring/frontmatter/linking#enabling-link-and-image-link-warnings) and the [include](shortcodes/include#enabling-link-warnings) shortcode.
+
+{{< multiconfig >}}
+openapi.errorlevel = 'warning'
+{{< /multiconfig >}}
+
+### Loading an External Version of the Swagger UI Library
+
+{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} {{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} The theme uses the shipped Swagger UI library by default.
+
+In case you want do use a different version of the Swagger UI library but don't want to override the shipped version, you can set `customOpenapiURL` to the URL of the external Swagger UI library.
+
+{{< multiconfig >}}
+customOpenapiURL = 'https://unpkg.com/swagger-ui-dist/swagger-ui-bundle.js'
+{{< /multiconfig >}}
+
+### Force Loading of the Swagger UI Library
+
+{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} {{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} The Swagger UI library will be loaded if the page contains an `openapi` shortcode or codefence.
+
+You can force loading the Swagger UI library if no shortcode or codefence was used by setting `openapi.force=true`. If a shortcode or codefence was found, the option has no effect. This comes handy in case you are using scripting to render a spec.
+
+{{< multiconfig >}}
+openapi.force = true
+{{< /multiconfig >}}
+
+### Setting a Specific Swagger UI Theme
+
+The recommended way to configure your Swagger UI theme is to set the default value using the `--OPENAPI-theme` variable in your [color variant stylesheet](configuration/branding/generator). This allows your specs to look pretty when the user switches the color variant.
+
+## Example
+
+### Using Local File
+
+````go
+{{</* openapi src="petstore.json" */>}}
+````
+
+{{< openapi src="petstore.json" >}}
--- a/docs/content/shortcodes/openapi/_index.pir.md
+++ b/docs/content/shortcodes/openapi/_index.pir.md
@ -0,0 +1,9 @@
+++
+aliases = "/pir/shortcodes/swagger"
+categories = ["howto", "reference"]
+description = "UI fer yer OpenAPI / Swaggerrr Specificat'ns"
+frontmatter = ["customOpenapiURL", "openapi.errorlevel", "openapi.force"]
+options = ["customOpenapiURL", "openapi.errorlevel", "openapi.force"]
+title = "OpenAPI"
+++
+{{< piratify >}}
--- a/docs/content/shortcodes/openapi/petstore.json
+++ b/docs/content/shortcodes/openapi/petstore.json
--- a/docs/content/shortcodes/openapi/petstore.yaml
+++ b/docs/content/shortcodes/openapi/petstore.yaml
--- a/docs/content/shortcodes/resources/MaybeTreasure.en.txt
+++ b/docs/content/shortcodes/resources/MaybeTreasure.en.txt
@ -0,0 +1 @@
+Nothing to see here :-(
--- a/docs/content/shortcodes/resources/MaybeTreasure.pir.txt
+++ b/docs/content/shortcodes/resources/MaybeTreasure.pir.txt
@ -0,0 +1 @@
+Harrr, me found a trrreasure!!!
--- a/docs/content/shortcodes/resources/NoTreasure.en.txt
+++ b/docs/content/shortcodes/resources/NoTreasure.en.txt
@ -0,0 +1 @@
+Nothing to see here :-(
--- a/docs/content/shortcodes/resources/Treasure.pir.txt
+++ b/docs/content/shortcodes/resources/Treasure.pir.txt
@ -0,0 +1 @@
+Harrr, me found a trrreasure!!!
--- a/docs/content/shortcodes/resources/hugo.png
+++ b/docs/content/shortcodes/resources/hugo.png
--- a/docs/content/shortcodes/resources/index.en.md
+++ b/docs/content/shortcodes/resources/index.en.md
@ -0,0 +1,86 @@
+++
+categories = ["howto", "reference"]
+description = "List resources contained in a page bundle"
+title = "Resources"
+[[resources]]
+  name = 'MaybeTreasure.txt'
+  src = 'MaybeTreasure.en.txt'
+++
+
+The `resources` shortcode displays links to resources contained in a [page bundle](https://gohugo.io/content-management/page-bundles/).
+
+{{% resources sort="asc" /%}}
+
+## Usage
+
+{{< tabs groupid="shortcode-parameter">}}
+{{% tab title="shortcode" %}}
+
+````go
+{{%/* resources sort="asc" /*/%}}
+````
+
+{{% /tab %}}
+{{% tab title="partial" %}}
+
+````go
+{{ partial "shortcodes/resources.html" (dict
+  "page" .
+  "sort" "asc"
+)}}
+````
+
+{{% /tab %}}
+{{< /tabs >}}
+
+Multilanguage features are not supported directly by the shortcode but rely on Hugo's handling for resource translations applied when the theme iterates over all available resources.
+
+### Parameter
+
+| Name                  | Default         | Notes       |
+|-----------------------|-----------------|-------------|
+| **style**             | `transparent`   | The style scheme used for the box.<br><br>- by severity: `caution`, `important`, `info`, `note`, `tip`, `warning`<br>- by brand color: `primary`, `secondary`, `accent`<br>- by color: `blue`, `cyan`, `green`, `grey`, `magenta`, `orange`, `red`<br>- by special color: `default`, `transparent`, `code`<br><br>You can also [define your own styles](shortcodes/notice#defining-own-styles). |
+| **color**             | see notes       | The [CSS color value](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value) to be used. If not set, the chosen color depends on the **style**. Any given value will overwrite the default.<br><br>- for severity styles: a nice matching color for the severity<br>- for all other styles: the corresponding color |
+| **title**             | 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 styles: `Resources`<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**              | see notes       | [Font Awesome icon name](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 styles: `paperclip`<br><br>If you want no icon, you have to set this parameter to `" "` (a non empty string filled with spaces) |
+| **expanded**          | _&lt;empty&gt;_ | Whether to draw an expander and how the resource list is displayed.<br><br>- _&lt;empty&gt;_: no expander is drawn and the resource list is permanently shown<br>- `true`: the expander is drawn and the resource list is initially shown<br>- `false`: the expander is drawn and the resource list is initially hidden |
+| **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 resources [by name](https://gohugo.io/methods/resource/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)` |
+
+## Examples
+
+### Custom Title, List of Resources Ending in png, jpg or gif
+
+````go
+{{%/* resources title="Related **files**" pattern=".*\.(png|jpg|gif)" /*/%}}
+````
+
+{{% resources title="Related **files**" pattern=".*\.(png|jpg|gif)" /%}}
+
+### Info Styled Box, Descending Sort Order
+
+````go
+{{%/* resources style="info" sort="desc" /*/%}}
+````
+
+{{% resources style="info" sort="desc" /%}}
+
+### With User-Defined Color and Font Awesome Brand Icon
+
+````go
+{{%/* resources color="fuchsia" icon="fa-fw fab fa-hackerrank" /*/%}}
+````
+
+{{% resources color="fuchsia" icon="fa-fw fab fa-hackerrank" /%}}
+
+### Expander with Initially Hidden Resource List
+
+````go
+{{%/* resources style="primary" expanded="false" /*/%}}
+````
+
+{{% resources style="primary" expanded="false" /%}}
+
+### Style, Color, Title and Icons
+
+For further examples for **style**, **color**, **title** and **icon**, see the [`notice` shortcode](shortcodes/notice) documentation. The parameter are working the same way for both shortcodes, besides having different defaults.
--- a/docs/content/shortcodes/resources/index.pir.md
+++ b/docs/content/shortcodes/resources/index.pir.md
@ -0,0 +1,11 @@
+++
+categories = ["howto", "reference"]
+description = "List Rrresources shorrrtcode contained in a plank bundle"
+title = "Resources"
+[[resources]]
+  name = 'MaybeTreasure.txt'
+  src = 'MaybeTreasure.pir.txt'
+++
+{{% resources /%}}
+
+{{< piratify >}}
--- a/docs/content/shortcodes/siteparam.en.md
+++ b/docs/content/shortcodes/siteparam.en.md
@ -0,0 +1,75 @@
+++
+categories = ["howto", "reference"]
+description = "Get value of site params"
+title = "SiteParam"
+++
+
+The `siteparam` shortcode prints values of params contained in your `hugo.toml`.
+
+## Usage
+
+{{< tabs groupid="shortcode-parameter">}}
+{{% tab title="shortcode" %}}
+
+````go
+{{%/* siteparam name="editURL" */%}}
+````
+
+{{% /tab %}}
+{{% tab title="shortcode (positional)" %}}
+
+````go
+{{%/* siteparam "editURL" */%}}
+````
+
+{{% /tab %}}
+{{% tab title="partial" %}}
+
+````go
+{{ partial "shortcodes/siteparam.html" (dict
+  "page" .
+  "name" "editURL"
+)}}
+````
+
+{{% /tab %}}
+{{< /tabs >}}
+
+### Parameter
+
+| Name                 | Position | Default          | Notes       |
+|----------------------|----------|------------------|-------------|
+| **name**             | 1        | _&lt;empty&gt;_  | The name of the site param to be displayed. |
+
+## Examples
+
+### `editURL`
+
+```go
+`editURL` value: {{%/* siteparam name="editURL" */%}}
+```
+
+`editURL` value: {{% siteparam name="editURL" %}}
+
+### Nested Parameter with Markdown and HTML Formatting
+
+To use formatted parameter, add this in your `hugo.toml`:
+
+{{< multiconfig file=hugo >}}
+[markup.goldmark.renderer]
+  unsafe = true
+{{< /multiconfig >}}
+
+Now values containing Markdown will be formatted correctly.
+
+{{< multiconfig file=hugo >}}
+[params]
+  [params.siteparam.test]
+    text = 'A **nested** parameter <b>with</b> formatting'
+{{< /multiconfig >}}
+
+```go
+Formatted parameter: {{%/* siteparam name="siteparam.test.text" */%}}
+```
+
+Formatted parameter: {{% siteparam name="siteparam.test.text" %}}
--- a/docs/content/shortcodes/siteparam.pir.md
+++ b/docs/content/shortcodes/siteparam.pir.md
@ -0,0 +1,6 @@
+++
+categories = ["howto", "reference"]
+description = "Get value o' ship parrrams"
+title = "SiteParam"
+++
+{{< piratify >}}
--- a/docs/content/shortcodes/tab.en.md
+++ b/docs/content/shortcodes/tab.en.md
@ -0,0 +1,169 @@
+++
+categories = ["howto", "reference"]
+description = "Show content in a single tab"
+title = "Tab"
+++
+
+You can use a `tab` shortcode to display a single tab with a title.
+
+{{% tab title="c" %}}
+
+```python
+printf("Hello World!");
+```
+
+{{% /tab %}}
+
+## Usage
+
+{{< tabs groupid="shortcode-parameter">}}
+{{% tab title="shortcode" %}}
+
+````go
+{{%/* tab title="c" */%}}
+```c
+printf("Hello World!");
+```
+{{%/* /tab */%}}
+````
+
+{{% /tab %}}
+{{% tab title="partial" %}}
+
+````go
+{{ partial "shortcodes/tab.html" (dict
+  "page"  .
+  "title" "c"
+  "content" ("```c\nprintf(\"Hello World!\")\n```" | .RenderString)
+)}}
+````
+
+{{% /tab %}}
+{{< /tabs >}}
+
+If you want multiple tabs grouped together you can wrap your tabs into the [`tabs` shortcode](shortcodes/tabs).
+
+If you want further options when using a single code tab, you can also use the [`highlight` shortcode](shortcodes/highlight).
+
+### Parameter
+
+| Name                  | Default         | Notes       |
+|-----------------------|-----------------|-------------|
+| **style**             | see notes       | The style scheme used for the tab. If you don't set a style and you display a single code block inside of the tab, its default styling will adapt to that of a `code` block. Otherwise `default` is used.<br><br>- by severity: `caution`, `important`, `info`, `note`, `tip`, `warning`<br>- by brand color: `primary`, `secondary`, `accent`<br>- by color: `blue`, `cyan`, `green`, `grey`, `magenta`, `orange`, `red`<br>- by special color: `default`, `transparent`, `code`<br><br>You can also [define your own styles](shortcodes/notice#defining-own-styles). |
+| **color**             | see notes       | The [CSS color value](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value) to be used. If not set, the chosen color depends on the **style**. Any given value will overwrite the default.<br><br>- for severity styles: a nice matching color for the severity<br>- for all other styles: the corresponding color |
+| **title**             | see notes       | Arbitrary title for the tab. 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 styles: _&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**              | see notes       | [Font Awesome icon name](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 styles: _&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 the tab. |
+
+## Examples
+
+### Single Code Block with Collapsed Margins
+
+````go
+{{%/* tab title="Code" */%}}
+```python
+printf("Hello World!");
+```
+{{%/* /tab */%}}
+````
+
+{{% tab title="Code" %}}
+
+```python
+printf("Hello World!");
+```
+
+{{% /tab %}}
+
+### Mixed Markdown Content
+
+````go
+{{%/* tab title="_**Mixed**_" */%}}
+A tab can not only contain code but arbitrary text. In this case text **and** code will get a margin.
+```python
+printf("Hello World!");
+```
+{{%/* /tab */%}}
+````
+
+{{% tab title="_**Mixed**_" %}}
+
+A tab can not only contain code but arbitrary text. In this case text **and** code will get a margin.
+
+```python
+printf("Hello World!");
+```
+
+{{% /tab %}}
+
+### Understanding `style` and `color` Behavior
+
+The `style` parameter affects how the `color` parameter is applied.
+
+````go
+{{</* tabs */>}}
+{{%/* tab title="just colored style" style="blue" */%}}
+The `style` parameter is set to a color style.
+
+This will set the background to a lighter version of the chosen style color as configured in your theme variant.
+{{%/* /tab */%}}
+{{%/* tab title="just color" color="blue" */%}}
+Only the `color` parameter is set.
+
+This will set the background to a lighter version of the chosen CSS color value.
+{{%/* /tab */%}}
+{{%/* tab title="default style and color" style="default" color="blue" */%}}
+The `style` parameter affects how the `color` parameter is applied.
+
+The `default` style will set the background to your `--MAIN-BG-color` as configured for your theme variant resembling the default style but with different color.
+{{%/* /tab */%}}
+{{%/* tab title="just severity style" style="info" */%}}
+The `style` parameter is set to a severity style.
+
+This will set the background to a lighter version of the chosen style color as configured in your theme variant and also affects the chosen icon.
+{{%/* /tab */%}}
+{{%/* tab title="severity style and color" style="info" color="blue" */%}}
+The `style` parameter affects how the `color` parameter is applied.
+
+This will set the background to a lighter version of the chosen CSS color value and also affects the chosen icon.
+{{%/* /tab */%}}
+{{</* /tabs */>}}
+````
+
+{{< tabs >}}
+{{% tab title="just colored style" style="blue" %}}
+
+The `style` parameter is set to a color style.
+
+This will set the background to a lighter version of the chosen style color as configured in your theme variant.
+
+{{% /tab %}}
+{{% tab title="just color" color="blue" %}}
+
+Only the `color` parameter is set.
+
+This will set the background to a lighter version of the chosen CSS color value.
+
+{{% /tab %}}
+{{% tab title="default style and color" style="default" color="blue" %}}
+
+The `style` parameter affects how the `color` parameter is applied.
+
+The `default` style will set the background to your `--MAIN-BG-color` as configured for your theme variant resembling the default style but with different color.
+
+{{% /tab %}}
+{{% tab title="just severity style" style="info" %}}
+
+The `style` parameter is set to a severity style.
+
+This will set the background to a lighter version of the chosen style color as configured in your theme variant and also affects the chosen icon.
+
+{{% /tab %}}
+{{% tab title="severity style and color" style="info" color="blue" %}}
+
+The `style` parameter affects how the `color` parameter is applied.
+
+This will set the background to a lighter version of the chosen CSS color value and also affects the chosen icon.
+
+{{% /tab %}}
+{{< /tabs >}}
--- a/docs/content/shortcodes/tab.pir.md
+++ b/docs/content/shortcodes/tab.pir.md
@ -0,0 +1,6 @@
+++
+categories = ["howto", "reference"]
+description = "Show rrrambl'n 'n a single tab"
+title = "Tab"
+++
+{{< piratify >}}
--- a/docs/content/shortcodes/tabs.en.md
+++ b/docs/content/shortcodes/tabs.en.md
@ -0,0 +1,285 @@
+++
+categories = ["howto", "reference"]
+description = "Show content in tabbed views"
+title = "Tabs"
+++
+
+The `tabs` shortcode displays arbitrary content in an unlimited number of tabs.
+
+{{< tabs title="hello." >}}
+{{% tab title="py" %}}
+
+```python
+print("Hello World!")
+```
+
+{{% /tab %}}
+{{% tab title="sh" %}}
+
+```bash
+echo "Hello World!"
+```
+
+{{% /tab %}}
+{{% tab title="c" %}}
+
+```c
+printf("Hello World!");
+```
+
+{{% /tab %}}
+{{< /tabs >}}
+
+## Usage
+
+{{< tabs groupid="shortcode-parameter">}}
+{{% tab title="shortcode" %}}
+
+````go
+{{</* tabs title="hello." */>}}
+{{%/* tab title="py" */%}}
+```python
+print("Hello World!")
+```
+{{%/* /tab */%}}
+{{%/* tab title="sh" */%}}
+```bash
+echo "Hello World!"
+```
+{{%/* /tab */%}}
+{{%/* tab title="c" */%}}
+```c
+printf"Hello World!");
+```
+{{%/* /tab */%}}
+{{</* /tabs */>}}
+````
+
+{{% /tab %}}
+{{% tab title="partial" %}}
+
+````go
+{{ partial "shortcodes/tabs.html" (dict
+  "page"  .
+  "title" "hello."
+  "content" (slice
+    (dict
+      "title" "py"
+      "content" ("```python\nprint(\"Hello World!\")\n```" | .RenderString)
+    )
+    (dict
+      "title" "sh"
+      "content" ("```bash\necho \"Hello World!\"\n```" | .RenderString)
+    )
+    (dict
+      "title" "c"
+      "content" ("```c\nprintf(\"Hello World!\");\n```" | .RenderString)
+    )
+  )
+)}}
+````
+
+{{% /tab %}}
+{{< /tabs >}}
+
+If you just want a single tab you can instead call the [`tab` shortcode](shortcodes/tab) standalone.
+
+Also follow the above link to see the parameter for a nested tab.
+
+### Parameter
+
+| Name                  | Default              | Notes       |
+|-----------------------|----------------------|-------------|
+| **groupid**           | _&lt;random&gt;_     | Arbitrary name of the group the tab view belongs to.<br><br>Tab views with the same **groupid** sychronize their selected tab. The tab selection is restored automatically based on the `groupid` for tab view. If the selected tab can not be found in a tab group the first tab is selected instead.<br><br>This sychronization applies to the whole site! |
+| **style**             | _&lt;empty&gt;_      | Sets a default value for every contained tab. Can be overridden by each tab. See the [`tab` shortcode](shortcodes/tab#parameter) for possible values. |
+| **color**             | _&lt;empty&gt;_      | Sets a default value for every contained tab. Can be overridden by each tab. See the [`tab` shortcode](shortcodes/tab#parameter) for possible values. |
+| **title**             | _&lt;empty&gt;_      | Arbitrary title written in front of the tab view. |
+| **icon**              | _&lt;empty&gt;_      | [Font Awesome icon name](shortcodes/icon#finding-an-icon) set to the left of the title. |
+| _**&lt;content&gt;**_ | _&lt;empty&gt;_      | Arbitrary number of tabs defined with the `tab` sub-shortcode. |
+
+## Examples
+
+### Behavior of the `groupid`
+
+See what happens to the tab views while you select different tabs.
+
+While pressing a tab of Group A switches all tab views of Group A in sync (if the tab is available), the tabs of Group B are left untouched.
+
+{{< tabs >}}
+{{% tab title="Group A, Tab View 1" %}}
+````go
+{{</* tabs groupid="a" */>}}
+{{%/* tab title="json" */%}}
+{{</* highlight json "linenos=true" */>}}
+{ "Hello": "World" }
+{{</* /highlight */>}}
+{{%/* /tab */%}}
+{{%/* tab title="_**XML**_ stuff" */%}}
+```xml
+<Hello>World</Hello>
+```
+{{%/* /tab */%}}
+{{%/* tab title="text" */%}}
+    Hello World
+{{%/* /tab */%}}
+{{</* /tabs */>}}
+````
+{{% /tab %}}
+{{% tab title="Group A, Tab View 2" %}}
+````go
+{{</* tabs groupid="a" */>}}
+{{%/* tab title="json" */%}}
+{{</* highlight json "linenos=true" */>}}
+{ "Hello": "World" }
+{{</* /highlight */>}}
+{{%/* /tab */%}}
+{{%/* tab title="XML stuff" */%}}
+```xml
+<Hello>World</Hello>
+```
+{{%/* /tab */%}}
+{{</* /tabs */>}}
+````
+{{% /tab %}}
+{{% tab title="Group B" %}}
+````go
+{{</* tabs groupid="b" */>}}
+{{%/* tab title="json" */%}}
+{{</* highlight json "linenos=true" */>}}
+{ "Hello": "World" }
+{{</* /highlight */>}}
+{{%/* /tab */%}}
+{{%/* tab title="XML stuff" */%}}
+```xml
+<Hello>World</Hello>
+```
+{{%/* /tab */%}}
+{{</* /tabs */>}}
+````
+{{% /tab %}}
+{{< /tabs >}}
+
+
+#### Group A, Tab View 1
+
+{{< tabs groupid="tab-example-a" >}}
+{{% tab title="json" %}}
+{{< highlight json "linenos=true" >}}
+{ "Hello": "World" }
+{{< /highlight >}}
+{{% /tab %}}
+{{% tab title="_**XML**_ stuff" %}}
+```xml
+<Hello>World</Hello>
+```
+{{% /tab %}}
+{{% tab title="text" %}}
+
+    Hello World
+
+{{% /tab %}}
+{{< /tabs >}}
+
+#### Group A, Tab View 2
+
+{{< tabs groupid="tab-example-a" >}}
+{{% tab title="json" %}}
+{{< highlight json "linenos=true" >}}
+{ "Hello": "World" }
+{{< /highlight >}}
+{{% /tab %}}
+{{% tab title="XML stuff" %}}
+```xml
+<Hello>World</Hello>
+```
+{{% /tab %}}
+{{< /tabs >}}
+
+#### Group B
+
+{{< tabs groupid="tab-example-b" >}}
+{{% tab title="json" %}}
+{{< highlight json "linenos=true" >}}
+{ "Hello": "World" }
+{{< /highlight >}}
+{{% /tab %}}
+{{% tab title="XML stuff" %}}
+```xml
+<Hello>World</Hello>
+```
+{{% /tab %}}
+{{< /tabs >}}
+
+### Nested Tab Views and Color
+
+In case you want to nest tab views, the parent tab that contains nested tab views needs to be declared with `{{</* tab */>}}` instead of `{{%/* tab */%}}`. Note, that in this case it is not possible to put markdown in the parent tab.
+
+You can also set style and color parameter for all tabs and overwrite them on tab level. See the [`tab` shortcode](shortcodes/tab#parameter) for possible values.
+
+````go
+{{</* tabs groupid="main" style="primary" title="Rationale" icon="thumbtack" */>}}
+{{</* tab title="Text" */>}}
+  Simple text is possible here...
+  {{</* tabs groupid="tabs-example-language" */>}}
+  {{%/* tab title="python" */%}}
+  Python is **super** easy.
+
+  - most of the time.
+  - if you don't want to output unicode
+  {{%/* /tab */%}}
+  {{%/* tab title="bash" */%}}
+  Bash is for **hackers**.
+  {{%/* /tab */%}}
+  {{</* /tabs */>}}
+{{</* /tab */>}}
+
+{{</* tab title="Code" style="default" color="darkorchid" */>}}
+  ...but no markdown
+  {{</* tabs groupid="tabs-example-language" */>}}
+  {{%/* tab title="python" */%}}
+  ```python
+  print("Hello World!")
+  ```
+  {{%/* /tab */%}}
+  {{%/* tab title="bash" */%}}
+  ```bash
+  echo "Hello World!"
+  ```
+  {{%/* /tab */%}}
+  {{</* /tabs */>}}
+{{</* /tab */>}}
+{{</* /tabs */>}}
+````
+
+{{< tabs groupid="main" style="primary" title="Rationale" icon="thumbtack" >}}
+{{< tab title="Text" >}}
+  Simple text is possible here...
+  {{< tabs groupid="tabs-example-language" >}}
+  {{% tab title="python" %}}
+  Python is **super** easy.
+
+  - most of the time.
+  - if you don't want to output unicode
+  {{% /tab %}}
+  {{% tab title="bash" %}}
+  Bash is for **hackers**.
+  {{% /tab %}}
+  {{< /tabs >}}
+{{< /tab >}}
+
+{{< tab title="Code" style="default" color="darkorchid" >}}
+  ...but no markdown
+  {{< tabs groupid="tabs-example-language" >}}
+  {{% tab title="python" %}}
+  ```python
+  print("Hello World!")
+  ```
+  {{% /tab %}}
+  {{% tab title="bash" %}}
+  ```bash
+  echo "Hello World!"
+  ```
+  {{% /tab %}}
+  {{< /tabs >}}
+{{< /tab >}}
+{{< /tabs >}}
--- a/docs/content/shortcodes/tabs.pir.md
+++ b/docs/content/shortcodes/tabs.pir.md
@ -0,0 +1,6 @@
+++
+categories = ["howto", "reference"]
+description = "Show rrrambl'n 'n tabbed views"
+title = "Tabs"
+++
+{{< piratify >}}