shortcodes: revamp shortcodes #260 #261

- supply named parameter if missing #260
- fix boolean parameter if given as string #261
- revise documentation

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

@@ -20,7 +20,9 @@ This document shows you what's new in the latest release. For a detailed list of
 
 - **Breaking**: Because anchor hover color was not configurable without introducing more complexitity to the variant stylesheets, we decided to remove `--MAIN-ANCHOR-color` instead. You don't need to change anything in your custom color stylesheet as the anchors now get their colors from `--MAIN-LINK-color` and `--MAIN-ANCHOR-HOVER-color` respectivley.
 
-- **New**: The [`notice`]({{% relref "shortcodes/notice" %}}) shortcode can now be used with named parameters. The old positional parameters are still supported, so you don't need to change anything in your installation.
+- **New**: All shortcodes now support named parameter. The positional parameter are still supported but will not be enhanced with new features, so you don't need to change anything in your installation.
+
+  This applies to [`expand`]({{% relref "shortcodes/expand" %}}) , [`include`]({{% relref "shortcodes/include" %}}) , [`notice`]({{% relref "shortcodes/notice" %}}) and [`siteparam`]({{% relref "shortcodes/siteparam" %}}) .
 
 - **New**: The [`button`]({{% relref "shortcodes/button" %}}) shortcode received some love and now has a parameter for the color style similar to other shortcodes.
 
@@ -28,6 +30,8 @@ This document shows you what's new in the latest release. For a detailed list of
 
   These two colors are the default for other, more specific color variables. You don't need to change anything in your existing custom color stylesheets as those variables get reasonable default values.
 
+- **New**: The documentation for all shortcodes were revised.
+
 ---
 
 ## 3.4.0

exampleSite/content/shortcodes/attachments.en.md

@@ -9,30 +9,29 @@ The `attachments` shortcode displays a list of files attached to a page with adj
 
 ## Usage
 
-The shortcurt lists files found in a **specific folder**.
-
 ````go
 {{%/* attachments /*/%}}
 ````
 
+The shortcurt lists files found in a specific folder.
 
-Currently, it support two implementations for pages
+Currently, it supports two implementations for pages
 
-1. If your page is a Markdown file, attachements must be placed in a **folder** named like your page and ending with **.files**.
+1. If your page is a Markdown file, attachements must be placed in a folder named like your page and ending with `.files`.
 
     > * content
     >   * _index.md
-    >   * page.files
+    >   * **page.files**
     >      * attachment.pdf
     >   * page.md
 
-2. If your page is a **folder**, attachements must be placed in a nested **'files'** folder.
+2. If your page is a folder, attachements must be placed in a nested `files` folder.
 
     > * content
     >   * _index.md
     >   * page
     >      * index.md
-    >      * files
+    >      * **files**
     >          * attachment.pdf
 
 Be aware that if you use a multilingual website, you will need to have as many folders as languages.
@@ -40,40 +39,32 @@ Be aware that if you use a multilingual website, you will need to have as many f
 
 ### Parameter
 
