mirror of
https://github.com/McShelby/hugo-theme-relearn.git
synced 2024-11-23 07:47:54 +00:00
docs: add settings docs to shortcodes #567
This commit is contained in:
Sören Weber
parent
c9378b1e42
commit
a289a12bb5
27 changed files with 703 additions and 697 deletions
|
|
@ -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,5 +1,6 @@
|
|||
+++
|
||||
description = "Add additional shortcut links to the sidebar"
|
||||
options = ["disableShortcutsTitle"]
|
||||
title = "Shortcut Menu"
|
||||
weight = 5
|
||||
+++
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -1,4 +1,6 @@
|
|||
+++
|
||||
title = "Frontmatter"
|
||||
singulartitle = "Frontmatter"
|
||||
+++
|
||||
|
||||
Each Hugo page **has to define** a [frontmatter](https://gohugo.io/content/front-matter/).
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
+++
|
||||
title = "Tag-a-taggs"
|
||||
singulartitle = "Tagga"
|
||||
title = "Frontmatter"
|
||||
singulartitle = "Frontmatter"
|
||||
+++
|
||||
{{< piratify >}}
|
||||
|
|
@ -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`.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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`.
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
+++
|
||||
title = "Tag-a-taggs"
|
||||
singulartitle = "Tagga"
|
||||
title = "Options"
|
||||
singulartitle = "Option"
|
||||
+++
|
||||
{{< piratify >}}
|
||||
|
|
@ -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) |
|
||||
|
|
|
|||
|
|
@ -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: _<empty>_<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: _<empty>_<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) |
|
||||
|
|
|
|||
|
|
@ -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** | _<empty>_ | 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: _<empty>_<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. |
|
||||
|
|
|
|||
|
|
@ -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" %}}
|
||||
|
||||
|
|
|
|||
|
|
@ -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 |
|
||||
|
|
|
|||
|
|
@ -1,6 +1,7 @@
|
|||
+++
|
||||
description = "Render code with a syntax highlighter"
|
||||
options = ["highlightWrap"]
|
||||
frontmatter = ["highlightWrap"]
|
||||
options = ["disableHoverBlockCopyToClipBoard", "disableInlineCopyToClipBoard", "highlightWrap"]
|
||||
title = "Highlight"
|
||||
+++
|
||||
|
||||
|
|
@ -12,19 +13,11 @@ 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" }
|
||||
```py {lineNos="true" wrap="true" title="python"}
|
||||
print("Hello World!")
|
||||
```
|
||||
````
|
||||
|
|
@ -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 | _<empty>_ | 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** | | _<empty>_ | **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 | _<empty>_ | 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. |
|
||||
| _**<option>**_ | | _<empty>_ | Any of [Hugo's supported options](https://gohugo.io/functions/highlight/#options). |
|
||||
| _**<content>**_ | | _<empty>_ | 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
|
||||
|
||||
|
|
|
|||
|
|
@ -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" %}}
|
||||
|
||||
|
|
|
|||
|
|
@ -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 | _<empty>_ | 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
|
||||
|
|
|
|||
|
|
@ -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,17 +15,18 @@ $$\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
|
||||
```math { align="center" }
|
||||
$$\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)$$
|
||||
````
|
||||
|
||||
{{% /tab %}}
|
||||
{{% tab title="codefence" %}}
|
||||
|
||||
````md
|
||||
```math {align="center"}
|
||||
$$\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)$$
|
||||
```
|
||||
````
|
||||
|
|
@ -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`. |
|
||||
| _**<content>**_ | _<empty>_ | 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 >}}
|
||||
|
|
|
|||
|
|
@ -1,28 +1,25 @@
|
|||
+++
|
||||
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" }
|
||||
```mermaid {align="center" zoom="true"}
|
||||
graph LR;
|
||||
If --> Then
|
||||
Then --> Else
|
||||
|
|
@ -46,7 +43,7 @@ graph LR;
|
|||
````go
|
||||
{{ partial "shortcodes/mermaid.html" (dict
|
||||
"page" .
|
||||
"content" "graph LR;\nIf --> Then\nThen --> Else"
|
||||
"content" "graph LR;\n If --> Then\n Then --> Else"
|
||||
"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 |
|
||||
| _**<content>**_ | _<empty>_ | 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,13 +376,31 @@ 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 */>}}
|
||||
requirementDiagram
|
||||
````md
|
||||
```mermaid
|
||||
requirementDiagram
|
||||
|
||||
requirement test_req {
|
||||
id: 1
|
||||
|
|
@ -399,11 +414,11 @@ quadrantChart
|
|||
}
|
||||
|
||||
test_entity - satisfies -> test_req
|
||||
{{</* /mermaid */>}}
|
||||
```
|
||||
````
|
||||
|
||||
{{< mermaid >}}
|
||||
requirementDiagram
|
||||
````mermaid
|
||||
requirementDiagram
|
||||
|
||||
requirement test_req {
|
||||
id: 1
|
||||
|
|
@ -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,58 +622,56 @@ 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 */>}}
|
||||
%% 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
|
||||
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 >}}
|
||||
%% source,target,value
|
||||
Electricity grid,Over generation / exports,104.453
|
||||
Electricity grid,Heating and cooling - homes,113.726
|
||||
Electricity grid,H2 conversion,27.14
|
||||
````
|
||||
|
||||
### XYChart
|
||||
|
||||
````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
|
||||
columns 1
|
||||
db(("DB"))
|
||||
blockArrowId6<[" "]>(down)
|
||||
block:ID
|
||||
|
|
@ -675,12 +684,12 @@ columns 1
|
|||
ID --> D
|
||||
C --> D
|
||||
style B fill:#969,stroke:#333,stroke-width:4px
|
||||
{{</* /mermaid */>}}
|
||||
```
|
||||
````
|
||||
|
||||
{{< mermaid >}}
|
||||
````mermaid
|
||||
block-beta
|
||||
columns 1
|
||||
columns 1
|
||||
db(("DB"))
|
||||
blockArrowId6<[" "]>(down)
|
||||
block:ID
|
||||
|
|
@ -693,64 +702,64 @@ columns 1
|
|||
ID --> D
|
||||
C --> D
|
||||
style B fill:#969,stroke:#333,stroke-width:4px
|
||||
{{< /mermaid >}}
|
||||
````
|
||||
|
||||
### Packet
|
||||
|
||||
````go
|
||||
{{</* mermaid */>}}
|
||||
````md
|
||||
```mermaid
|
||||
---
|
||||
title: "TCP Packet"
|
||||
---
|
||||
packet-beta
|
||||
0-15: "Source Port"
|
||||
16-31: "Destination Port"
|
||||
32-63: "Sequence Number"
|
||||
64-95: "Acknowledgment Number"
|
||||
96-99: "Data Offset"
|
||||
100-105: "Reserved"
|
||||
106: "URG"
|
||||
107: "ACK"
|
||||
108: "PSH"
|
||||
109: "RST"
|
||||
110: "SYN"
|
||||
111: "FIN"
|
||||
112-127: "Window"
|
||||
128-143: "Checksum"
|
||||
144-159: "Urgent Pointer"
|
||||
160-191: "(Options and Padding)"
|
||||
192-255: "Data (variable length)"
|
||||
{{</* /mermaid */>}}
|
||||
0-15: "Source Port"
|
||||
16-31: "Destination Port"
|
||||
32-63: "Sequence Number"
|
||||
64-95: "Acknowledgment Number"
|
||||
96-99: "Data Offset"
|
||||
100-105: "Reserved"
|
||||
106: "URG"
|
||||
107: "ACK"
|
||||
108: "PSH"
|
||||
109: "RST"
|
||||
110: "SYN"
|
||||
111: "FIN"
|
||||
112-127: "Window"
|
||||
128-143: "Checksum"
|
||||
144-159: "Urgent Pointer"
|
||||
160-191: "(Options and Padding)"
|
||||
192-255: "Data (variable length)"
|
||||
```
|
||||
````
|
||||
|
||||
{{< mermaid >}}
|
||||
````mermaid
|
||||
---
|
||||
title: "TCP Packet"
|
||||
---
|
||||
packet-beta
|
||||
0-15: "Source Port"
|
||||
16-31: "Destination Port"
|
||||
32-63: "Sequence Number"
|
||||
64-95: "Acknowledgment Number"
|
||||
96-99: "Data Offset"
|
||||
100-105: "Reserved"
|
||||
106: "URG"
|
||||
107: "ACK"
|
||||
108: "PSH"
|
||||
109: "RST"
|
||||
110: "SYN"
|
||||
111: "FIN"
|
||||
112-127: "Window"
|
||||
128-143: "Checksum"
|
||||
144-159: "Urgent Pointer"
|
||||
160-191: "(Options and Padding)"
|
||||
192-255: "Data (variable length)"
|
||||
{{< /mermaid >}}
|
||||
0-15: "Source Port"
|
||||
16-31: "Destination Port"
|
||||
32-63: "Sequence Number"
|
||||
64-95: "Acknowledgment Number"
|
||||
96-99: "Data Offset"
|
||||
100-105: "Reserved"
|
||||
106: "URG"
|
||||
107: "ACK"
|
||||
108: "PSH"
|
||||
109: "RST"
|
||||
110: "SYN"
|
||||
111: "FIN"
|
||||
112-127: "Window"
|
||||
128-143: "Checksum"
|
||||
144-159: "Urgent Pointer"
|
||||
160-191: "(Options and Padding)"
|
||||
192-255: "Data (variable length)"
|
||||
````
|
||||
|
||||
### 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 >}}
|
||||
````
|
||||
|
|
|
|||
|
|
@ -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: _<empty>_<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: _<empty>_<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: _<empty>_<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** | | _<empty>_ | Whether to draw an expander and how the content is displayed.<br><br>- _<empty>_: 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 |
|
||||
| _**<content>**_ | | _<empty>_ | 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]
|
||||
|
|
|
|||
|
|
@ -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** | _<empty>_ | 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,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) |
|
||||
|
|
|
|||
|
|
@ -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`:
|
||||
|
||||
|
|
|
|||
|
|
@ -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: _<empty>_<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: _<empty>_<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) |
|
||||
|
|
|
|||
|
|
@ -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 |
|
||||
|
|
|
|||
|
|
@ -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"
|
||||
) }}
|
||||
Loading…
Reference in a new issue