docs: call shortcode from partials #277

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

@@ -14,6 +14,10 @@ This document shows you what's new in the latest release. For a detailed list of
 
 ---
 
+## 4.2.0
+
+- **New**: All shortcodes can now be also called from your partials. Examples for this are added to the documentation of each shortcode.
+
 ## 4.1.0
 
 - **New**: While fixing issues with the search functionality for non latin languages, you can now [configure to have multiple languages on a single page]({{% relref "cont/i18n/#search-with-mixed-language-support" %}}).

exampleSite/content/shortcodes/attachments.en.md

@@ -5,14 +5,32 @@ title = "Attachments"
 
 The `attachments` shortcode displays a list of files attached to a page with adjustable color, title and icon.
 
-{{% attachments /%}}
+{{% attachments sort="asc" /%}}
 
 ## 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 name="shortcode" %}}
+
 ````go
-{{%/* attachments /*/%}}
+{{%/* attachments sort="asc" /*/%}}
 ````
 
+{{% /tab %}}
+{{% tab name="partial" %}}
+
+````go
+{{ partial "shortcodes/attachments.html" (dict
+  "context" .
+  "sort" "asc"
+)}}
+````
+
+{{% /tab %}}
+{{< /tabs >}}
+
 The shortcurt lists files found in a specific folder.
 
 Currently, it supports two implementations for pages

exampleSite/content/shortcodes/button.en.md

@@ -10,11 +10,37 @@ The `button` shortcode displays a clickable button with adjustable color, title
 
 ## 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 name="shortcode" %}}
+
 ````go
 {{%/* button href="https://gohugo.io/" %}}Get Hugo{{% /button */%}}
 {{%/* button href="https://gohugo.io/" style="warning" icon="dragon" %}}Get Hugo{{% /button */%}}
 ````
 
+{{% /tab %}}
+{{% tab name="partial" %}}
+
+````go
+{{ partial "shortcodes/button.html" (dict
+    "context" .
+    "href" "https://gohugo.io/"
+    "content" "Get Hugo"
+)}}
+{{ partial "shortcodes/button.html" (dict
+  "context" .
+  "href" "https://gohugo.io/"
+  "style" "warning"
+  "icon" "dragon"
+  "content" "Get Hugo"
+)}}
+````
+
+{{% /tab %}}
+{{< /tabs >}}
+
 Once the button is clicked, it opens another browser tab for the given URL.
 
 ### Parameter

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

@@ -6,12 +6,31 @@ title = "Children"
 
 The `children` shortcode lists the child pages of a page and its descendants .
 
+{{% children sort="weight" %}}
 ## 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 name="shortcode" %}}
+
 ````go
-{{%/* children */%}}
+{{%/* children sort="weight" */%}}
 ````
 
+{{% /tab %}}
+{{% tab name="partial" %}}
+
+````go
+{{ partial "shortcodes/children.html" (dict
+  "context" .
+  "sort" "weight"
+)}}
+````
+
+{{% /tab %}}
+{{< /tabs >}}
+
 ### Parameter
 
 | Name               | Default           | Notes       |

exampleSite/content/shortcodes/expand.en.md

@@ -9,22 +9,33 @@ The `expand` shortcode displays an expandable/collapsible section of text.
 
 ## Usage
 
-While the examples are using named parameter you are free to use positional aswell.
+While the examples are using shortcodes with named parameter you are free to use positional aswell or also call this shortcode from your own partials.
 
 {{< tabs groupId="shortcode-parameter">}}
-{{% tab name="named" %}}
+{{% tab name="shortcode" %}}
 
 ````go
 {{%/* expand title="Expand me..." */%}}Thank you!{{%/* /expand */%}}
 ````
 
 {{% /tab %}}
-{{% tab name="positional" %}}
+{{% tab name="shortcode (positional)" %}}
 
 ````go
 {{%/* expand "Expand me..." */%}}Thank you!{{%/* /expand */%}}
 ````
 
+{{% /tab %}}
+{{% tab name="partial" %}}
+
+````go
+{{ partial "shortcodes/expand.html" (dict
+  "context" .
+  "title" "Expand me..."
+  "content" "Thank you!"
+)}}
+````
+
 {{% /tab %}}
 {{< /tabs >}}
 

exampleSite/content/shortcodes/include.en.md

@@ -7,10 +7,10 @@ The `include` shortcode includes other files from your project inside of the cur
 
 ## Usage
 
-While the examples are using named parameter you are free to use positional aswell.
+While the examples are using shortcodes with named parameter you are free to use positional aswell or also call this shortcode from your own partials.
 
 {{< tabs groupId="shortcode-parameter">}}
-{{% tab name="named" %}}
+{{% tab name="shortcode" %}}
 
 
 ````go
@@ -18,12 +18,22 @@ While the examples are using named parameter you are free to use positional aswe
 ````
 
 {{% /tab %}}
-{{% tab name="positional" %}}
+{{% tab name="shortcode (positional)" %}}
 
 ````go
 {{%/* include "shortcodes/INCLUDE_ME.md" */%}}
 ````
 
+{{% /tab %}}
+{{% tab name="partial" %}}
+
+````go
+{{ partial "shortcodes/include .html" (dict
+  "context" .
+  "file" "shortcodes/INCLUDE_ME.md"
+)}}
+````
+
 {{% /tab %}}
 {{< /tabs >}}
 

exampleSite/content/shortcodes/mermaid.en.md