-| Name        | Optional  | Default       | Notes       |
+| Name        | Default       | Notes       |
-|:------------|:----------|:--------------|:------------|
+|:------------|:--------------|:------------|
-| **style**   | yes       | `transparent` | The color scheme used to highlight the box content.<br/><br/>- by severity: `info`, `note`, `tip`, `warning`<br/>- by brand color: `primary`, `secondary`<br/>- by color: `blue`, `green`, `grey`, `orange`, `red`<br/>- by special color: `default`, `transparent` |
+| **style**   | `transparent` | The color scheme used to highlight the box content.<br/><br/>- by severity: `info`, `note`, `tip`, `warning`<nd color: `primary`, `secondary`<br/>- by color: `blue`, `green`, `grey`, `orange`, `red`<br/>- by special color: `default`,t` |
-| **title**   | yes       | see notes     | Arbitray text for the box title. Depending on the **style** there may be a default title. Any given value will overwrite the default.<br/><br/>- for severity styles: the matching title for the severity<br/>- for all other colors: `Attachments`<br/><br/>If you want no title, you have to set this parameter to `" "` (a non empty string filled with spaces) |
+| **title**   | see notes     | Arbitray text for the box title. Depending on the **style** there may be a default title. Any given value will overwault.<br/><br/>- for severity styles: the matching title for the severity<br/>- for all other colors: `Attachments`<br/><br/>If you wa you have to set this parameter to `" "` (a non empty string filled with spaces) |
-| **icon**    | yes       | see notes     | [Font Awesome icon name]({{%relref "cont/icons#finding-an-icon" %}}) set to the left of the title. Depending on the **style** there may be a default icon. Any given value will overwrite the default.<br/><br/>- for severity styles: a nice matching icon for the severity<br/>- for all other colors: `paperclip`<br/><br/>If you want no icon, you have to set this parameter to `" "` (a non empty string filled with spaces) |
+| **icon**    | see notes     | [Font Awesome icon name]({{%relref "cont/icons#finding-an-icon" %}}) set to the left of the title. Depending le** there may be a default icon. Any given value will overwrite the default.<br/><br/>- for severity styles: a nice matching iseverity<br/>- for all other colors: `paperclip`<br/><br/>If you want no icon, you have to set this parameter to `" "` (a non empty d with spaces) |
-| **sort**    | yes       | `asc`         | Sorting the output in `asc`ending or `desc`ending order. |
+| **sort**    | `asc`         | Sorting the output in `asc`ending or `desc`ending order. |
-| **pattern** | yes       | `.*`          | 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)` |
+| **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)` |
 
 ## Examples
 
-### Custom title, list of attachments ending in pdf or mp4
+### Custom Title, List of Attachments Ending in pdf or mp4
-
-{{% attachments title="Related files" pattern=".*(pdf|mp4)" /%}}
-
-{{% expand "Show markup" %}}
 
 ````go
 {{%/* attachments title="Related files" pattern=".*(pdf|mp4)" /*/%}}
 ````
 
-{{% /expand %}}
+{{% attachments title="Related files" pattern=".*(pdf|mp4)" /%}}
 
-### Info styled box, descending sort order
+### Info Styled Box, Descending Sort Order
-
-{{% attachments style="info" sort="desc" /%}}
-
-{{% expand "Show markup" %}}
 
 ````go
 {{%/* attachments style="info" sort="desc" /*/%}}
 ````
 
-{{% /expand %}}
+{{% attachments style="info" sort="desc" /%}}
 
-### Style and icons
+### Style and Icons
 
 For further examples for **style**, **title** and **icon**, see the [`notice` shortcode]({{% relref "shortcodes/notice" %}}) documentation. The parameter are working the same way for both shortcodes, besides having different defaults.

exampleSite/content/shortcodes/button.en.md

@@ -5,45 +5,66 @@ title = "Button"
 
 The `button` shortcode displays a clickable button with adjustable color, title and icon.
 
-{{% button href="https://gohugo.io/" icon="download" icon-position="right" %}}Get Hugo{{% /button %}}
+{{% button href="https://gohugo.io/" %}}Get Hugo{{% /button %}}
-{{% button href="https://gohugo.io/" style="default" %}}Get Hugo{{% /button %}}
+{{% button href="https://gohugo.io/" style="warning" icon="dragon" %}}Get Hugo{{% /button %}}
-{{% button href="https://gohugo.io/" icon="dragon" style="warning" %}}Get Hugo{{% /button %}}
 
 ## Usage
 
-Once the button is clicked, it opens another browser tab for the given URL.
-
 ````go
-{{%/* button href="https://gohugo.io/" icon="download" %}}Get Hugo{{% /button */%}}
+{{%/* button href="https://gohugo.io/" %}}Get Hugo{{% /button */%}}
+{{%/* button href="https://gohugo.io/" style="warning" icon="dragon" %}}Get Hugo{{% /button */%}}
 ````
 
+Once the button is clicked, it opens another browser tab for the given URL.
+
 ### Parameter
 
-| Name                  | Optional  | Default         | Notes       |
+| Name                  | Default         | Notes       |
-|:----------------------|:----------|:----------------|:------------|
+|:----------------------|:----------------|:------------|
-| **href**              | yes       | _<empty>_ | The destination URL for the button. If this parameter is not set, the button will do nothing but is still displayed as clickable. |
+| **href**              | _<empty>_ | The destination URL for the button. If this parameter is not set, the button will do nothing but is still displayed as clickable. |
-| **style**             | yes       | `transparent`   | The color scheme used to paint the button.<br/><br/>- by severity: `info`, `note`, `tip`, `warning`<br/>- by brand color: `primary`, `secondary`<br/>- by color: `blue`, `green`, `grey`, `orange`, `red`<br/>- by special color: `default`, `transparent` |
+| **style**             | `transparent`   | The color scheme used to paint the button.<br/><br/>- by severity: `info`, `note`, `tip`, `warning`<br/>- by brand color: `primary`, `secondary`<br/>- by color: `blue`, `green`, `grey`, `orange`, `red`<br/>- by special color: `default`, `transparent` |
-| **icon**              | yes       | see notes       | [Font Awesome icon name]({{%relref "cont/icons#finding-an-icon" %}}) set to the left of the title. Depending on the **style** there may be a default icon. Any given value will overwrite the default.<br/><br/>- for severity styles: a nice matching icon for the severity<br/>- for all other colors: _&lt;empty&gt;_<br/><br/>If you want no icon for a severity style, you have to set this parameter to `" "` (a non empty string filled with spaces) |
+| **icon**              | see notes       | [Font Awesome icon name]({{%relref "cont/icons#finding-an-icon" %}}) set to the left of the title. Depending on the **style** there may be a default icon. Any given value will overwrite the default.<br/><br/>- for severity styles: a nice matching icon for the severity<br/>- for all other colors: _&lt;empty&gt;_<br/><br/>If you want no icon for a severity style, you have to set this parameter to `" "` (a non empty string filled with spaces) |
-| **iconposition**      | yes       | `left`          | Places the icon to the `left` or `right` of the title. |
+| **iconposition**      | `left`          | Places the icon to the `left` or `right` of the title. |
-| _**&lt;content&gt;**_ | yes       | see notes       | Arbitray 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 colors: _&lt;empty&gt;_<br/><br/>If you want no title for a severity style, you have to set this parameter to `" "` (a non empty string filled with spaces) |
+| _**&lt;content&gt;**_ | see notes       | Arbitray 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 colors: _&lt;empty&gt;_<br/><br/>If you want no title for a severity style, you have to set this parameter to `" "` (a non empty string filled with spaces) |
 
 ## Examples
 
 ### Style
 
-#### by Severity
+#### By Severity
+
+````go
+{{%/* 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="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
+
+#### 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="primary" %}}Get Hugo{{% /button %}}
 {{% button href="https://gohugo.io/" style="secondary" %}}Get Hugo{{% /button %}}
 
-#### by Color
+#### By Color
+
+````go
+{{%/* button href="https://gohugo.io/" style="blue" %}}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="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="green" %}}Get Hugo{{% /button %}}
@@ -51,27 +72,48 @@ Once the button is clicked, it opens another browser tab for the given URL.
 {{% button href="https://gohugo.io/" style="orange" %}}Get Hugo{{% /button %}}
 {{% button href="https://gohugo.io/" style="red" %}}Get Hugo{{% /button %}}
 
-#### by Special Color
+#### 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
 
-#### to the left
+#### 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
+#### To the Right
+
+````go
+{{%/* button href="https://gohugo.io/" icon="download" icon-position="right" %}}Get Hugo{{% /button */%}}
+````
 
 {{% button href="https://gohugo.io/" icon="download" icon-position="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 %}}
 
 ### Other
 
 #### Severity Style with all Defaults
 
+````go
+{{%/* button href="https://gohugo.io/" style="tip" %}}{{% /button */%}}
+````
+
 {{% button href="https://gohugo.io/" style="tip" %}}{{% /button %}}

exampleSite/content/shortcodes/children/_index.en.md

@@ -4,21 +4,29 @@ description = "List the child pages of a page"
 title = "Children"
 +++
 
-Use the children shortcode to list the child pages of a page and the further descendants (children's children). By default, the shortcode displays links to the child pages.
+The `children` shortcode lists the child pages of a page and its descendants .
 
 ## Usage
 
-| Parameter | Default | Description |
+````go
-|:--|:--|:--|
+{{%/* children */%}}
-| page | _current_ | Specify the page name (section name) to display children for |
+````
-| 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 |
-| description  | "false" | Allows you to include a short text under each page in the list. When no description exists for the page, children shortcode takes the first 70 words of your content. [Read more info about summaries on gohugo.io](https://gohugo.io/content/summaries/) |
-| depth | 1 | Enter a number to specify the depth of descendants to display. For example, if the value is 2, the shortcode will display 2 levels of child pages.  **Tips:** set 999 to get all descendants |
-| sort | [ordersectionsby]({{% relref "basics/configuration#global-site-parameters" %}}) | Sort children by **weight**, to sort on menu order - **title**, to sort alphabetically on menu label. If not set it is sorted by the `ordersectionsby` setting of the site and the pages frontmatter |
 
-## Demo
+### Parameter
+
+| Name               | Default           | Notes       |
+|:-------------------|:------------------|:------------|
+| **page**           | _<current>_ | Specify the page name (section name) to display children for. |
+| **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 aswell. |
+| **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**           | see notes         | The sort order of the displayed list.<br/><br/>If not set it is sorted by the [`ordersectionsby`]({{% relref "basics/configuration#global-site-parameters" %}}) setting of the site and the pages frontmatter<br/><br/>- `weight`: to sort on menu order<br/>- `title`: to sort alphabetically on menu label. |
+
+## Examples
+
+### All Default
 
 ````go
 {{%/* children  */%}}
@@ -26,26 +34,34 @@ Use the children shortcode to list the child pages of a page and the further des
 
 {{% children %}}
 
+### With Description
+
 ````go
 {{%/* children description="true" */%}}
 ````
 
 {{%children description="true" %}}
 
+### Infinte 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="999" */%}}
+{{%/* children containerstyle="div" style="div" depth="3" */%}}
 ````
 
-{{% children containerstyle="div" style="div" depth="999" %}}
+{{% children containerstyle="div" style="div" depth="3" %}}

exampleSite/content/shortcodes/expand.en.md

@@ -1,80 +1,63 @@
 +++
-description = "Displays an expandable/collapsible section of text on your page"
+description = "Expandable/collapsible sections of text"
 title = "Expand"
 +++
 
-The Expand shortcode displays an expandable/collapsible section of text on your page.
+The `expand` shortcode displays an expandable/collapsible section of text.
+
+{{% expand title="Expand me..." %}}Thank you!{{% /expand %}}
 
 ## Usage
 
+While the examples are using named parameter you are free to use positional aswell.
+
+{{< tabs groupId="shortcode-parameter">}}
+{{% tab name="named" %}}
+
 ````go
-{{%/* expand [ <string> [ "true" | "false" ] ] */%}}
+{{%/* expand title="Expand me..." */%}}Thank you!{{%/* /expand */%}}
-Yes!
-{{%/* /expand */%}}
 ````
 
-The first optional parameter defines the text that appears next to the expand/collapse icon. The default text is `"Expand me..."`.
+{{% /tab %}}
+{{% tab name="positional" %}}
+
+````go
+{{%/* expand "Expand me..." */%}}Thank you!{{%/* /expand */%}}
+````
+
+{{% /tab %}}
+{{< /tabs >}}
+
+### Parameter
+
+| Name                  | Position | Default          | Notes       |
+|:----------------------|:---------|:-----------------|:------------|
+| **title**             | 1        | `"Expand me..."` | Arbitray text to appear next to the expand/collapse icon. |
+| **open**              | 2        | `false`          | When `true` the content text will be initially shown as expanded. |
+| _**&lt;content&gt;**_ |          | _&lt;empty&gt;_  | Arbitray text to be displayed on expand. |
 
-The second optional parameter controls if the block is initially shown as expanded (`"true"`) or collapsed (`"false"`). The default ist `"false"`.
 ## Examples
 
-{{% expand "I'll tell you a secret..." %}}
+### All Defaults
-...maybe the next time you'll open this expander!
-{{% /expand %}}
 
-### All defaults
-
-{{% expand %}}
-Yes, you did it!
-{{% /expand %}}
-
-{{% expand "Show markup" "true" %}}
 ````go
-{{%/* expand */%}}
+{{%/* expand */%}}Yes, you did it!{{%/* /expand */%}}
-Yes, you did it!
-{{%/* /expand */%}}
 ````
-{{% /expand %}}
 
-### Initially expanded
+{{% expand %}}Yes, you did it!{{% /expand %}}
 
-{{% expand "Expand me..." "true" %}}
+### Initially Expanded
-No need to press you!
-{{% /expand %}}
 
-{{% expand "Show markup" "true" %}}
 ````go
-{{%/* expand "Expand me..." "true" */%}}
+{{%/* expand title="Expand me..." open="true" */%}}No need to press you!{{%/* /expand */%}}
-No need to press you!
-{{%/* /expand */%}}
 ````
-{{% /expand %}}
 
-### Arbitrary text
+{{% expand title="Expand me..." open="true" %}}No need to press you!{{% /expand %}}
 
-{{% expand "Show me almost endless possibilities" %}}
+### Arbitrary Text
-Some expandable text.
 
-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 possiblities are endless (almost - including other shortcodes may or may not work)
-{{% /expand %}}
-
-{{% expand "Show markup" %}}
 ````go
-{{%/* expand "Show me almost endless possibilities" */%}}
+{{%/* expand title="Show me almost endless possibilities" */%}}
-Some expandable text.
-
 You can add standard markdown syntax:
 
 - multiple paragraphs
@@ -90,4 +73,19 @@ You can add standard markdown syntax:
 > the possiblities 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 possiblities are endless (almost - including other shortcodes may or may not work)
 {{% /expand %}}

exampleSite/content/shortcodes/include.en.md

@@ -1,28 +1,47 @@
 +++
-description = "Displays content from other Markdown files"
+description = "Displays content from other files"
 title = "Include"
 +++
 
-The include shortcode includes other files from your project inside of the current file. This can even contain Markdown and will be taken into account when generating the table of contents.
+The `include` shortcode includes other files from your project inside of the current page.
 
 ## Usage
 
+While the examples are using named parameter you are free to use positional aswell.
+
+{{< tabs groupId="shortcode-parameter">}}
+{{% tab name="named" %}}
+
+
 ````go
-{{%/* include <string> [ "true" | "false" ] */%}}
+{{%/* include file="shortcodes/INCLUDE_ME.md" */%}}
 ````
 
-The first required parameter is the path to the file to be included.
+{{% /tab %}}
+{{% tab name="positional" %}}
 
-If the file's content will be displayed as HTML, the second optional parameter controls if the first heading of the included file should be displayed (`"true"`)- which is the default - or be hidden.
-
-## Examples
-
-### Arbitray content
-
-{{% include "shortcodes/INCLUDE_ME.md" %}}
-
-{{% expand "Show markup" %}}
 ````go
 {{%/* include "shortcodes/INCLUDE_ME.md" */%}}
 ````
-{{% /expand %}}
+
+{{% /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 file to be included. Path resolution adheres to [Hugo's build-in `readFile` function](https://gohugo.io/functions/readfile/) |
+| **showfirstheading** | 2        | `true`           | When `false` and the included file contains headings, the first heading will be hidden. This comes in handy, eg. if you include otherwise standalone Markdown files. |
+
+## Examples
+
+### Arbitray Content
+
+````go
+{{%/* include "shortcodes/INCLUDE_ME.md" */%}}
+````
+
+{{% include "shortcodes/INCLUDE_ME.md" %}}

exampleSite/content/shortcodes/mermaid.en.md

@@ -1,9 +1,15 @@
 +++
-description = "Generation of diagram and flowchart from text in a similar manner as Markdown"
+description = "Generate diagrams and flowcharts from text"
 title = "Mermaid"
 +++
 
-[Mermaid](https://mermaidjs.github.io/) is a library helping you to generate diagram and flowcharts from text, in a similar manner as Markdown.
+With the [Mermaid](https://mermaidjs.github.io/) library and shortcode, you can  generate diagrams and flowcharts from text, in a similar manner as Markdown.
+
+{{< mermaid >}}
+graph LR;
+    If --> Then
+    Then --> Else
+{{< /mermaid >}}
 
 {{% notice note %}}
 This only works in modern browsers.
@@ -15,197 +21,47 @@ Due to limitations with [Mermaid](https://github.com/mermaid-js/mermaid/issues/1
 
 ## Usage
 
-Just insert your Mermaid code in the `mermaid` shortcode like this:
+The generated graphs can be be panned by dragging them and zoomed by using the mousewheel. On mobile devices you can use finger gestures.
 
-````go
+While the examples are using shortcode syntax it is recommended to use codefence syntax instead. This is because more and more other software supports Mermaid codefences (eg. GitHub) and so your markdown becomes more portable.
-{{</* mermaid [ align=("left"|"right"|"center"|"justify") ] */>}}
-classDiagram
-    Person *-- Dog
-{{</* /mermaid */>}}
-````
 
-You can set an optional `align` attribute which defaults to `"center"`.
+{{% notice note %}}
+To use codefence syntax you have to turn off `guessSyntax` for the `markup.highlight` setting ([see the configuration section](#configuration)).
+{{% /notice %}}
 
-If you don't need alignment you can use the alternative syntax using code fences if you have turned off `guessSyntax` for the `markup.highlight` setting (see below):
+{{< tabs groupId="shortcode-codefence">}}
+{{% tab name="codefence" %}}
 
 ````plaintext
 ```mermaid
