From aa4d1b77bd0010ef7fa58f65f7e943701ebc5e6d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=B6ren=20Weber?= Date: Thu, 23 Jun 2022 00:03:24 +0200 Subject: [PATCH] docs: call shortcode from partials #277 --- .../content/basics/migration/_index.en.md | 4 +++ .../content/shortcodes/attachments.en.md | 22 +++++++++++++-- exampleSite/content/shortcodes/button.en.md | 26 ++++++++++++++++++ .../content/shortcodes/children/_index.en.md | 21 ++++++++++++++- exampleSite/content/shortcodes/expand.en.md | 17 +++++++++--- exampleSite/content/shortcodes/include.en.md | 16 ++++++++--- exampleSite/content/shortcodes/mermaid.en.md | 19 ++++++++++--- exampleSite/content/shortcodes/notice.en.md | 19 ++++++++++--- .../content/shortcodes/siteparam.en.md | 16 ++++++++--- .../content/shortcodes/swagger/_index.en.md | 17 ++++++++++++ exampleSite/content/shortcodes/tabs.en.md | 27 +++++++++++++++++++ 11 files changed, 186 insertions(+), 18 deletions(-) diff --git a/exampleSite/content/basics/migration/_index.en.md b/exampleSite/content/basics/migration/_index.en.md index 62dc1344a7..46e1e83df6 100644 --- a/exampleSite/content/basics/migration/_index.en.md +++ b/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" %}}). diff --git a/exampleSite/content/shortcodes/attachments.en.md b/exampleSite/content/shortcodes/attachments.en.md index e5e30756d4..d175966c9b 100644 --- a/exampleSite/content/shortcodes/attachments.en.md +++ b/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 diff --git a/exampleSite/content/shortcodes/button.en.md b/exampleSite/content/shortcodes/button.en.md index 6a51cda48c..8165ce1d3a 100644 --- a/exampleSite/content/shortcodes/button.en.md +++ b/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 diff --git a/exampleSite/content/shortcodes/children/_index.en.md b/exampleSite/content/shortcodes/children/_index.en.md index a5a7eb8045..1f03190b7b 100644 --- a/exampleSite/content/shortcodes/children/_index.en.md +++ b/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 | diff --git a/exampleSite/content/shortcodes/expand.en.md b/exampleSite/content/shortcodes/expand.en.md index 9b329d5fdc..9b1d4bc744 100644 --- a/exampleSite/content/shortcodes/expand.en.md +++ b/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 >}} diff --git a/exampleSite/content/shortcodes/include.en.md b/exampleSite/content/shortcodes/include.en.md index abd00386ef..e667482c80 100644 --- a/exampleSite/content/shortcodes/include.en.md +++ b/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 >}} diff --git a/exampleSite/content/shortcodes/mermaid.en.md b/exampleSite/content/shortcodes/mermaid.en.md index 6a4dfd7863..833861a781 100644 --- a/exampleSite/content/shortcodes/mermaid.en.md +++ b/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; {{}} ```` +{{% /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. diff --git a/exampleSite/content/shortcodes/notice.en.md b/exampleSite/content/shortcodes/notice.en.md index ba9d652f74..7cccd9e228 100644 --- a/exampleSite/content/shortcodes/notice.en.md +++ b/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 >}} diff --git a/exampleSite/content/shortcodes/siteparam.en.md b/exampleSite/content/shortcodes/siteparam.en.md index 4a4f192344..8e6839e0da 100644 --- a/exampleSite/content/shortcodes/siteparam.en.md +++ b/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 >}} diff --git a/exampleSite/content/shortcodes/swagger/_index.en.md b/exampleSite/content/shortcodes/swagger/_index.en.md index a202923ef5..9a72e05cbf 100644 --- a/exampleSite/content/shortcodes/swagger/_index.en.md +++ b/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 {{}} ```` +{{% /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 | diff --git a/exampleSite/content/shortcodes/tabs.en.md b/exampleSite/content/shortcodes/tabs.en.md index 11c2f145d0..1eb68cafb8 100644 --- a/exampleSite/content/shortcodes/tabs.en.md +++ b/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 {{}} {{%/* tab name="python" */%}} @@ -39,6 +44,28 @@ echo "Hello World!" {{}} ```` +{{% /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 |