@@ -21,15 +21,15 @@ Due to limitations with [Mermaid](https://github.com/mermaid-js/mermaid/issues/1
 
 ## Usage
 
-The generated graphs can be be panned by dragging them and zoomed by using the mousewheel. On mobile devices you can use finger gestures.
+While the examples are using shortcodes with named parameter it is recommended to use codefences instead. This is because more and more other software supports Mermaid codefences (eg. GitHub) and so your markdown becomes more portable.
 
-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.
+You are free to also call this shortcode from your own partials.
 
 {{% notice note %}}
 To use codefence syntax you have to turn off `guessSyntax` for the `markup.highlight` setting ([see the configuration section](#configuration)).
 {{% /notice %}}
 
-{{< tabs groupId="shortcode-codefence">}}
+{{< tabs groupId="shortcode-parameter">}}
 {{% tab name="codefence" %}}
 
 ````plaintext
@@ -51,9 +51,22 @@ graph LR;
 {{</* /mermaid */>}}
 ````
 
+{{% /tab %}}
+{{% tab name="partial" %}}
+
+````go
+{{ partial "shortcodes/mermaid.html" (dict
+  "context" .
+  "content" "graph LR;\nIf --> Then\nThen --> Else"
+)}}
+
+````
+
 {{% /tab %}}
 {{< /tabs >}}
 
+The generated graphs can be be panned by dragging them and zoomed by using the mousewheel. On mobile devices you can use finger gestures.
+
 ### Parameter
 
 Parameter are only supported when using shortcode syntax. Defaults are used when using codefence syntax.

exampleSite/content/shortcodes/notice.en.md

@@ -11,10 +11,10 @@ It is all about the boxes.
 
 ## Usage
 
-While the examples are using named parameter you are free to use positional aswell.
+While the examples are using shortcodes with named parameter you are free to use positional aswell or also call this shortcode from your own partials.
 
 {{< tabs groupId="shortcode-parameter">}}
-{{% tab name="named" %}}
+{{% tab name="shortcode" %}}
 
 ````go
 {{%/* notice style="primary" title="There may be pirates" icon="skull-crossbones" */%}}
@@ -23,7 +23,7 @@ It is all about the boxes.
 ````
 
 {{% /tab %}}
-{{% tab name="positional" %}}
+{{% tab name="shortcode (positional)" %}}
 
 ````go
 {{%/* notice primary "There may be pirates" "skull-crossbones" */%}}
@@ -31,6 +31,19 @@ It is all about the boxes.
 {{%/* /notice */%}}
 ````
 
+{{% /tab %}}
+{{% tab name="partial" %}}
+
+````go
+{{ partial "shortcodes/notice.html" (dict
+  "context" .
+  "style" "primary"
+  "title" "There may be pirates"
+  "icon" "skull-crossbones"
+  "content" "It is all about the boxes."
+)}}
+````
+
 {{% /tab %}}
 {{< /tabs >}}
 

exampleSite/content/shortcodes/siteparam.en.md

@@ -7,10 +7,10 @@ The `siteparam` shortcode prints values of site params.
 
 ## Usage
 
-While the examples are using named parameter you are free to use positional aswell.
+While the examples are using shortcodes with named parameter you are free to use positional aswell or call this shortcode from your own partials.
 
 {{< tabs groupId="shortcode-parameter">}}
-{{% tab name="named" %}}
+{{% tab name="shortcode" %}}
 
 
 ````go
@@ -18,12 +18,22 @@ While the examples are using named parameter you are free to use positional aswe
 ````
 
 {{% /tab %}}
-{{% tab name="positional" %}}
+{{% tab name="shortcode (positional)" %}}
 
 ````go
 {{%/* siteparam "editURL" */%}}
 ````
 
+{{% /tab %}}
+{{% tab name="partial" %}}
+
+````go
+{{ partial "shortcodes/siteparam.html" (dict
+  "context" .
+  "name" "editURL"
+)}}
+````
+
 {{% /tab %}}
 {{< /tabs >}}
 

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

@@ -11,11 +11,28 @@ This only works in modern browsers.
 
 ## 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 name="shortcode" %}}
 
 ````go
 {{</* swagger src="https://petstore3.swagger.io/api/v3/openapi.json" */>}}
 ````
 
+{{% /tab %}}
+{{% tab name="partial" %}}
+
+````go
+{{ partial "shortcodes/swagger.html" (dict
+  "context" .
+  "src" "https://petstore3.swagger.io/api/v3/openapi.json"
+)}}
+````
+
+{{% /tab %}}
+{{< /tabs >}}
+
 ### Parameter
 
 | Name                 | Default          | Notes       |

exampleSite/content/shortcodes/tabs.en.md

@@ -24,6 +24,11 @@ echo "Hello World!"
 
 ## 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 name="shortcode" %}}
+
 ````go
 {{</* tabs */>}}
 {{%/* tab name="python" */%}}
@@ -39,6 +44,28 @@ echo "Hello World!"
 {{</* /tabs */>}}
 ````
 
+{{% /tab %}}
+{{% tab name="partial" %}}
+
+````go
+{{ partial "shortcodes/tabs.html" (dict
+  "context" .
+  "tabs" (slice
+    (dict
+      "name" "python"
+      "content" ("```python\nprint(\"Hello World!\")\n```" | markdownify)
+    )
+    (dict
+      "name" "bash"
+      "content" ("```bash\necho \"Hello World!\"\n```" | markdownify)
+    )
+  )
+)}}
+````
+
+{{% /tab %}}
+{{< /tabs >}}
+
 ### Parameter
 
 | Name                  | Default          | Notes       |