-classDiagram
+graph LR;
-    Person *-- Dog
+    If --> Then
+    Then --> Else
 ```
 ````
 
-The generated graphs can be be panned by dragging them and zoomed by using the mousewheel. On mobile devices you can use finger gestures.
+{{% /tab %}}
+{{% tab name="shortcode" %}}
 
-## Examples
+````go
-
+{{</* mermaid */>}}
-### Flowchart
-
-{{< mermaid align="left" >}}
-%%{init:{"theme":"forest"}}%%
 graph LR;
-    A[Hard edge] -->|Link text| B(Round edge)
+    If --> Then
-    B --> C{<strong>Decision</strong>}
+    Then --> Else
-    C -->|One| D[Result one]
-    C -->|Two| E[Result two]
-{{< /mermaid >}}
-
-{{% expand "Show markup" "true" %}}
-````go
-{{</* mermaid align="left" */>}}
-%%{init:{"theme":"forest"}}%%
-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 */>}}
 ````
-{{% /expand %}}
 
-### Sequence
+{{% /tab %}}
+{{< /tabs >}}
 
-{{< mermaid >}}
+### Parameter
-sequenceDiagram
-    participant Alice
-    participant Bob
-    Alice->>John: Hello John, how are you?
-    loop Healthcheck
-        John->John: Fight against hypochondria
-    end
-    Note right of John: Rational thoughts <br/>prevail...
-    John-->Alice: Great!
-    John->Bob: How about you?
-    Bob-->John: Jolly good!
-{{< /mermaid >}}
 
-{{% expand "Show markup" "true" %}}
+Parameter are only supported when using shortcode syntax. Defaults are used when using codefence syntax.
-````go
-{{</* mermaid */>}}
-sequenceDiagram
-    participant Alice
-    participant Bob
-    Alice->>John: Hello John, how are you?
-    loop Healthcheck
-        John->John: Fight against hypochondria
-    end
-    Note right of John: Rational thoughts <br/>prevail...
-    John-->Alice: Great!
-    John->Bob: How about you?
-    Bob-->John: Jolly good!
-{{</* /mermaid */>}}
-````
-{{% /expand %}}
 
-### GANTT
+| Name                  | Default          | Notes       |
-
+|:----------------------|:-----------------|:------------|
-{{< mermaid >}}
+| **align**             | `center`         | Allowed values are `left`, `center` or `right`. |
-gantt
+| _**&lt;content&gt;**_ | _&lt;empty&gt;_  | Your mermaid graph. |
-        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 >}}
-
-{{% expand "Show markup" "true" %}}
-````go
-{{</* 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 */>}}
-````
-{{% /expand %}}
-
-### Class
-
-{{< mermaid >}}
-classDiagram
-  Class01 <|-- AveryLongClass : Cool
-  Class03 *-- Class04
-  Class05 o-- Class06
-  Class07 .. Class08
-  Class09 --> C2 : Where am i?
-  Class09 --* C3
-  Class09 --|> Class07
-  Class07 : equals()
-  Class07 : Object[] elementData
-  Class01 : size()
-  Class01 : int chimp
-  Class01 : int gorilla
-  Class08 <--> C2: Cool label
-{{< /mermaid >}}
-
-{{% expand "Show markup" "true" %}}
-````go
-{{</* mermaid */>}}
-classDiagram
-    Class01 <|-- AveryLongClass : Cool
-    Class03 *-- Class04
-    Class05 o-- Class06
-    Class07 .. Class08
-    Class09 --> C2 : Where am i?
-    Class09 --* C3
-    Class09 --|> Class07
-    Class07 : equals()
-    Class07 : Object[] elementData
-    Class01 : size()
-    Class01 : int chimp
-    Class01 : int gorilla
-    Class08 <--> C2: Cool label
-{{</* /mermaid */>}}
-````
-{{% /expand %}}
-
-### State
-
-````mermaid
-stateDiagram-v2
-  open: Open Door
-  closed: Closed Door
-  locked: Locked Door
-  open   --> closed: Close
-  closed --> locked: Lock
-  locked --> closed: Unlock
-  closed --> open: Open
-````
-
-{{% expand "Show markup" "true" %}}
-````go
-```mermaid
-stateDiagram-v2
-    open: Open Door
-    closed: Closed Door
-    locked: Locked Door
-    open   --> closed: Close
-    closed --> locked: Lock
-    locked --> closed: Unlock
-    closed --> open: Open
-```
-````
-{{% /expand %}}
 
 ## Configuration
 
@@ -218,10 +74,10 @@ See [Mermaid documentation](http://mermaid-js.github.io/mermaid/#/Setup?id=merma
 The `theme` setting can also be set by your used color variant. This will be the sitewide default and can - again - be overridden by your settings in `config.toml`, frontmatter or diagram directives.
 
 {{% notice note %}}
-If you want to use mermaid codefences, you have to turn off `guessSyntax` for the `markup.highlight` setting.
+To use codefence syntax you have to turn off `guessSyntax` for the `markup.highlight` setting.
 {{% /notice %}}
 
-### Example
+### Global Configuration File
 
 ````toml
 [params]
@@ -235,9 +91,170 @@ If you want to use mermaid codefences, you have to turn off `guessSyntax` for th
     guessSyntax = false
 ````
 
-or pages frontmatter
+### Page's Frontmatter
+
 ````toml
 +++
 mermaidInitialize = "{ \"theme\": \"dark\" }"
 +++
 ````
+
+## Examples
+
+### Flowchart with Non-Default Mermaid Theme
+
+````go
+{{</* mermaid align="left" */>}}
+%%{init:{"theme":"forest"}}%%
+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 */>}}
+````
+
+{{< mermaid align="left" >}}
+%%{init:{"theme":"forest"}}%%
+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 >}}
+
+### Sequence
+
+````go
+{{</* mermaid */>}}
+sequenceDiagram
+    participant Alice
+    participant Bob
+    Alice->>John: Hello John, how are you?
+    loop Healthcheck
+        John->John: Fight against hypochondria
+    end
+    Note right of John: Rational thoughts <br/>prevail...
+    John-->Alice: Great!
+    John->Bob: How about you?
+    Bob-->John: Jolly good!
+{{</* /mermaid */>}}
+````
+
+{{< mermaid >}}
+sequenceDiagram
+    participant Alice
+    participant Bob
+    Alice->>John: Hello John, how are you?
+    loop Healthcheck
+        John->John: Fight against hypochondria
+    end
+    Note right of John: Rational thoughts <br/>prevail...
+    John-->Alice: Great!
+    John->Bob: How about you?
+    Bob-->John: Jolly good!
+{{< /mermaid >}}
+
+### GANTT
+
+````go
+{{</* 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 */>}}
+````
+
+{{< 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 >}}
+
+### Class
+
+````go
+{{</* mermaid */>}}
+classDiagram
+    Class01 <|-- AveryLongClass : Cool
+    Class03 *-- Class04
+    Class05 o-- Class06
+    Class07 .. Class08
+    Class09 --> C2 : Where am i?
+    Class09 --* C3
+    Class09 --|> Class07
+    Class07 : equals()
+    Class07 : Object[] elementData
+    Class01 : size()
+    Class01 : int chimp
+    Class01 : int gorilla
+    Class08 <--> C2: Cool label
+{{</* /mermaid */>}}
+````
+
+{{< mermaid >}}
+classDiagram
+  Class01 <|-- AveryLongClass : Cool
+  Class03 *-- Class04
+  Class05 o-- Class06
+  Class07 .. Class08
+  Class09 --> C2 : Where am i?
+  Class09 --* C3
+  Class09 --|> Class07
+  Class07 : equals()
+  Class07 : Object[] elementData
+  Class01 : size()
+  Class01 : int chimp
+  Class01 : int gorilla
+  Class08 <--> C2: Cool label
+{{< /mermaid >}}
+
+### State Diagram with Codefence Syntax
+
+````go
+```mermaid
+stateDiagram-v2
+    open: Open Door
+    closed: Closed Door
+    locked: Locked Door
+    open   --> closed: Close
+    closed --> locked: Lock
+    locked --> closed: Unlock
+    closed --> open: Open
+```
+````
+
+````mermaid
+stateDiagram-v2
+  open: Open Door
+  closed: Closed Door
+  locked: Locked Door
+  open   --> closed: Close
+  closed --> locked: Lock
+  locked --> closed: Unlock
+  closed --> open: Open
+````

exampleSite/content/shortcodes/notice.en.md

@@ -36,11 +36,11 @@ It is all about the boxes.
 
 ### Parameter
 
-| Name      | Position | Optional  | Default   | Notes       |
+| Name      | Position | Default   | Notes       |
-|:----------|:---------|:----------|:----------|:------------|
+|:----------|:---------|:----------|:------------|
-| **style** | 1        | yes       | `default` | The color scheme used to highlight the box content.<br/><br/>- by severity: `info`, `note`, `tip`, `warning`<br/>- by brand color: `primary`, `secondary`<br/>- by color: `blue`, `green`, `grey`, `orange`, `red`<br/>- by special color: `default`, `transparent` |
+| **style** | 1        | `default` | The color scheme used to highlight the box content.<br/><br/>- by severity: `info`, `note`, `tip`, `warning`<br/>- by brand color: `primary`, `secondary`<br/>- by color: `blue`, `green`, `grey`, `orange`, `red`<br/>- by special color: `default`, `transparent` |
-| **title** | 2        | yes       | see notes | Arbitray text for the box title. Depending on the **style** there may be a default title. Any given value will overwrite the default.<br/><br/>- for severity styles: the matching title for the severity<br/>- for all other colors: _&lt;empty&gt;_<br/><br/>If you want no title for a severity style, you have to set this parameter to `" "` (a non empty string filled with spaces) |
+| **title** | 2        | see notes | Arbitray text for the box title. Depending on the **style** there may be a default title. Any given value will overwrite the default.<br/><br/>- for severity styles: the matching title for the severity<br/>- for all other colors: _&lt;empty&gt;_<br/><br/>If you want no title for a severity style, you have to set this parameter to `" "` (a non empty string filled with spaces) |
-| **icon**  | 3        | yes       | see notes | [Font Awesome icon name]({{%relref "cont/icons#finding-an-icon" %}}) set to the left of the title. Depending on the **style** there may be a default icon. Any given value will overwrite the default.<br/><br/>- for severity styles: a nice matching icon for the severity<br/>- for all other colors: _&lt;empty&gt;_<br/><br/>If you want no icon for a severity style, you have to set this parameter to `" "` (a non empty string filled with spaces) |
+| **icon**  | 3        | see notes | [Font Awesome icon name]({{%relref "cont/icons#finding-an-icon" %}}) set to the left of the title. Depending on the **style** there may be a default icon. Any given value will overwrite the default.<br/><br/>- for severity styles: a nice matching icon for the severity<br/>- for all other colors: _&lt;empty&gt;_<br/><br/>If you want no icon for a severity style, you have to set this parameter to `" "` (a non empty string filled with spaces) |
 
 ## Examples
 
@@ -137,7 +137,7 @@ A **warning** disclaimer
 
 {{% /expand %}}
 
-#### Warning with non-default title and icon
+#### Warning with Non-Default Title and Icon
 
 {{% notice style="warning" title="Here are dragons" icon="dragon" %}}
 A **warning** disclaimer
@@ -153,7 +153,7 @@ A **warning** disclaimer
 
 {{% /expand %}}
 
-#### Warning without a title and icon
+#### Warning without a Title and Icon
 
 {{% notice style="warning" title=" " icon=" " %}}
 A **warning** disclaimer
@@ -171,7 +171,7 @@ A **warning** disclaimer
 
 ### By Brand Colors
 
-#### Primary with title only
+#### Primary with Title only
 
 {{% notice style="primary" title="Primary" %}}
 A **primary** disclaimer
@@ -187,7 +187,7 @@ A **primary** disclaimer
 
 {{% /expand %}}
 
-#### Secondary with icon only
+#### Secondary with Icon only
 
 {{% notice style="secondary" icon="stopwatch" %}}
 A **secondary** disclaimer
@@ -205,7 +205,7 @@ A **secondary** disclaimer
 
 ### By Color
 
-#### Blue without a title and icon
+#### Blue without a Title and Icon
 
 {{% notice style="blue" %}}
 A **blue** disclaimer
@@ -221,7 +221,7 @@ A **blue** disclaimer
 
 {{% /expand %}}
 
-#### Green with title only
+#### Green with Title only
 
 {{% notice style="green" title="Green" %}}
 A **green** disclaimer
@@ -237,7 +237,7 @@ A **green** disclaimer
 
 {{% /expand %}}
 
-#### Grey with icon only
+#### Grey with Icon only
 
 {{% notice style="grey" icon="bug" %}}
 A **grey** disclaimer
@@ -253,7 +253,7 @@ A **grey** disclaimer
 
 {{% /expand %}}
 
-#### Orange with title and icon
+#### Orange with Title and Icon
 
 {{% notice style="orange" title="Orange" icon="bug" %}}
 A **orange** disclaimer
@@ -287,7 +287,7 @@ A **red** disclaimer
 
 ### By Special Color
 
-#### Default with title and icon
+#### Default with Title and Icon
 
 {{% notice default "Pay Attention to this Note!" "skull-crossbones" %}}
 Some serious information.
@@ -303,7 +303,7 @@ Some serious information.
 
 {{% /expand %}}
 
-#### Transparent with title and icon
+#### Transparent with Title and Icon
 
 {{% notice style="transparent" title="Pay Attention to this Note!" icon="skull-crossbones" %}}
 Some serious information.

exampleSite/content/shortcodes/siteparam.en.md

@@ -1,33 +1,44 @@
 +++
-description = "Get value of site params variables in your page"
+description = "Get value of site params"
 title = "Site param"
 +++
 
-The `siteparam` shortcode is used to help you print values of site params.
+The `siteparam` shortcode prints values of site params.
 
 ## Usage
 
+While the examples are using named parameter you are free to use positional aswell.
+
+{{< tabs groupId="shortcode-parameter">}}
+{{% tab name="named" %}}
+
+
 ````go
-{{%/* siteparam <string> */%}}
+{{%/* siteparam name="editURL" */%}}
 ````
 
-The first required parameter is the name of the site param to be displayed.
+{{% /tab %}}
+{{% tab name="positional" %}}
+
+````go
+{{%/* siteparam "editURL" */%}}
+````
+
+{{% /tab %}}
+{{< /tabs >}}
+
+### Parameter
+
+| Name                 | Position | Default          | Notes       |
+|:---------------------|:---------|:-----------------|:------------|
+| **name**             | 1        | _&lt;empty&gt;_  | The name of the site param to be displayed. |
 
 ## Examples
 
-For instance, in this current site, the `editURL` variable is used in `config.toml`
+### `editURL` from `config.toml`
-
-```toml
-[params]
-  editURL = "https://github.com/McShelby/hugo-theme-relearn/edit/main/exampleSite/content/"
-```
-
-Use the `siteparam` shortcode to display its value.
 
 ```go
