nishiki/hugo-theme-relearn
1
0
Fork 0
mirror of https://github.com/McShelby/hugo-theme-relearn.git synced 2024-11-26 17:23:05 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs: add settings docs to shortcodes #567

Browse source
This commit is contained in:
Sören Weber 2024-10-05 01:49:00 +02:00
parent c9378b1e42
commit a289a12bb5
No known key found for this signature in database
GPG key ID: BEC6D55545451B6D
27 changed files with 703 additions and 697 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
README.md
View file

@ -44,7 +44,7 @@ The Relearn theme is an enhanced fork of the popular [Learn theme](https://githu
- **Enhanced Markdown Features**
- [GitHub Flavored Markdown (GFM) support](https://mcshelby.github.io/hugo-theme-relearn/content/markdown)
- [Support for Obsidian styled alerts](https://mcshelby.github.io/hugo-theme-relearn/content/markdown#obsidian-styled-alerts)
- [Support for Obsidian callouts](https://mcshelby.github.io/hugo-theme-relearn/content/markdown#obsidian-callouts)
- [Advanced image manipulation like lightbox, sizing, shadows, borders, and alignment](https://mcshelby.github.io/hugo-theme-relearn/content/imageeffects)
- **Rich Shortcode Library**

1
exampleSite/content/configuration/sidebar/shortcutmenu/_index.en.md
View file

@ -1,5 +1,6 @@
+++
description = "Add additional shortcut links to the sidebar"
options = ["disableShortcutsTitle"]
title = "Shortcut Menu"
weight = 5
+++

4
exampleSite/content/content/markdown.en.md
View file

@ -187,9 +187,9 @@ If you are in need of more advanced options to style your alerts, use the [notic
> Urgent info that needs immediate user attention to avoid problems.
{{% /notice %}}
### Obsidian Styled Alerts
### Obsidian Callouts
{{% badge color="#7c3aed" icon="fa-fw far fa-gem" %}}Obsidian{{% /badge %}} Since Hugo {{% badge color="fuchsia" icon="fa-fw fab fa-hackerrank" %}}0.134.0{{% /badge %}} [Obsidian styled alerts](https://help.obsidian.md/Editing+and+formatting/Callouts#Change+the+title) are also supported. Which enables configurable title text and expand/collapse.
{{% badge color="#7c3aed" icon="fa-fw far fa-gem" %}}Obsidian{{% /badge %}} Since Hugo {{% badge color="fuchsia" icon="fa-fw fab fa-hackerrank" %}}0.134.0{{% /badge %}} [Obsidian callouts](https://help.obsidian.md/Editing+and+formatting/Callouts#Change+the+title) are also supported. Which enables configurable title text and expand/collapse.
````md
> [!tip] Callouts can have custom titles

2
exampleSite/content/frontmatter/_index.en.md
View file

@ -1,4 +1,6 @@
+++
title = "Frontmatter"
singulartitle = "Frontmatter"
+++
Each Hugo page **has to define** a [frontmatter](https://gohugo.io/content/front-matter/).

4
exampleSite/content/frontmatter/_index.pir.md
View file

@ -1,5 +1,5 @@
+++
title = "Tag-a-taggs"
singulartitle = "Tagga"
title = "Frontmatter"
singulartitle = "Frontmatter"
+++
{{< piratify >}}

2
exampleSite/content/introduction/releasenotes/1/1.en.md
View file

@ -14,4 +14,4 @@ weight = -1
### New
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} [`Mermaid`](shortcodes/mermaid#configuration) config options can be set in `hugo.toml`.
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} [`Mermaid`](shortcodes/mermaid#settings) config options can be set in `hugo.toml`.

2
exampleSite/content/introduction/releasenotes/6/3.en.md
View file

@ -18,6 +18,6 @@ weight = -3
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} The [`notice` shortcode](shortcodes/notice) has a new parameter `expanded` to make the content collapsible.
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} If you are running Hugo {{% badge color="fuchsia" icon="fa-fw fab fa-hackerrank" title=" " %}}0.134.0{{% /badge %}} or later, the theme now supports [Obsidian styled alerts](content/markdown#obsidian-styled-alerts).
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} If you are running Hugo {{% badge color="fuchsia" icon="fa-fw fab fa-hackerrank" title=" " %}}0.134.0{{% /badge %}} or later, the theme now supports [Obsidian callouts](content/markdown#obsidian-callouts).
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} The theme has updated its Mermaid dependency to 11.1.0. This adds support for [packet](shortcodes/mermaid#packet) and [architecture](shortcodes/mermaid#architecture) diagrams.

2
exampleSite/content/introduction/releasenotes/6/4.en.md
View file

@ -14,6 +14,6 @@ weight = -4
### New
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} It is now possible to have user-defined styles for all shortcodes that accept the `style` parameter. See the [`notice` shortcode](shortcodes/notice#configuration) for configuration.
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} It is now possible to have user-defined styles for all shortcodes that accept the `style` parameter. See the [`notice` shortcode](shortcodes/notice/#defining-own-styles) for configuration.
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} The [`resources` shortcode](shortcodes/resources) has a new parameter `expanded` to make the resource list collapsible.

2
exampleSite/content/options/_index.en.md
View file

@ -1,4 +1,6 @@
+++
title = "Options"
singulartitle = "Option"
+++
On top of [Hugo's global configuration options](https://gohugo.io/overview/configuration/), you can set further options unique to the theme in your `hugo.toml`.

4
exampleSite/content/options/_index.pir.md
View file

@ -1,5 +1,5 @@
+++
title = "Tag-a-taggs"
singulartitle = "Tagga"
title = "Options"
singulartitle = "Option"
+++
{{< piratify >}}

2
exampleSite/content/shortcodes/attachments/index.en.md
View file

@ -54,7 +54,7 @@ While the examples are using shortcodes with named parameter you are free to als
| 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#configuration). |
| **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) |

4
exampleSite/content/shortcodes/badge.en.md
View file

@ -13,8 +13,6 @@ The `badge` shortcode displays little markers in your text with adjustable color
## 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" %}}
@ -66,7 +64,7 @@ While the examples are using shortcodes with named parameter you are free to als
| 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#configuration). |
| **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) |

6
exampleSite/content/shortcodes/button.en.md
View file

@ -10,8 +10,6 @@ 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 title="shortcode" %}}
@ -41,14 +39,12 @@ While the examples are using shortcodes with named parameter you are free to als
{{% /tab %}}
{{< /tabs >}}
Once the button is clicked, it opens another browser tab for the given URL.
### 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#configuration). |
| **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. |

2
exampleSite/content/shortcodes/children/_index.en.md
View file

@ -10,8 +10,6 @@ The `children` shortcode lists the child pages of the current page and its desce
## 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" %}}

4
exampleSite/content/shortcodes/expand.en.md
View file

@ -21,8 +21,6 @@ That's some more text with a footnote.[^someid]
## Usage
While the examples are using shortcodes with named parameter you are free to use positional as well or also call this shortcode from your own partials.
{{< tabs groupid="shortcode-parameter">}}
{{% tab title="shortcode" %}}
@ -51,6 +49,8 @@ While the examples are using shortcodes with named parameter you are free to use
{{% /tab %}}
{{< /tabs >}}
The [`notice` shortcode](shortcodes/notice/) is also capable of displaying expandable/collapsible sections of text but with color options.
### Parameter
| Name | Position | Default | Notes |

63
exampleSite/content/shortcodes/highlight.en.md
View file

@ -1,6 +1,7 @@
+++
description = "Render code with a syntax highlighter"
options = ["highlightWrap"]
frontmatter = ["highlightWrap"]
options = ["disableHoverBlockCopyToClipBoard", "disableInlineCopyToClipBoard", "highlightWrap"]
title = "Highlight"
+++
@ -12,16 +13,8 @@ print("Hello World!")
## Usage
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 providing positional parameter or by simply 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 this shortcode as a partial using compatibility syntax.
While the examples are using shortcodes with named parameter it is recommended to use Markdown codefences instead. This is because more and more other software supports Markdown codefences (eg. GitHub) and so your Markdown becomes more portable.
{{< tabs groupid="shortcode-parameter">}}
{{% tab title="markdown" %}}
{{% tab title="codeodefence" %}}
````md
```py {lineNos="true" wrap="true" title="python"}
@ -76,48 +69,60 @@ print("Hello World!")
{{% /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 adopted in other Markdown parsers like GitHub and therefore is the recommend syntax for generating portable Markdown.
### 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 frontmatter. [See below](#configuration). |
| **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 frontmatter. [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. |
## Configuration
## Settings
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) in your `hugo.toml`
### Setting Default Values for Hugo's Options
Default values for extension options can be set via params settings in your `hugo.toml` or be overwritten by frontmatter for each individual page.
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} 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).
### Global Configuration File
You can configure the color style used for code blocks in your [color variants stylesheet](configuration/appearance/branding#syntax-highlighting) file.
#### Recommended Settings
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
noClasses = false
{{< /multiconfig >}}
#### Optional Settings
### Setting Wrap of Long Lines
{{< multiconfig file=hugo >}}
[params]
highlightWrap = true
{{< /multiconfig >}}
{{% 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.
### Page's Frontmatter
You can disable wrapping by setting `highlightWrap=false` or by setting the [`wrap` parameter](#parameter) individually for each code block.
{{< multiconfig fm=true >}}
highlightWrap = true
{{< /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`.
### 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.
### Setting a Specific Color Scheme
You can configure the color style used for code blocks in your [color variants stylesheet](configuration/appearance/branding#syntax-highlighting) file using the `--CODE-theme` variable. This requires further configuration as described in the above link.
## Examples

2
exampleSite/content/shortcodes/icon.en.md
View file

@ -12,8 +12,6 @@ The `icon` shortcode displays icons using the [Font Awesome](https://fontawesome
## Usage
While the examples are using shortcodes with positional parameter you are free to also call this shortcode from your own partials.
{{< tabs groupid="shortcode-parameter">}}
{{% tab title="shortcode" %}}

14
exampleSite/content/shortcodes/include/index.en.md
View file

@ -1,5 +1,7 @@
+++
description = "Displays content from other files"
frontmatter = ["include.errorlevel"]
options = ["include.errorlevel"]
title = "Include"
+++
@ -7,8 +9,6 @@ The `include` shortcode includes other pages, resources or files from your proje
## Usage
While the examples are using shortcodes with named parameter you are free to use positional as well or also call this shortcode from your own partials.
{{< tabs groupid="shortcode-parameter">}}
{{% tab title="shortcode" %}}
@ -45,6 +45,16 @@ The included files can even contain Markdown and will be taken into account when
| **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.
## Examples
### Arbitrary Content

175
exampleSite/content/shortcodes/math.en.md
View file

@ -1,10 +1,13 @@
+++
description = "Beautiful math and chemical formulae"
options = ["disableMathJax", "mathJaxInitialize"]
frontmatter = ["customMathJaxURL", "disableMathJax", "mathJaxInitialize"]
options = ["customMathJaxURL", "disableMathJax", "mathJaxInitialize"]
title = "Math"
+++
The `math` shortcode generates beautiful formatted math and chemical formulae using the [MathJax](https://mathjax.org/) library.
You can use [pure Markdown](content/markdown/#subscript-and-superscript) for writing simple math expressions.
If this is not enough, the `math` shortcode helps you generating 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)$$
@ -12,14 +15,15 @@ $$\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \
## Usage
While the examples are using shortcodes with named parameter it is recommended to use Markdown codefences instead. This is because more and more other software supports Markdown codefences (eg. GitHub) and so your markdown becomes more portable.
You are free to also call this shortcode from your own partials.
Math is also usable without enclosing it in a shortcode or Markdown codefence but [requires configuration](#passthrough-configuration) by you. In this case no parameter from the below table are available.
{{< tabs groupid="shortcode-parameter">}}
{{% tab title="markdown" %}}
{{% 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"}
@ -47,53 +51,57 @@ $$\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \
)}}
````
{{% /tab %}}
{{% 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 %}}
{{< /tabs >}}
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 adopted in other Markdown parsers like GitHub and therefore is the recommend syntax for generating portable Markdown.
### Parameter
| Name | Default | Notes |
|-----------------------|------------------|-------------|
| **align** | `center` | Allowed values are `left`, `center` or `right`. |
| **align** | `center` | The vertical alignment.<br><br>Allowed values are `left`, `center` or `right`. |
| _**&lt;content&gt;**_ | _&lt;empty&gt;_ | Your formulae. |
## Configuration
## Settings
MathJax is configured with default settings but you can customize MathJax's default settings for all of your files through a JSON object in your `hugo.toml` or override these settings per page through your pages frontmatter.
### Providing Initialization Options for the MathJax Library
The JSON object of your `hugo.toml` / frontmatter is forwarded into MathJax's configuration object.
{{% 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.
See [MathJax documentation](https://docs.mathjax.org/en/latest/options/index.html) for all allowed settings.
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.
### Global Configuration File
Keep in mind that initialization settings of your pages front matter overwrite all settings of your configuration options.
This example reflects the default configuration also used if you don't define `mathJaxInitialize`
#### Example
{{< multiconfig file=hugo >}}
[params]
mathJaxInitialize = "{ \"tex\": { \"inlineMath\": [[\"\\(\", \"\\)\"], [\"$\", \"$\"]], displayMath: [[\"\\[\", \"\\]\"], [\"$$\", \"$$\"]] }, \"options\": { \"enableMenu\": false }"
{{< /multiconfig >}}
### Page's Frontmatter
Usually you don't need to redefine the global initialization settings for a single page. But if you do, you have repeat all the values from your global configuration you want to keep for a single page as well.
Eg. If you have redefined the delimiters to something exotic like `@` symbols in your global config, but want to additionally align your math to the left for a specific page, you have to put this to your frontmatter:
{{< multiconfig fm=true >}}
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.
#### Example
{{< multiconfig file=hugo >}}
[params]
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 math.
You can force loading the MathJax library if math wasn't found by setting `disableMathJax=false`. If math was found, the option will be ignored. This comes handy in case you are using [passthrough configuration](#passthrough-configuration) or scripting for creating math.
### Passthrough Configuration
You can use your math without enclosing it in a shortcode or Markdown codefence by using a [passthrough configuration](https://gohugo.io/content-management/mathematics/#step-1) in your `hugo.toml`:
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} 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]
@ -106,82 +114,87 @@ You can use your math without enclosing it in a shortcode or Markdown codefence
block = [['\[', '\]'], ['$$', '$$']]
{{< /multiconfig >}}
In this case you have to tell the theme that your page contains math by setting this in your page's frontmatter:
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.
{{< multiconfig fm=true >}}
disableMathJax = false
{{< /multiconfig >}}
See the [example](#passthrough) on how it makes using math really easy.
[See the example](#passthrough-block-math) on how a passthrough configurations makes using math really easy.
## Examples
### Inline Math
### Passthrough Block Math
With passthrough configuration you can just drop your math without enclosing it by shortcodes or codefences but no other [parameters](#parameter) are available.
This is only available if you are using the [passthrough configuration](#passthrough-configuration).
Just don't forget to [force load](#force-loading-of-the-mathjax-library) the MathJax library by setting `disableMathJax=false` 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
Inline math is generated if you use a single `$` as a delimiter around your formulae: {{</* math */>}}$\sqrt{3}${{</* /math */>}}
$$\left|
\begin{array}{cc}
a & b \\
c & d
\end{array}\right|$$
````
Inline math is generated if you use a single `$` as a delimiter around your formulae: {{< math >}}$\sqrt{3}${{< /math >}}
$$\left|
\begin{array}{cc}
a & b \\
c & d
\end{array}\right|$$
### Blocklevel Math with Right Alignment
### 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
If you delimit your formulae by two consecutive `$$` it generates a new block.
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 */>}}
````
If you delimit your formulae by two consecutive `$$` it generates a new block.
{{< 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 >}}
### Markdown Codefence
You can also use Markdown codefences.
````md
```math
$$\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
$$\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)$$
````
### Passthrough
This works for block as well as inline math but is only available if you are using the [passthrough configuration](#passthrough-configuration).
With passthrough configuration you can just drop your math without enclosed by shortcodes or Markdown codefences but no settings from the [parameter table](#parameter) are available.
````md
$$\left|
\begin{array}{cc}
a & b \\
c & d
\end{array}\right|$$
````
$$\left|
\begin{array}{cc}
a & b \\
c & d
\end{array}\right|$$
### Chemical Formulae
The MathJax library can also be used for chemical formulae.
````md
{{</* math */>}}
$$\ce{Hg^2+ ->[I-] HgI2 ->[I-] [Hg^{II}I4]^2-}$$
{{</* /math */>}}
`````
{{< math >}}
$$\ce{Hg^2+ ->[I-] HgI2 ->[I-] [Hg^{II}I4]^2-}$$
{{< /math >}}

279
exampleSite/content/shortcodes/mermaid.en.md
View file

@ -1,25 +1,22 @@
+++
description = "Generate diagrams and flowcharts from text"
options = ["mermaidInitialize", "mermaidZoom"]
frontmatter = ["customMermaidURL", "disableMermaid", "mermaidInitialize", "mermaidZoom"]
options = ["customMermaidURL", "disableMermaid", "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.
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">}}
````mermaid {align="center" zoom="true"}
graph LR;
If --> Then
Then --> Else
{{< /mermaid >}}
````
## Usage
While the examples are using shortcodes with named parameter it is recommended to use Markdown codefences instead. This is because more and more other software supports Mermaid Markdown codefences (eg. GitHub) and so your markdown becomes more portable.
You are free to also call this shortcode from your own partials.
{{< tabs groupid="shortcode-parameter">}}
{{% tab title="markdown" %}}
{{% tab title="codefence" %}}
````md
```mermaid {align="center" zoom="true"}
@ -56,47 +53,65 @@ graph LR;
{{% /tab %}}
{{< /tabs >}}
The generated graphs can be panned by dragging them and zoomed by using the mousewheel. On mobile devices you can use finger gestures.
Codefence syntax is widely adopted in other Markdown parsers like GitHub and therefore is the recommend syntax for generating portable Markdown.
### Parameter
| Name | Default | Notes |
|-----------------------|------------------|-------------|
| **align** | `center` | 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 of the [site](#global-configuration-file) or the [pages frontmatter](#pages-frontmatter) or `false` if not set at all.<br><br>- `false`: no pan or zoom<br>- `true`: pan and zoom active |
| **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 frontmatter 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. |
## Configuration
## Settings
Mermaid is configured with default settings. You can customize Mermaid's default settings for all of your files through a JSON object in your `hugo.toml`, override these settings per page through your pages frontmatter or override these setting per diagramm through [diagram directives](https://mermaid-js.github.io/mermaid/#/directives?id=directives).
### Configuring Pan and Zoom
The JSON object of your `hugo.toml` / frontmatter is forwarded into Mermaid's `mermaid.initialize()` function.
{{% 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.
See [Mermaid documentation](https://mermaid-js.github.io/mermaid/#/Setup?id=mermaidapi-configuration-defaults) for all allowed settings.
By default this is disabled. Set `mermaidZoom=true` to enable it.
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 `hugo.toml`, frontmatter or diagram directives.
Individual settings of a graphs [`zoom` parameter](#parameter) have precedence over the page's front matter and configuration options in that order.
### Global Configuration File
### 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.
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.
### 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.
#### Example
{{< multiconfig file=hugo >}}
[params]
mermaidInitialize = "{ \"theme\": \"dark\" }"
mermaidZoom = true
customMermaidURL = "https://unpkg.com/mermaid/dist/mermaid.min.js"
{{< /multiconfig >}}
### Page's Frontmatter
### Force Loading of the Mermaid Library
{{< multiconfig fm=true >}}
mermaidInitialize = "{ \"theme\": \"dark\" }"
mermaidZoom = true
{{< /multiconfig >}}
{{% 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 a graph.
You can force loading the Mermaid library if a graph wasn't found by setting `disableMermaid=false`. If a graph was found, the option will be ignored. This comes handy in case you are using scripting for creating a graph.
### 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 in the `--MERMAID-theme` variable of your used [color variant](configuration/appearance/generator/). This allows your graphs to look pretty when the user switches a color variant.
## Examples
### Flowchart with YAML-Title
````go
{{</* mermaid */>}}
````md
```mermaid
---
title: Example Diagram
---
@ -105,10 +120,10 @@ graph LR;
B --> C{<strong>Decision</strong>}
C -->|One| D[Result one]
C -->|Two| E[Result two]
{{</* /mermaid */>}}
```
````
{{< mermaid >}}
````mermaid
---
title: Example Diagram
---
@ -117,12 +132,12 @@ graph LR;
B --> C{<strong>Decision</strong>}
C -->|One| D[Result one]
C -->|Two| E[Result two]
{{< /mermaid >}}
````
### Sequence Diagram with Configuration Directive
````go
{{</* mermaid */>}}
````md
```mermaid
%%{init:{"fontFamily":"monospace", "sequence":{"showSequenceNumbers":true}}}%%
sequenceDiagram
Alice->>John: Hello John, how are you?
@ -133,10 +148,10 @@ sequenceDiagram
John-->>Alice: Great!
John->>Bob: How about you?
Bob-->>John: Jolly good!
{{</* /mermaid */>}}
```
````
{{< mermaid >}}
````mermaid
%%{init:{"fontFamily":"monospace", "sequence":{"showSequenceNumbers":true}}}%%
sequenceDiagram
Alice->>John: Hello John, how are you?
@ -147,11 +162,11 @@ sequenceDiagram
John-->>Alice: Great!
John->>Bob: How about you?
Bob-->>John: Jolly good!
{{< /mermaid >}}
````
### Class Diagram with Markdown Codefence Syntax
### Class Diagram
````go
````md
```mermaid
classDiagram
Animal <|-- Duck
@ -201,7 +216,7 @@ classDiagram
}
````
### State Diagram Aligned to the Right
### State Diagram Aligned to the Right Using Shortcode Syntax
````go
{{</* mermaid align="right" */>}}
@ -229,8 +244,8 @@ stateDiagram-v2
### Entity Relationship Model with Non-Default Mermaid Theme
````go
{{</* mermaid */>}}
````md
```mermaid
%%{init:{"theme":"forest"}}%%
erDiagram
CUSTOMER }|..|{ DELIVERY-ADDRESS : has
@ -241,10 +256,10 @@ erDiagram
ORDER ||--|{ ORDER-ITEM : includes
PRODUCT-CATEGORY ||--|{ PRODUCT : contains
PRODUCT ||--o{ ORDER-ITEM : "ordered in"
{{</* /mermaid */>}}
```
````
{{< mermaid >}}
````mermaid
%%{init:{"theme":"forest"}}%%
erDiagram
CUSTOMER }|..|{ DELIVERY-ADDRESS : has
@ -255,12 +270,12 @@ erDiagram
ORDER ||--|{ ORDER-ITEM : includes
PRODUCT-CATEGORY ||--|{ PRODUCT : contains
PRODUCT ||--o{ ORDER-ITEM : "ordered in"
{{< /mermaid >}}
````
### User Journey
````go
{{</* mermaid */>}}
````md
```mermaid
journey
title My working day
section Go to work
@ -270,10 +285,10 @@ journey
section Go home
Go downstairs: 5: Me
Sit down: 3: Me
{{</* /mermaid */>}}
```
````
{{< mermaid >}}
````mermaid
journey
title My working day
section Go to work
@ -283,12 +298,12 @@ journey
section Go home
Go downstairs: 5: Me
Sit down: 3: Me
{{< /mermaid >}}
````
### GANTT Chart
````go
{{</* mermaid */>}}
````md
```mermaid
gantt
dateFormat YYYY-MM-DD
title Adding GANTT diagram functionality to Mermaid
@ -304,10 +319,10 @@ gantt
Future task in critical line :crit, 5d
Create tests for renderer :2d
Add to Mermaid :1d
{{</* /mermaid */>}}
```
````
{{< mermaid >}}
````mermaid
gantt
dateFormat YYYY-MM-DD
title Adding GANTT diagram functionality to Mermaid
@ -323,48 +338,30 @@ gantt
Future task in critical line :crit, 5d
Create tests for renderer :2d
Add to Mermaid :1d
{{< /mermaid >}}
````
### Pie Chart without Zoom
````go
{{</* mermaid zoom="false" */>}}
````md
```mermaid {zoom="false"}
pie title Pets adopted by volunteers
"Dogs" : 386
"Cats" : 85
"Rats" : 15
{{</* /mermaid */>}}
```
````
{{< mermaid zoom="false" >}}
````mermaid {zoom="false"}
pie title Pets adopted by volunteers
"Dogs" : 386
"Cats" : 85
"Rats" : 15
{{< /mermaid >}}
````
### Quadrant Chart
````go
{{</* mermaid */>}}
pie title Pets adopted by volunteers
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 */>}}
````
{{< mermaid >}}
````md
```mermaid
quadrantChart
title Reach and engagement of campaigns
x-axis Low Reach --> High Reach
@ -379,12 +376,30 @@ quadrantChart
Campaign D: [0.78, 0.34]
Campaign E: [0.40, 0.34]
Campaign F: [0.35, 0.78]
{{< /mermaid >}}
```
````
````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
````go
{{</* mermaid */>}}
````md
```mermaid
requirementDiagram
requirement test_req {
@ -399,10 +414,10 @@ quadrantChart
}
test_entity - satisfies -> test_req
{{</* /mermaid */>}}
```
````
{{< mermaid >}}
````mermaid
requirementDiagram
requirement test_req {
@ -417,12 +432,12 @@ quadrantChart
}
test_entity - satisfies -> test_req
{{< /mermaid >}}
````
### Git Graph
````go
{{</* mermaid */>}}
````md
```mermaid
gitGraph
commit
commit
@ -434,10 +449,10 @@ gitGraph
merge develop
commit
commit
{{</* /mermaid */>}}
```
````
{{< mermaid >}}
````mermaid
gitGraph
commit
commit
@ -449,25 +464,23 @@ gitGraph
merge develop
commit
commit
{{< /mermaid >}}
````
### C4 Diagrams
````go
{{</* mermaid */>}}
````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") {
@ -497,23 +510,21 @@ C4Context
UpdateRelStyle(SystemC, customerA, $textColor="red", $lineColor="red", $offsetX="-50", $offsetY="20")
UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")
{{</* /mermaid */>}}
```
````
{{< mermaid >}}
````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") {
@ -543,12 +554,12 @@ C4Context
UpdateRelStyle(SystemC, customerA, $textColor="red", $lineColor="red", $offsetX="-50", $offsetY="20")
UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")
{{< /mermaid >}}
````
### Mindmaps
````go
{{</* mermaid */>}}
````md
```mermaid
mindmap
root((mindmap))
Origins
@ -566,10 +577,10 @@ mindmap
Tools
Pen and paper
Mermaid
{{</* /mermaid */>}}
```
````
{{< mermaid >}}
````mermaid
mindmap
root((mindmap))
Origins
@ -587,12 +598,12 @@ mindmap
Tools
Pen and paper
Mermaid
{{< /mermaid >}}
````
### Timeline
````go
{{</* mermaid */>}}
````md
```mermaid
timeline
title History of Social Media Platform
2002 : LinkedIn
@ -600,10 +611,10 @@ timeline
: Google
2005 : Youtube
2006 : Twitter
{{</* /mermaid */>}}
```
````
{{< mermaid >}}
````mermaid
timeline
title History of Social Media Platform
2002 : LinkedIn
@ -611,56 +622,54 @@ timeline
: Google
2005 : Youtube
2006 : Twitter
{{< /mermaid >}}
````
### Sankey
````go
{{</* mermaid */>}}
````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 */>}}
```
````
{{< mermaid >}}
````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 >}}
````
### XYChart
````go
{{</* mermaid */>}}
````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 */>}}
```
````
{{< mermaid >}}
````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 >}}
````
### Block Diagram
````go
{{</* mermaid */>}}
````md
```mermaid
block-beta
columns 1
db(("DB"))
@ -675,10 +684,10 @@ columns 1
ID --> D
C --> D
style B fill:#969,stroke:#333,stroke-width:4px
{{</* /mermaid */>}}
```
````
{{< mermaid >}}
````mermaid
block-beta
columns 1
db(("DB"))
@ -693,12 +702,12 @@ columns 1
ID --> D
C --> D
style B fill:#969,stroke:#333,stroke-width:4px
{{< /mermaid >}}
````
### Packet
````go
{{</* mermaid */>}}
````md
```mermaid
---
title: "TCP Packet"
---
@ -720,10 +729,10 @@ packet-beta
144-159: "Urgent Pointer"
160-191: "(Options and Padding)"
192-255: "Data (variable length)"
{{</* /mermaid */>}}
```
````
{{< mermaid >}}
````mermaid
---
title: "TCP Packet"
---
@ -745,12 +754,12 @@ packet-beta
144-159: "Urgent Pointer"
160-191: "(Options and Padding)"
192-255: "Data (variable length)"
{{< /mermaid >}}
````
### Architecture
````go
{{</* mermaid */>}}
````md
```mermaid
architecture-beta
group api(cloud)[API]
@ -762,10 +771,10 @@ architecture-beta
db:L -- R:server
disk1:T -- B:server
disk2:T -- B:db
{{</* /mermaid */>}}
```
````
{{< mermaid >}}
````mermaid
architecture-beta
group api(cloud)[API]
@ -777,4 +786,4 @@ architecture-beta
db:L -- R:server
disk1:T -- B:server
disk2:T -- B:db
{{< /mermaid >}}
````

28
exampleSite/content/shortcodes/notice.en.md
View file

@ -12,10 +12,8 @@ It is all about the boxes.
## Usage
While the examples are using shortcodes with named parameter you are free to use positional as well, use it as [GitHub](/content/markdown#github-styled-alerts) or [Obsidian](/content/markdown#obsidian-styled-alerts) styled alerts and also call this shortcode from your own partials.
{{< tabs groupid="shortcode-parameter">}}
{{% tab title="markdown" %}}
{{% tab title="callout" %}}
````md
> [!primary] There may be pirates
@ -56,20 +54,26 @@ 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 adopted in other Markdown parsers like [GitHub styled alerts](/content/markdown#github-styled-alerts) or [Obsidian callouts](/content/markdown#obsidian-callouts) 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 |
|-----------------------|----------|-----------------|-------------|
| **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](#configuration). |
| **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 |
| **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) |
| **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. |
## Configuration
## Settings
Besides the predefined `style` values, you are able to define your own in the `hugo.toml`.
### 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]
@ -78,7 +82,7 @@ boxStyle = [
]
{{< /multiconfig >}}
The `style` parameter must match the `identifier`. The title for the style will be determined from the `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.
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.
@ -86,7 +90,7 @@ Below is a [usage example](#user-defined-style).
## Examples
### By Severity Using Markdown Syntax
### By Severity Using Callout Syntax
````md
> [!CAUTION]
@ -294,7 +298,7 @@ Just a box
Just a box
{{% /notice %}}
#### Markdown Styled Alerts
#### Various Callouts
````go
> [!caution] Callouts can have custom titles
@ -360,7 +364,7 @@ printf("Hello World!");
#### User-defined Style
Self-defined styles can be [configured](#configuration) in your `hugo.toml` and used for every shortcode, that accepts a `style` parameter.
Self-defined styles can be [configured](#defining-own-styles) in your `hugo.toml` and used for every shortcode, that accepts a `style` parameter.
````
> [!magic]

41
exampleSite/content/shortcodes/openapi/_index.en.md
View file

@ -1,15 +1,15 @@
+++
aliases = "/shortcodes/swagger"
description = "UI for your OpenAPI / Swagger specifications"
frontmatter = ["customOpenapiURL", "disableOpenapi", "openapi.errorlevel"]
options = ["customOpenapiURL", "disableOpenapi", "openapi.errorlevel"]
title = "OpenAPI"
+++
The `openapi` shortcode uses the [Swagger UI](https://github.com/swagger-api/swagger-ui) library to display your OpenAPI / Swagger specifications.
The `openapi` shortcode displays your OpenAPI / Swagger specifications using the [Swagger UI](https://github.com/swagger-api/swagger-ui) library.
## 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" %}}
@ -30,17 +30,44 @@ While the examples are using shortcodes with named parameter you are free to als
{{% /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](configuration/appearance/topbar/#print-support) 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/). |
{{% notice note %}}
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.
## Settings
Instead, open the [print preview](configuration/appearance/topbar/#print-support) in your browser and initiate printing from that page. This page is optimized for reading and expands most of the available sections.
{{% /notice %}}
### 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.
### 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.
#### Example
{{< multiconfig file=hugo >}}
[params]
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 specification.
You can force loading the Swagger UI library if a OpenAPI specification wasn't found by setting `disableOpenapi=false`. If an OpenAPI specification was found, the option will be ignored. This comes handy in case you are using scripting for creating an OpenAPI specification.
## Example

6
exampleSite/content/shortcodes/resources/index.en.md
View file

@ -6,14 +6,12 @@ title = "Resources"
src = 'MaybeTreasure.en.txt'
+++
The `resources` shortcode displays the [titles](https://gohugo.io/methods/resource/title/) of resources contained in a [page bundle](https://gohugo.io/content-management/page-bundles/).
The `resources` shortcode displays links to resources contained in a [page bundle](https://gohugo.io/content-management/page-bundles/).
{{% resources 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 title="shortcode" %}}
@ -40,7 +38,7 @@ Multilanguage features are not supported directly by the shortcode but rely on H
| 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#configuration). |
| **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) |

8
exampleSite/content/shortcodes/siteparam.en.md
View file

@ -3,12 +3,10 @@ description = "Get value of site params"
title = "SiteParam"
+++
The `siteparam` shortcode prints values of site params.
The `siteparam` shortcode prints values of params contained in your `hugo.toml`.
## Usage
While the examples are using shortcodes with named parameter you are free to use positional as well or call this shortcode from your own partials.
{{< tabs groupid="shortcode-parameter">}}
{{% tab title="shortcode" %}}
@ -44,7 +42,7 @@ While the examples are using shortcodes with named parameter you are free to use
## Examples
### `editURL` from `hugo.toml`
### `editURL`
```go
`editURL` value: {{%/* siteparam name="editURL" */%}}
@ -52,7 +50,7 @@ While the examples are using shortcodes with named parameter you are free to use
`editURL` value: {{% siteparam name="editURL" %}}
### Nested parameter with Markdown and HTML formatting
### Nested Parameter with Markdown and HTML Formatting
To use formatted parameter, add this in your `hugo.toml`:

12
exampleSite/content/shortcodes/tab.en.md
View file

@ -3,11 +3,7 @@ description = "Show content in a single tab"
title = "Tab"
+++
You can use a `tab` shortcode to display a single tab.
This is especially useful if you want to flag your code example with an explicit language.
If you want multiple tabs grouped together you can wrap your tabs into the [`tabs` shortcode](shortcodes/tabs).
You can use a `tab` shortcode to display a single tab with a title.
{{% tab title="c" %}}
@ -19,8 +15,6 @@ printf("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 title="shortcode" %}}
@ -46,11 +40,13 @@ printf("Hello World!");
{{% /tab %}}
{{< /tabs >}}
If you want multiple tabs grouped together you can wrap your tabs into the [`tabs` shortcode](shortcodes/tabs).
### 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#configuration). |
| **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) |

12
exampleSite/content/shortcodes/tabs.en.md
View file

@ -5,10 +5,6 @@ title = "Tabs"
The `tabs` shortcode displays arbitrary content in an unlimited number of tabs.
This comes in handy eg. for providing code snippets for multiple languages.
If you just want a single tab you can instead call the [`tab` shortcode](shortcodes/tab) standalone.
{{< tabs title="hello." >}}
{{% tab title="py" %}}
@ -35,10 +31,6 @@ printf("Hello World!");
## Usage
While the examples are using shortcodes with named parameter you are free to also call this shortcode from your own partials.
See the [`tab` shortcode](shortcodes/tab) for a description of the parameter for nested tabs.
{{< tabs groupid="shortcode-parameter">}}
{{% tab title="shortcode" %}}
@ -89,6 +81,10 @@ printf"Hello World!");
{{% /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 |

45
exampleSite/layouts/partials/content-footer.html
View file

@ -1,45 +0,0 @@
{{- $LastModifierDisplayName := "" }}
{{- $LastModifierEmail := "" }}
{{- $Date := "" }}
{{- with .GitInfo }}
{{- with .AuthorName }}
{{- $LastModifierDisplayName = . }}
{{- end }}
{{- with .AuthorEmail }}
{{- $LastModifierEmail = . }}
{{- end }}
{{- with .AuthorDate }}
{{- $Date = . | time.Format ":date_medium" }}
{{- end }}
{{- else }}
{{- with .Params.LastModifierDisplayName }}
{{- $LastModifierDisplayName = . }}
{{- end }}
{{- with .Params.LastModifierEmail }}
{{- $LastModifierEmail = . }}
{{- end }}
{{- with .Date }}
{{- $Date = . | time.Format ":date_medium" }}
{{- end }}
{{- end }}
{{- if $LastModifierDisplayName }}
<i class='fa-fw fas fa-user'></i> {{ with $LastModifierEmail }}<a href="mailto:{{ . }}">{{ end }}{{ $LastModifierDisplayName }}{{ with $LastModifierEmail }}</a>{{ end }}
{{- with $Date }}
<i class='fa-fw fas fa-calendar'></i> {{ . }}
{{- end }}
{{- end }}
{{- partial "term-list.html" (dict
"page" .
"taxonomy" "options"
"icon" "gears"
) }}
{{- partial "term-list.html" (dict
"page" .
"taxonomy" "frontmatters"
"icon" "fa-fw fab fa-markdown"
) }}
{{- partial "term-list.html" (dict
"page" .
"taxonomy" "categories"
"icon" "layer-group"
) }}