-`editURL` Value : {{%/* siteparam "editURL" */%}}
+`editURL` value: {{%/* siteparam name="editURL" */%}}
 ```
 
-is displayed as
+`editURL` value: {{% siteparam name="editURL" %}}
-
-`editURL` Value : {{% siteparam "editURL" %}}

exampleSite/content/shortcodes/swagger/_index.en.md

@@ -1,14 +1,27 @@
 ---
-description: "Adds UI for your Swagger / OpenAPI Specifications"
+description: "UI for your Swagger / OpenAPI Specifications"
 title: "Swagger"
 ---
 
-This shortcode uses the [RapiDoc](https://mrin9.github.io/RapiDoc) library to display your OpenAPI Specifications.
+This shortcode uses the [RapiDoc](https://mrin9.github.io/RapiDoc) library to display your Swagger / OpenAPI Specifications.
 
 {{% notice note %}}
 This only works in modern browsers.
 {{% /notice %}}
 
+## Usage
+
+
+````go
+{{</* swagger src="https://petstore3.swagger.io/api/v3/openapi.json" */>}}
+````
+
+### Parameter
+
+| Name                 | Default          | Notes       |
+|:---------------------|:-----------------|:------------|
+| **src**              | _&lt;empty&gt;_  | The URL to the OpenAPI Specification file. This can be relative to the URL of your page if it is a leaf or branch bundle. |
+
 ## Configuration
 
 Swagger is configured with default settings. You can customize Swagger's default settings for all of your files thru a JSON object in your `config.toml` or override these settings per page thru your pages frontmatter.
@@ -17,29 +30,19 @@ The JSON object of your `config.toml` / frontmatter is forwarded into Swagger's
 
 The `theme` setting can also be set by your used color variant. This will be the sitewide default and can - again - be overridden by your settings in `config.toml` or frontmatter.
 
-### Example
+### Global Configuration File
 
 ````toml
 [params]
   swaggerInitialize = "{ \"theme\": \"dark\" }"
 ````
 
-## Usage
+## Example
 
-Just insert give the URL to your OpenAPI Specification like this:
+### Using Local File
-
-````go
-{{</* swagger src="https://petstore3.swagger.io/api/v3/openapi.json" */>}}
-````
-
-If your page is a leaf or branch bundle, you can also use relative URLs:
 
 ````go
 {{</* swagger src="petstore.json" */>}}
 ````
 
-The `src` parameter is mandatory and can be either an absolute or a relative URL.
-
-## Example
-
 {{< swagger src="petstore.json" >}}

exampleSite/content/shortcodes/tabs.en.md

@@ -1,12 +1,28 @@
 +++
-description = "Synchronize selection of content in different tabbed views"
+description = "Show content in tabbed views"
 title = "Tabbed views"
 +++
 
-Choose which content to see across the page. Very handy for providing code
+The `tabs` shortcode displays arbitrary content in unlimited number of tabs. This comes in handy eg. for providing code snippets for multiple languages or providing configuration in different formats.
-snippets for multiple languages or providing configuration in different formats.
 
-## Code example
+{{< tabs groupId="tabs-example-language" >}}
+{{% tab name="python" %}}
+
+```python
+print("Hello World!")
+```
+
+{{% /tab %}}
+{{% tab name="bash" %}}
+
+```bash
+echo "Hello World!"
+```
+
+{{% /tab %}}
+{{< /tabs >}}
+
+## Usage
 
 ````go
 {{</* tabs */>}}
@@ -15,60 +31,30 @@ snippets for multiple languages or providing configuration in different formats.
 print("Hello World!")
 ```
 {{%/* /tab */%}}
-{{%/* tab name="R" */%}}
+{{%/* tab name="bash" */%}}
-```R
+```bash
-> print("Hello World!")
-```
-{{%/* /tab */%}}
-{{%/* tab name="Bash" */%}}
-```Bash
 echo "Hello World!"
 ```
 {{%/* /tab */%}}
 {{</* /tabs */>}}
 ````
 
-Renders as:
+### Parameter
 
-{{< tabs groupId="tabs-example-language" >}}
+| Name                  | Default          | Notes       |
-{{% tab name="python" %}}
+|:----------------------|:-----------------|:------------|
-```python
+| **groupId**           | `default`        | Arbitrary name of the group the tab view belongs to.<br/><br/>Tab views with the same **groupId** sychronize their selected tab. This sychronization applies to the whole site! |
-print("Hello World!")
+| _**&lt;content&gt;**_ | _&lt;empty&gt;_  | Arbitrary number of tabs defined with the `tab` sub-shortcode. |
-```
-{{% /tab %}}
-{{% tab name="R" %}}
-```R
-> print("Hello World!")
-```
-{{% /tab %}}
-{{% tab name="Bash" %}}
-```Bash
-echo "Hello World!"
-```
-{{% /tab %}}
-{{< /tabs >}}
 
-Tab views with the same tabs that belong to the same group sychronize their selection:
+{{% notice warning %}}
+When using tab views with different content sets, make sure to use a common `groupId` for equal sets of tabs but distinct `groupId` for different sets.
 
-{{< tabs groupId="tabs-example-language" >}}
+The tab selection is restored automatically based on the `groupId` and if it cannot find a tab item because it came from the `'default'` group on a different page then all tabs will be empty at first!
-{{% tab name="python" %}}
+{{% /notice %}}
-```python
-print("Hello World!")
-```
-{{% /tab %}}
-{{% tab name="R" %}}
-```R
-> print("Hello World!")
-```
-{{% /tab %}}
-{{% tab name="Bash" %}}
-```Bash
-echo "Hello World!"
-```
-{{% /tab %}}
-{{< /tabs >}}
 
-## Config example
+## Examples
+
+### Distinct `groupId`
 
 ````go
 {{</* tabs groupId="config" */>}}
@@ -92,8 +78,6 @@ Hello = World
 {{</* /tabs */>}}
 ````
 
-Renders as:
-
 {{< tabs groupId="tabs-example-config" >}}
 {{% tab name="json" %}}
 ```json
@@ -114,10 +98,38 @@ Hello = World
 {{% /tab %}}
 {{< /tabs >}}
 
-{{% notice warning %}}
+### Non-Distinct `groupId`
-When using tab views with different content sets, make sure to use a common `groupId` for equal sets but distinct
+
-`groupId` for different sets. The `groupId` defaults to `'default'`.
+See what happens to this tab view if you select **properties** tab from the previous example.
-**Take this into account across the whole site!**
+
-The tab selection is restored automatically based on the `groupId` and if it cannot find a tab item because it came
+````go
-from the `'default'` group on a different page then all tabs will be empty at first.
+{{</* tabs groupId="config" */>}}
-{{% /notice %}}
+{{%/* tab name="json" */%}}
+```json
+{
+  "Hello": "World"
+}
+```
+{{%/* /tab */%}}
+{{%/* tab name="XML" */%}}
+```xml
+<Hello>World</Hello>
+```
+{{%/* /tab */%}}
+{{</* /tabs */>}}
+````
+
+{{< tabs groupId="tabs-example-config" >}}
+{{% tab name="json" %}}
+```json
+{
+  "Hello": "World"
+}
+```
+{{% /tab %}}
+{{% tab name="XML" %}}
+```xml
+<Hello>World</Hello>
+```
+{{% /tab %}}
+{{< /tabs >}}

layouts/shortcodes/children.html

@@ -1,8 +1,14 @@
 {{- $_hugo_config := `{ "version": 1 }` }}
-{{- $showhidden := .Get "showhidden"}}
+{{- $showhidden := .Get "showhidden" | default false }}
+{{- if eq (printf "%T" $showhidden) "string" }}
+	{{- $showhidden = (eq $showhidden "true") }}
+{{- end }}
 {{- $style := .Get "style" | default "li" }}
 {{- $depth := .Get "depth" | default 1 }}
 {{- $withDescription := .Get "description" | default false }}
+{{- if eq (printf "%T" $withDescription) "string" }}
+	{{- $withDescription = (eq $withDescription "true") }}
+{{- end }}
 {{- $sortTerm :=  .Get "sort" | lower }}
 {{- $containerstyle :=  .Get "containerstyle" | default "ul" }}
 {{- if( and (not (eq $style "li") ) (eq $containerstyle "ul" ) ) }}

layouts/shortcodes/expand.html

@@ -1,7 +1,10 @@
 {{- $_hugo_config := `{ "version": 1 }` }}
-{{- $title := .Get 0 | default (T "Expand-title") }}
+{{- $title := .Get "title" | default (.Get 0) | default (T "Expand-title") }}
+{{- $expanded := .Get "open" | default (.Get 1) | default false }}
+{{- if eq (printf "%T" $expanded) "string" }}
+	{{- $expanded = (eq $expanded "true") }}
+{{- end }}
 {{- $content := .Inner | safeHTML }}
-{{- $expanded := eq (.Get 1) "true" }}
 <div class="expand
     {{- if $expanded }} expand-expanded{{ end -}}
 ">

layouts/shortcodes/include.html

@@ -1,5 +1,8 @@
-{{- $file := .Get 0 }}
+{{- $file := .Get "file" | default (.Get 0) }}
-{{- $showFirstHeading := .Get 1 | default true }}
+{{- $showFirstHeading := .Get "showfirstheading" | default (.Get 1) | default true }}
+{{- if eq (printf "%T" $showFirstHeading) "string" }}
+	{{- $showFirstHeading = (eq $showFirstHeading "true") }}
+{{- end }}
 {{- if not $showFirstHeading }}<div class="include hide-first-heading">{{ end }}
 
 {{ $file | readFile | safeHTML }}

layouts/shortcodes/mermaid.html

@@ -1,5 +1,6 @@
 {{- $_hugo_config := `{ "version": 1 }` }}
-<div class="mermaid" align="{{ if .Get "align" }}{{ .Get "align" }}{{ else }}center{{ end }}">
+{{- $align := .Get "align" | default "center" }}
+<div class="mermaid" align="{{ $align }}">
   {{- safeHTML .Inner -}}
 </div>
 {{- .Page.Store.Set "htmlHasMermaid" true }}

layouts/shortcodes/siteparam.html

@@ -1,4 +1,4 @@
-{{- $paramName := (.Get 0) -}}
+{{- $paramName := .Get "name" | default (.Get 0) -}}
 {{- $siteParams := .Site.Params -}}
 {{- with $paramName -}}
     {{- with $siteParams -}}

layouts/shortcodes/tabs.html

@@ -1,5 +1,5 @@
 {{- with .Inner }}{{/* don't do anything, just call it */}}{{ end }}
-{{- $groupId := default "default" (.Get "groupId") }}
+{{- $groupId := .Get "groupId" | default "default" }}
 <div class="tab-panel">
   <div class="tab-nav">
   {{- range $idx, $tab := .Scratch.Get "tabs" }}