Chapter 3

Shortcodes

Hugo uses Markdown for its simple content format. However, there are a lot of things that Markdown doesn’t support well. You could use pure HTML to expand possibilities.

But this happens to be a bad idea. Everyone uses Markdown because it’s pure and simple to read even non-rendered. You should avoid HTML to keep it as simple as possible.

To avoid this limitations, Hugo created shortcodes. A shortcode is a simple snippet inside a page.

The Relearn theme provides multiple shortcodes on top of existing ones.

Attachments

List of files attached to a page

Badge

Marker badges to display in your text

Button

Clickable buttons

Children

List the child pages of a page

Expand

Expandable/collapsible sections of text

Highlight

Render code with a syntax highlighter

Icon

Nice icons for your page

Include

Displays content from other files

Math

Beautiful math and chemical formulae

Mermaid

Generate diagrams and flowcharts from text

Notice

Disclaimers to help you structure your page

OpenAPI

UI for your OpenAPI / Swagger specifications

SiteParam

Get value of site params

Tab

Show content in a single tab

Tabs

Show content in tabbed views

Subsections of Shortcodes

Attachments

The attachments shortcode displays a list of files attached to a page with adjustable color, title and icon.

Warning

Since Hugo 0.112.0 this only works for leaf bundles. Branch bundles and simple pages must be switched to leaf bundles or you are currently locked to a Hugo version < 0.112.0.

Usage

While the examples are using shortcodes with named parameter you are free to also call this shortcode from your own partials.

{{% attachments sort="asc" /%}}
{{ partial "shortcodes/attachments.html" (dict
  "page" .
  "sort" "asc"
)}}

Parameter

Name Default Notes
style transparent The style scheme used for the box.

- by severity: info, note, tip, warning
- by brand color: primary, secondary, accent
- by color: blue, green, grey, orange, red
- by special color: default, transparent, code
color see notes The CSS color value to be used. If not set, the chosen color depends on the style. Any given value will overwrite the default.

- for severity styles: a nice matching color for the severity
- 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.

- for severity styles: the matching title for the severity
- for all other styles: Attachments

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 set to the left of the title. Depending on the style there may be a default icon. Any given value will overwrite the default.

- for severity styles: a nice matching icon for the severity
- for all other styles: paperclip

If you want no icon, you have to set this parameter to " " (a non empty d with spaces)
sort asc Sorting the output in ascending or descending order.
pattern .* A regular expressions, used to filter the attachments by file name. For example:

- to match a file suffix of ‘jpg’, use .*\.jpg (not *.\.jpg)
- to match file names ending in jpg or png, use .*\.(jpg|png)

Setup

Single language

The shortcode lists files found in a specific folder. The name of the folder depends on your page type (either branch bundle, leaf bundle or page).

  1. If your page is a leaf bundle, attachments must be placed in a nested index.files folder, accordingly.

    • content
      • _index.md
      • page
        • _index.md
        • _index.files
          • attachment.pdf
  2. If your page is a branch bundle, attachments must be placed in a nested _index.files folder, accordingly.

    Warning This is only available for Hugo < 0.112.0

    • content
      • _index.md
      • page
        • index.md
        • index.files
          • attachment.pdf
  3. For simple pages, attachments must be placed in a folder named like your page and ending with .files.

    Warning This is only available for Hugo < 0.112.0

    • content
      • _index.md
      • page.files
        • attachment.pdf
      • page.md

Multilingual

Be aware that if you use a multilingual website, you will need to have as many folders as languages and the language code must be part of the folder name.

Eg. for a site in English and Piratish:

  • content
    • index.en.md
    • index.pir.md
    • page
      • index.en.md
      • index.pir.md
      • index.en.files
        • attachment.pdf
      • index.pir.files
        • attachment.pdf

Examples

Custom Title, List of Attachments Ending in pdf or mp4

{{% attachments title="Related **files**" pattern=".*\.(pdf|mp4)" /%}}

Info Styled Box, Descending Sort Order

{{% attachments style="info" sort="desc" /%}}

With User-Defined Color and Font Awesome Brand Icon

{{% attachments color="fuchsia" icon="fab fa-hackerrank" /%}}

Style, Color, Title and Icons

For further examples for style, color, title and icon, see the notice shortcode documentation. The parameter are working the same way for both shortcodes, besides having different defaults.

Badge

The badge shortcode displays little markers in your text with adjustable color, title and icon.

Important Version6.6.6 Captain InfoNew Awesome

Usage

While the examples are using shortcodes with named parameter you are free to also call this shortcode from your own partials.

{{% badge %}}Important{{% /badge %}}
{{% badge style="primary" title="Version" %}}6.6.6{{% /badge %}}
{{% badge style="red" icon="angle-double-up" %}}Captain{{% /badge %}}
{{% badge style="info" %}}New{{% /badge %}}
{{% badge color="fuchsia" icon="fab fa-hackerrank" %}}Awesome{{% /badge %}}
{{ partial "shortcodes/badge.html" (dict
    "page"    .
    "content" "Important"
)}}
{{ partial "shortcodes/badge.html" (dict
  "page"  .
  "style" "primary"
  "title" "Version"
  "content" "6.6.6"
)}}
{{ partial "shortcodes/badge.html" (dict
  "page"  .
  "style" "red"
  "icon"  "angle-double-up"
  "content" "Captain"
)}}
{{ partial "shortcodes/badge.html" (dict
  "page"  .
  "style" "info"
  "content" "New"
)}}
{{ partial "shortcodes/badge.html" (dict
  "page"  .
  "color" "fuchsia"
  "icon"  "fab fa-hackerrank"
  "content" "Awesome"
)}}

Parameter

Name Default Notes
style default The style scheme used for the badge.

- by severity: info, note, tip, warning
- by brand color: primary, secondary, accent
- by color: blue, green, grey, orange, red
- by special color: default, transparent, code
color see notes The CSS color value to be used. If not set, the chosen color depends on the style. Any given value will overwrite the default.

- for severity styles: a nice matching color for the severity
- 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.

- for severity styles: the matching title for the severity
- for all other styles: <empty>

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 set to the left of the title. Depending on the style there may be a default icon. Any given value will overwrite the default.

- for severity styles: a nice matching icon for the severity
- for all other styles: <empty>

If you want no icon for a severity style, you have to set this parameter to " " (a non empty string filled with spaces)
<content> <empty> Arbitrary text for the badge.

Examples

Style

By Severity

{{% badge style="info" %}}New{{% /badge %}}
{{% badge style="note" %}}Change{{% /badge %}}
{{% badge style="tip" %}}Optional{{% /badge %}}
{{% badge style="warning" %}}Breaking{{% /badge %}}

InfoNew NoteChange TipOptional WarningBreaking

By Brand Colors

{{% badge style="primary" icon="bullhorn" title="Announcement" %}}Mandatory{{% /badge %}}
{{% badge style="secondary" icon="bullhorn" title="Announcement" %}}Optional{{% /badge %}}
{{% badge style="accent" icon="bullhorn" title="Announcement" %}}Special{{% /badge %}}

AnnouncementMandatory AnnouncementOptional AnnouncementSpecial

By Color

{{% badge style="blue" icon="palette" title="Color" %}}Blue{{% /badge %}}
{{% badge style="green" icon="palette" title="Color" %}}Green{{% /badge %}}
{{% badge style="grey" icon="palette" title="Color" %}}Grey{{% /badge %}}
{{% badge style="orange" icon="palette" title="Color" %}}Orange{{% /badge %}}
{{% badge style="red" icon="palette" title="Color" %}}Red{{% /badge %}}

ColorBlue ColorGreen ColorGrey ColorOrange ColorRed

By Special Color

{{% badge style="default" icon="palette" title="Color" %}}Default{{% /badge %}}
{{% badge style="transparent" icon="palette" title="Color" %}}Transparent{{% /badge %}}

ColorDefault ColorTransparent

Variants

Without Icon and Title Text

{{% badge %}}6.6.6{{% /badge %}}
{{% badge style="info" icon=" " title=" " %}}Awesome{{% /badge %}}
{{% badge style="red" %}}Captain{{% /badge %}}

6.6.6 Awesome Captain

Without Icon

{{% badge title="Version" %}}6.6.6{{% /badge %}}
{{% badge style="info" icon=" " %}}Awesome{{% /badge %}}
{{% badge style="red" title="Rank" %}}Captain{{% /badge %}}

Version6.6.6 InfoAwesome RankCaptain

Without Title Text

{{% badge icon="star" %}}6.6.6{{% /badge %}}
{{% badge style="info" title=" " %}}Awesome{{% /badge %}}
{{% badge style="red" icon="angle-double-up" %}}Captain{{% /badge %}}

6.6.6 Awesome Captain

All Set

{{% badge icon="star" title="Version" %}}6.6.6{{% /badge %}}
{{% badge style="info" %}}Awesome{{% /badge %}}
{{% badge style="red" icon="angle-double-up" title="Rank" %}}Captain{{% /badge %}}

Version6.6.6 InfoAwesome RankCaptain

Override for Severity

{{% badge style="info" icon="rocket" title="Feature" %}}Awesome{{% /badge %}}
FeatureAwesome

Other

With User-Defined Color, Font Awesome Brand Icon and Markdown Title and Content

{{% badge color="fuchsia" icon="fab fa-hackerrank" title="**Font**" %}}**Awesome**{{% /badge %}}
FontAwesome

With Icon Content

You can combine the badge with the icon shortcode to create even more stunning visuals.

In this case you need to declare {{< badge >}} instead of {{% badge %}}. Note, that in this case it is not possible to put markdown in the content.

{{< badge style="primary" icon="angle-double-up" >}}{{% icon skull-crossbones %}}{{< /badge >}}  
{{< badge style="primary" icon="angle-double-up" >}}{{% icon skull-crossbones %}} Pirate{{< /badge >}}  
{{< badge style="primary" title="Rank" >}}{{% icon skull-crossbones %}}{{< /badge >}}  
{{< badge style="primary" title="Rank" >}}{{% icon skull-crossbones %}} Pirate{{< /badge >}}  
{{< badge style="primary" icon="angle-double-up" title="Rank" >}}{{% icon skull-crossbones %}}{{< /badge >}}  
{{< badge style="primary" icon="angle-double-up" title="Rank" >}}{{% icon skull-crossbones %}} Pirate{{< /badge >}}


Pirate
Rank
Rank Pirate
Rank
Rank Pirate

Inside of Text

Lorem ipsum dolor sit amet, graecis denique ei vel, at duo primis mandamus. {{% badge style="blue" icon="rocket" %}}Awesome{{% /badge %}} Et legere ocurreret pri, animal tacimates complectitur ad cum. Cu eum inermis inimicus efficiendi. Labore officiis his ex, soluta officiis concludaturque ei qui, vide sensibus vim ad.

Lorem ipsum dolor sit amet, graecis denique ei vel, at duo primis mandamus. Awesome Et legere ocurreret pri, animal tacimates complectitur ad cum. Cu eum inermis inimicus efficiendi. Labore officiis his ex, soluta officiis concludaturque ei qui, vide sensibus vim ad.

Button

The button shortcode displays a clickable button with adjustable color, title and icon.

Get Hugo Get Hugo

Usage

While the examples are using shortcodes with named parameter you are free to also call this shortcode from your own partials.

{{% button href="https://gohugo.io/" %}}Get Hugo{{% /button %}}
{{% button href="https://gohugo.io/" style="warning" icon="dragon" %}}Get Hugo{{% /button %}}
{{ partial "shortcodes/button.html" (dict
    "page" .
    "href" "https://gohugo.io/"
    "content" "Get Hugo"
)}}
{{ partial "shortcodes/button.html" (dict
  "page" .
  "href" "https://gohugo.io/"
  "style" "warning"
  "icon" "dragon"
  "content" "Get Hugo"
)}}

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.

- if starting with javascript: all following text will be executed in your browser
- every other string will be interpreted as URL
style transparent The style scheme used for the button.

- by severity: info, note, tip, warning
- by brand color: primary, secondary, accent
- by color: blue, green, grey, orange, red
- by special color: default, transparent, code
color see notes The CSS color value to be used. If not set, the chosen color depends on the style. Any given value will overwrite the default.

- for severity styles: a nice matching color for the severity
- for all other styles: the corresponding color
icon see notes Font Awesome icon name set to the left of the title. Depending on the style there may be a default icon. Any given value will overwrite the default.

- for severity styles: a nice matching icon for the severity
- for all other styles: <empty>

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.
target see notes The destination frame/window if href is an URL. Otherwise the parameter is not used. This behaves similar to normal links. If the parameter is not given it defaults to:

- the setting of externalLinkTarget or _blank if not set, for any address starting with http:// or https://
- no specific value for all other links
type see notes The button type if href is JavaScript. Otherwise the parameter is not used. If the parameter is not given it defaults to button
<content> see notes Arbitrary text for the button title. Depending on the style there may be a default title. Any given value will overwrite the default.

- for severity styles: the matching title for the severity
- for all other styles: <empty>

If you want no title for a severity style, you have to set this parameter to " " (a non empty string filled with spaces)

Examples

Style

By Severity

{{% button href="https://gohugo.io/" style="info" %}}Get Hugo{{% /button %}}
{{% button href="https://gohugo.io/" style="note" %}}Get Hugo{{% /button %}}
{{% button href="https://gohugo.io/" style="tip" %}}Get Hugo{{% /button %}}
{{% button href="https://gohugo.io/" style="warning" %}}Get Hugo{{% /button %}}

Get Hugo Get Hugo Get Hugo Get Hugo

By Brand Colors

{{% button href="https://gohugo.io/" style="primary" %}}Get Hugo{{% /button %}}
{{% button href="https://gohugo.io/" style="secondary" %}}Get Hugo{{% /button %}}
{{% button href="https://gohugo.io/" style="accent" %}}Get Hugo{{% /button %}}

Get Hugo Get Hugo Get Hugo

By Color

{{% button href="https://gohugo.io/" style="blue" %}}Get Hugo{{% /button %}}
{{% button href="https://gohugo.io/" style="green" %}}Get Hugo{{% /button %}}
{{% button href="https://gohugo.io/" style="grey" %}}Get Hugo{{% /button %}}
{{% button href="https://gohugo.io/" style="orange" %}}Get Hugo{{% /button %}}
{{% button href="https://gohugo.io/" style="red" %}}Get Hugo{{% /button %}}

Get Hugo Get Hugo Get Hugo Get Hugo Get Hugo

By Special Color

{{% button href="https://gohugo.io/" style="default" %}}Get Hugo{{% /button %}}
{{% button href="https://gohugo.io/" style="transparent" %}}Get Hugo{{% /button %}}

Get Hugo Get Hugo

Icon

Empty

{{% button href="https://gohugo.io/" icon=" " %}}{{% /button %}}

Only

{{% button href="https://gohugo.io/" icon="download" %}}{{% /button %}}

To the Left

{{% button href="https://gohugo.io/" icon="download" %}}Get Hugo{{% /button %}}
Get Hugo

To the Right

{{% button href="https://gohugo.io/" icon="download" iconposition="right" %}}Get Hugo{{% /button %}}
Get Hugo

Override for Severity

{{% button href="https://gohugo.io/" icon="dragon" style="warning" %}}Get Hugo{{% /button %}}
Get Hugo

Target

{{% button href="https://gohugo.io/" target="_self" %}}Get Hugo in same window{{% /button %}}
{{% button href="https://gohugo.io/" %}}Get Hugo in new Window/Frame (default){{% /button %}}

Get Hugo in same Window/Frame Get Hugo in new Window/Frame (default)

Other

With User-Defined Color, Font Awesome Brand Icon and Markdown Title

{{% button href="https://gohugo.io/" color="fuchsia" icon="fab fa-hackerrank" %}}Get **Hugo**{{% /button %}}
Get Hugo

Severity Style with All Defaults

{{% button href="https://gohugo.io/" style="tip" %}}{{% /button %}}
Tip

Button to Internal Page

{{% button href="/index.html" %}}Home{{% /button %}}
Home

Button with JavaScript Action

If your JavaScript action does not change the focus afterwards, make sure to call this.blur() in the end to unselect the button.

{{% button style="primary" icon="bullhorn" href="javascript:alert('Hello world!');this.blur();" %}}Shout it out{{% /button %}}

Button within a form Element

To use native HTML elements in your Markdown, add this in your config.toml

[markup.goldmark.renderer]
    unsafe = true
<form action="../../search.html" method="get">
  <input name="search-by-detail" class="search-by" type="search">
  {{% button type="submit" style="secondary" icon="search" %}}Search{{% /button %}}
</form>

Children

The children shortcode lists the child pages of the current page and its descendants.

Usage

While the examples are using shortcodes with named parameter you are free to also call this shortcode from your own partials.

{{% children sort="weight" %}}
{{ partial "shortcodes/children.html" (dict
  "page" .
  "sort" "weight"
)}}

Parameter

Name Default Notes
containerstyle ul Choose the style used to group all children. It could be any HTML tag name.
style li Choose the style used to display each descendant. It could be any HTML tag name.
showhidden false When true, child pages hidden from the menu will be displayed as well.
description false When true shows a short text under each page in the list. When no description or summary exists for the page, the first 70 words of the content is taken - read more info about summaries on gohugo.io.
depth 1 The depth of descendants to display. For example, if the value is 2, the shortcode will display two levels of child pages. To get all descendants, set this value to a high number eg. 999.
sort auto The sort criteria of the displayed list.

- auto defaults to ordersectionsby of the pages frontmatter
    or to ordersectionsby of the site configuration
    or to weight
- weight
- title
- linktitle
- modifieddate
- expirydate
- publishdate
- date
- length
- default adhering to Hugo’s default sort criteria

Examples

All Default

{{% children  %}}

With Description

{{% children description="true" %}}
  • page X

    This is a plain page test, and the beginning of a YAML multiline description...

  • page 1

    This is a demo child page

  • page 2

    This is a demo child page with no description. So its content is used as description.

  • page 3

    This is a demo child page

Infinite Depth and Hidden Pages

{{% children depth="999" showhidden="true" %}}

Heading Styles for Container and Elements

{{% children containerstyle="div" style="h2" depth="3" description="true" %}}

page X

This is a plain page test, and the beginning of a YAML multiline description...

page 1

This is a demo child page

page 1-1

This is a demo child page

page 1-1-2 (headless)

This is a demo child page

page 1-1-3

This is a demo child page

page 2

This is a demo child page with no description. So its content is used as description.

page 3

This is a demo child page

page 3-1

This is a plain page test nested in a parent

Divs for Group and Element Styles

{{% children containerstyle="div" style="div" depth="3" %}}

Subsections of Children

page X

This is a plain demo child page.

Subsections of page 1

Subsections of page 1-1

Subsections of page 1-1-2 (headless)

page 2

This is a demo child page with no description.

So its content is used as description.

Subsections of page 3

Expand

The expand shortcode displays an expandable/collapsible section of text.

Thank you!

That’s some text with a footnote1

That’s some more text with a footnote.2


  1. And that’s the footnote. ↩︎

  2. Anything of interest goes here.

    Blue light glows blue. ↩︎

Note

This only works in modern browsers flawlessly. While Internet Explorer 11 has issues in displaying it, the functionality still works.

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.

{{% expand title="Expand me..." %}}Thank you!{{% /expand %}}
{{% expand "Expand me..." %}}Thank you!{{% /expand %}}
{{ partial "shortcodes/expand.html" (dict
  "page"  .
  "title" "Expand me..."
  "content" "Thank you!"
)}}

Parameter

Name Position Default Notes
title 1 "Expand me..." Arbitrary text to appear next to the expand/collapse icon.
open 2 false When true the content text will be initially shown as expanded.
<content> <empty> Arbitrary text to be displayed on expand.

Examples

All Defaults

{{% expand %}}Yes, you did it!{{% /expand %}}

Yes, you did it!

Initially Expanded

{{% expand title="Expand me..." open="true" %}}No need to press you!{{% /expand %}}

No need to press you!

Arbitrary Text

{{% expand title="Show me almost **endless** possibilities" %}}
You can add standard markdown syntax:

- multiple paragraphs
- bullet point lists
- _emphasized_, **bold** and even **_bold emphasized_** text
- [links](https://example.com)
- etc.

```plaintext
...and even source code
```

> the possibilities are endless (almost - including other shortcodes may or may not work)
{{% /expand %}}

You can add standard markdown syntax:

  • multiple paragraphs
  • bullet point lists
  • emphasized, bold and even bold emphasized text
  • links
  • etc.
...and even source code

the possibilities are endless (almost - including other shortcodes may or may not work)

Highlight

The highlight shortcode renders your code with a syntax highlighter.

1print("Hello World!")

Usage

This shortcode is fully compatible with Hugo’s 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 codefences.

You are free to also call this shortcode from your own partials. In this case it resembles Hugo’s highlight function syntax if you call this shortcode as a partial using compatiblity syntax.

While the examples are using shortcodes with named parameter it is recommended to use codefences instead. This is because more and more other software supports codefences (eg. GitHub) and so your markdown becomes more portable.

```py { lineNos="true" wrap="true" title="python" }
print("Hello World!")
```
{{< highlight lineNos="true" type="py" wrap="true" title="python" >}}
print("Hello World!")
{{< /highlight >}}
{{< highlight py "lineNos=true,wrap=true,title=python" >}}
print("Hello World!")
{{< /highlight >}}
{{ partial "shortcodes/highlight.html" (dict
  "page"    .
  "content" "print(\"Hello World!\")"
  "lineNos" "true"
  "type"    "py"
  "wrap"    "true"
  "title"   "python"
)}}
{{ partial "shortcodes/highlight.html" (dict
  "page"    .
  "content" "print(\"Hello World!\")"
  "options" "lineNos=true,wrap=true,title=python"
  "type"    "py"
)}}

Parameter

Name Position Default Notes
type 1 <empty> The language of the code to highlight. Choose from one of the supported languages. Case-insensitive.
title <empty> Extension. Arbitrary title for code. This displays the code like a single tab if hl_inline=false (which is Hugos default).
wrap see notes Extension. When true the content may wrap on long lines otherwise it will be scrollable.

The default value can be set in your config.toml and overwritten via frontmatter. See below.
options 2 <empty> An optional, comma-separated list of zero or more Hugo supported options as well as extension parameter from this table.
<option> <empty> Any of Hugo’s supported options.
<content> <empty> Your code to highlight.

Configuration

Default values for Hugo’s supported options can be set via goldmark settings in your config.toml

Default values for extension options can be set via params settings in your config.toml or be overwritten by frontmatter for each individual page.

Global Configuration File

[markup]
  [markup.highlight]
    # line numbers in a table layout will shift if code is wrapping, so better
    # use inline; besides that visually both layouts have the same look and behavior
    lineNumbersInTable = false

    # if `guessSyntax = true`, there will be no unstyled code even if no language
    # was given BUT Mermaid and Math codefences will not work anymore! So this is a
    # mandatory setting for your site if you want to use Mermaid or Math codefences
    guessSyntax = false

    # the shipped variants come with their own modified chroma syntax highlightning
    # style which is imported in theme-relearn-light.css, theme-relearn-dark.css, etc.;
    # if you want to use a predefined style instead:
    # - remove `noClasses` or set `noClasses = true`
    # - set `style` to a predefined style name
    noClasses = false
    # style = "tango"

Optional Settings

[params]
  highlightWrap = true

Page’s Frontmatter

+++
highlightWrap = true
+++

Examples

Line Numbers with Starting Offset

As mentioned above, line numbers in a table layout will shift if code is wrapping, so better use inline. To make things easier for you, set lineNumbersInTable = false in your config.toml and add lineNos = true when calling the shortcode instead of the specific values table or inline.

{{< highlight lineNos="true" lineNoStart="666" type="py" >}}
# the hardest part is to start writing code; here's a kickstart; just copy and paste this; it's free; the next lines will cost you serious credits
print("Hello")
print(" ")
print("World")
print("!")
{{< /highlight >}}
666# the hardest part is to start writing code; here's a kickstart; just copy and paste this; it's free; the next lines will cost you serious credits
667print("Hello")
668print(" ")
669print("World")
670print("!")

Codefence with Title

```py { title="python" }
# a bit shorter
print("Hello World!")
```
# a bit shorter
print("Hello World!")

With Wrap

{{< highlight type="py" wrap="true" hl_lines="2" >}}
# Quicksort Python One-liner
lambda L: [] if L==[] else qsort([x for x in L[1:] if x< L[0]]) + L[0:1] + qsort([x for x in L[1:] if x>=L[0]])
# Some more stuff
{{< /highlight >}}
# Quicksort Python One-liner
lambda L: [] if L==[] else qsort([x for x in L[1:] if x< L[0]]) + L[0:1] + qsort([x for x in L[1:] if x>=L[0]])
# Some more stuff

Without Wrap

{{< highlight type="py" wrap="false" hl_lines="2" >}}
# Quicksort Python One-liner
lambda L: [] if L==[] else qsort([x for x in L[1:] if x< L[0]]) + L[0:1] + qsort([x for x in L[1:] if x>=L[0]])
# Some more stuff
{{< /highlight >}}
# Quicksort Python One-liner
lambda L: [] if L==[] else qsort([x for x in L[1:] if x< L[0]]) + L[0:1] + qsort([x for x in L[1:] if x>=L[0]])
# Some more stuff

Icon

The icon shortcode displays icons using the Font Awesome library.

Usage

While the examples are using shortcodes with positional parameter you are free to also call this shortcode from your own partials.

{{% icon icon="exclamation-triangle" %}}
{{% icon icon="angle-double-up" %}}
{{% icon icon="skull-crossbones" %}}
{{% icon exclamation-triangle %}}
{{% icon angle-double-up %}}
{{% icon skull-crossbones %}}
{{ partial "shortcodes/icon.html" (dict
    "page" .
    "icon" "exclamation-triangle"
)}}
{{ partial "shortcodes/icon.html" (dict
    "page" .
    "icon" "angle-double-up"
)}}
{{ partial "shortcodes/icon.html" (dict
    "page" .
    "icon" "skull-crossbones"
)}}

Parameter

Name Position Default Notes
icon 1 <empty> Font Awesome icon name to be displayed. It will be displayed in the text color of its according context.

Finding an icon

Browse through the available icons in the Font Awesome Gallery. Notice that the free filter is enabled, as only the free icons are available by default.

Once on the Font Awesome page for a specific icon, for example the page for the heart, copy the icon name and paste into the Markdown content.

Customising Icons

Font Awesome provides many ways to modify the icon

  • Change color (by default the icon will inherit the parent color)
  • Increase or decrease size
  • Rotate
  • Combine with other icons

Check the full documentation on web fonts with CSS for more.

Examples

Standard Usage

Built with {{% icon heart %}} by Relearn and Hugo

Built with by Relearn and Hugo

Advanced HTML Usage

While the shortcode simplifies using standard icons, the icon customization and other advanced features of the Font Awesome library require you to use HTML directly. Paste the <i> HTML into markup, and Font Awesome will load the relevant icon.

Built with <i class="fas fa-heart"></i> by Relearn and Hugo

Built with by Relearn and Hugo

To use these native HTML elements in your Markdown, add this in your config.toml:

[markup.goldmark.renderer]
    unsafe = true

Include

The include shortcode includes other files from your project inside of the current page.

Usage

While the examples are using shortcodes with named parameter you are free to use positional aswell or also call this shortcode from your own partials.

{{% include file="shortcodes/INCLUDE_ME.md" %}}
{{% include "shortcodes/INCLUDE_ME.md" %}}
{{ partial "shortcodes/include .html" (dict
  "page" .
  "file" "shortcodes/INCLUDE_ME.md"
)}}

The included files can even contain Markdown and will be taken into account when generating the table of contents.

Parameter

Name Position Default Notes
file 1 <empty> The path to the file to be included. Path resolution adheres to Hugo’s build-in readFile function
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.

Examples

Arbitrary Content

{{% include "shortcodes/INCLUDE_ME.md" %}}

You can add standard markdown syntax:

  • multiple paragraphs
  • bullet point lists
  • emphasized, bold and even bold emphasized text
  • links
  • etc.1
...and even source code

the possibilities are endless (almost - including other shortcodes may or may not work) (almost - including other shortcodes may or may not work)


  1. Et Cetera (English: /ɛtˈsɛtərə/), abbreviated to etc., etc, et cet., is a Latin expression that is used in English to mean “and other similar things”, or “and so forth” ↩︎

Math

The math shortcode generates beautiful formatted math and chemical formulae using the MathJax library.

$$\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)$$
Note

This only works in modern browsers.

Usage

While the examples are using shortcodes with named parameter it is recommended to use codefences instead. This is because more and more other software supports Math codefences (eg. GitHub) and so your markdown becomes more portable.

You are free to also call this shortcode from your own partials.

Note

To use codefence syntax you have to turn off guessSyntax for the markup.highlight setting (see the configuration section).

```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)$$
```
{{< 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)$$
{{< /math >}}
{{ partial "shortcodes/math.html" (dict
  "page"    .
  "content" "$$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)$$"
  "align"   "center"
)}}

Parameter

Name Default Notes
align center Allowed values are left, center or right.
<content> <empty> Your formuale.

Configuration

MathJax is configured with default settings. You can customize MathJax’s default settings for all of your files thru a JSON object in your config.toml or override these settings per page thru your pages frontmatter.

The JSON object of your config.toml / frontmatter is forwarded into MathJax’s configuration object.

See MathJax documentation for all allowed settings.

Note

To use codefence syntax you have to turn off guessSyntax for the markup.highlight setting.

Global Configuration File

[params]
  mathJaxInitialize = "{ \"chtml\": { \"displayAlign\": \"left\" } }"

[markup]
  [markup.highlight]
    # if `guessSyntax = true`, there will be no unstyled code even if no language
    # was given BUT Mermaid and Math codefences will not work anymore! So this is a
    # mandatory setting for your site if you want to use Math codefences
    guessSyntax = false

Page’s Frontmatter

+++
mathJaxInitialize = "{ \"chtml\": { \"displayAlign\": \"left\" } }"
+++

Examples

Inline Math

Inline math is generated if you use a single `$` as a delimiter around your formulae: {{< math >}}$\sqrt{3}${{< /math >}}

Inline math is generated if you use a single $ as a delimiter around your formulae: $\sqrt{3}$

Blocklevel Math with Right Alignment

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 >}}

If you delimit your formulae by two consecutive $$ it generates a new block.

$$\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)$$

Codefence

You can also use codefences.

```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)$$
```
$$\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)$$

Chemical Formulae

{{< math >}}
$$\ce{Hg^2+ ->[I-] HgI2 ->[I-] [Hg^{II}I4]^2-}$$
{{< /math >}}
$$\ce{Hg^2+ ->[I-] HgI2 ->[I-] [Hg^{II}I4]^2-}$$

Mermaid

The mermaid shortcode generates diagrams and flowcharts from text, in a similar manner as Markdown using the Mermaid library.

graph LR;
    If --> Then
    Then --> Else
Note

This only works in modern browsers.

Usage

While the examples are using shortcodes with named parameter it is recommended to use codefences instead. This is because more and more other software supports Mermaid codefences (eg. GitHub) and so your markdown becomes more portable.

You are free to also call this shortcode from your own partials.

Note

To use codefence syntax you have to turn off guessSyntax for the markup.highlight setting (see the configuration section).

```mermaid { align="center" zoom="true" }
graph LR;
    If --> Then
    Then --> Else
```
{{< mermaid align="center" zoom="true" >}}
graph LR;
    If --> Then
    Then --> Else
{{< /mermaid >}}
{{ partial "shortcodes/mermaid.html" (dict
  "page"    .
  "content" "graph LR;\nIf --> Then\nThen --> Else"
  "align"   "center"
  "zoom"    "true"
)}}

The generated graphs can be be panned by dragging them and zoomed by using the mousewheel. On mobile devices you can use finger gestures.

Parameter

Name Default Notes
align center Allowed values are left, center or right.
zoom see notes Whether the graph is pan- and zoomable.

If not set the value is determined by the mermaidZoom setting of the site or the pages frontmatter or false if not set at all.

- false: no pan or zoom
- true: pan and zoom active
<content> <empty> Your Mermaid graph.

Configuration

Mermaid is configured with default settings. You can customize Mermaid’s default settings for all of your files thru a JSON object in your config.toml, override these settings per page thru your pages frontmatter or override these setting per diagramm thru diagram directives.

The JSON object of your config.toml / frontmatter is forwarded into Mermaid’s mermaid.initialize() function.

See Mermaid documentation for all allowed settings.

The theme setting can also be set by your used color variant. This will be the sitewide default and can - again - be overridden by your settings in config.toml, frontmatter or diagram directives.

Note

To use codefence syntax you have to turn off guessSyntax for the markup.highlight setting.

Global Configuration File

[params]
  mermaidInitialize = "{ \"theme\": \"dark\" }"
  mermaidZoom = true

[markup]
  [markup.highlight]
    # if `guessSyntax = true`, there will be no unstyled code even if no language
    # was given BUT Mermaid and Math codefences will not work anymore! So this is a
    # mandatory setting for your site if you want to use Mermaid codefences
    guessSyntax = false

Page’s Frontmatter

+++
mermaidInitialize = "{ \"theme\": \"dark\" }"
mermaidZoom = true
+++

Examples

Flowchart with YAML-Title

{{< mermaid >}}
---
title: Example Diagram
---
graph LR;
    A[Hard edge] -->|Link text| B(Round edge)
    B --> C{<strong>Decision</strong>}
    C -->|One| D[Result one]
    C -->|Two| E[Result two]
{{< /mermaid >}}
---
title: Example Diagram
---
graph LR;
    A[Hard edge] -->|Link text| B(Round edge)
    B --> C{<strong>Decision</strong>}
    C -->|One| D[Result one]
    C -->|Two| E[Result two]

Sequence Diagram with Configuration Directive

{{< mermaid >}}
%%{init:{"fontFamily":"monospace", "sequence":{"showSequenceNumbers":true}}}%%
sequenceDiagram
    Alice->>John: Hello John, how are you?
    loop Healthcheck
        John->>John: Fight against hypochondria
    end
    Note right of John: Rational thoughts!
    John-->>Alice: Great!
    John->>Bob: How about you?
    Bob-->>John: Jolly good!
{{< /mermaid >}}
%%{init:{"fontFamily":"monospace", "sequence":{"showSequenceNumbers":true}}}%%
sequenceDiagram
    Alice->>John: Hello John, how are you?
    loop Healthcheck
        John->>John: Fight against hypochondria
    end
    Note right of John: Rational thoughts!
    John-->>Alice: Great!
    John->>Bob: How about you?
    Bob-->>John: Jolly good!

Class Diagram with Codefence Syntax

```mermaid
classDiagram
    Animal <|-- Duck
    Animal <|-- Fish
    Animal <|-- Zebra
    Animal : +int age
    Animal : +String gender
    Animal: +isMammal()
    Animal: +mate()
    class Duck{
      +String beakColor
      +swim()
      +quack()
    }
    class Fish{
      -int sizeInFeet
      -canEat()
    }
    class Zebra{
      +bool is_wild
      +run()
    }
```
classDiagram
    Animal <|-- Duck
    Animal <|-- Fish
    Animal <|-- Zebra
    Animal : +int age
    Animal : +String gender
    Animal: +isMammal()
    Animal: +mate()
    class Duck{
      +String beakColor
      +swim()
      +quack()
    }
    class Fish{
      -int sizeInFeet
      -canEat()
    }
    class Zebra{
      +bool is_wild
      +run()
    }

State Diagram Aligned to the Right

{{< mermaid align="right" >}}
stateDiagram-v2
    open: Open Door
    closed: Closed Door
    locked: Locked Door
    open   --> closed: Close
    closed --> locked: Lock
    locked --> closed: Unlock
    closed --> open: Open
{{< /mermaid >}}
stateDiagram-v2
  open: Open Door
  closed: Closed Door
  locked: Locked Door
  open   --> closed: Close
  closed --> locked: Lock
  locked --> closed: Unlock
  closed --> open: Open

Entity Relationship Model with Non-Default Mermaid Theme

{{< mermaid >}}
%%{init:{"theme":"forest"}}%%
erDiagram
    CUSTOMER }|..|{ DELIVERY-ADDRESS : has
    CUSTOMER ||--o{ ORDER : places
    CUSTOMER ||--o{ INVOICE : "liable for"
    DELIVERY-ADDRESS ||--o{ ORDER : receives
    INVOICE ||--|{ ORDER : covers
    ORDER ||--|{ ORDER-ITEM : includes
    PRODUCT-CATEGORY ||--|{ PRODUCT : contains
    PRODUCT ||--o{ ORDER-ITEM : "ordered in"
{{< /mermaid >}}
%%{init:{"theme":"forest"}}%%
erDiagram
    CUSTOMER }|..|{ DELIVERY-ADDRESS : has
    CUSTOMER ||--o{ ORDER : places
    CUSTOMER ||--o{ INVOICE : "liable for"
    DELIVERY-ADDRESS ||--o{ ORDER : receives
    INVOICE ||--|{ ORDER : covers
    ORDER ||--|{ ORDER-ITEM : includes
    PRODUCT-CATEGORY ||--|{ PRODUCT : contains
    PRODUCT ||--o{ ORDER-ITEM : "ordered in"

User Journey

{{< mermaid >}}
journey
    title My working day
    section Go to work
      Make tea: 5: Me
      Go upstairs: 3: Me
      Do work: 1: Me, Cat
    section Go home
      Go downstairs: 5: Me
      Sit down: 3: Me
{{< /mermaid >}}
journey
    title My working day
    section Go to work
      Make tea: 5: Me
      Go upstairs: 3: Me
      Do work: 1: Me, Cat
    section Go home
      Go downstairs: 5: Me
      Sit down: 3: Me

GANTT Chart

{{< mermaid >}}
gantt
        dateFormat  YYYY-MM-DD
        title Adding GANTT diagram functionality to Mermaid
        section A section
        Completed task            :done,    des1, 2014-01-06,2014-01-08
        Active task               :active,  des2, 2014-01-09, 3d
        Future task               :         des3, after des2, 5d
        Future task2              :         des4, after des3, 5d
        section Critical tasks
        Completed task in the critical line :crit, done, 2014-01-06,24h
        Implement parser and jison          :crit, done, after des1, 2d
        Create tests for parser             :crit, active, 3d
        Future task in critical line        :crit, 5d
        Create tests for renderer           :2d
        Add to Mermaid                      :1d
{{< /mermaid >}}
gantt
        dateFormat  YYYY-MM-DD
        title Adding GANTT diagram functionality to Mermaid
        section A section
        Completed task            :done,    des1, 2014-01-06,2014-01-08
        Active task               :active,  des2, 2014-01-09, 3d
        Future task               :         des3, after des2, 5d
        Future task2              :         des4, after des3, 5d
        section Critical tasks
        Completed task in the critical line :crit, done, 2014-01-06,24h
        Implement parser and jison          :crit, done, after des1, 2d
        Create tests for parser             :crit, active, 3d
        Future task in critical line        :crit, 5d
        Create tests for renderer           :2d
        Add to Mermaid                      :1d

Pie Chart without Zoom

{{< mermaid zoom="false" >}}
pie title Pets adopted by volunteers
    "Dogs" : 386
    "Cats" : 85
    "Rats" : 15
{{< /mermaid >}}
pie title Pets adopted by volunteers
    "Dogs" : 386
    "Cats" : 85
    "Rats" : 15

Quadrant Chart

{{< 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 >}}
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

{{< mermaid >}}
    requirementDiagram

    requirement test_req {
    id: 1
    text: the test text.
    risk: high
    verifymethod: test
    }

    element test_entity {
    type: simulation
    }

    test_entity - satisfies -> test_req
{{< /mermaid >}}
    requirementDiagram

    requirement test_req {
    id: 1
    text: the test text.
    risk: high
    verifymethod: test
    }

    element test_entity {
    type: simulation
    }

    test_entity - satisfies -> test_req

Git Graph

{{< mermaid >}}
gitGraph
    commit
    commit
    branch develop
    checkout develop
    commit
    commit
    checkout main
    merge develop
    commit
    commit
{{< /mermaid >}}
gitGraph
    commit
    commit
    branch develop
    checkout develop
    commit
    commit
    checkout main
    merge develop
    commit
    commit

C4 Diagrams

{{< 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") {
        System(SystemA, "Banking System A")
        System(SystemB, "Banking System B", "A system of the bank, with personal bank accounts. next line.")
        }

        System_Ext(SystemC, "E-mail system", "The internal Microsoft Exchange e-mail system.")
        SystemDb(SystemD, "Banking System D Database", "A system of the bank, with personal bank accounts.")

        Boundary(b3, "BankBoundary3", "boundary") {
        SystemQueue(SystemF, "Banking System F Queue", "A system of the bank.")
        SystemQueue_Ext(SystemG, "Banking System G Queue", "A system of the bank, with personal bank accounts.")
        }
    }
    }

    BiRel(customerA, SystemAA, "Uses")
    BiRel(SystemAA, SystemE, "Uses")
    Rel(SystemAA, SystemC, "Sends e-mails", "SMTP")
    Rel(SystemC, customerA, "Sends e-mails to")

    UpdateElementStyle(customerA, $fontColor="red", $bgColor="grey", $borderColor="red")
    UpdateRelStyle(customerA, SystemAA, $textColor="blue", $lineColor="blue", $offsetX="5")
    UpdateRelStyle(SystemAA, SystemE, $textColor="blue", $lineColor="blue", $offsetY="-10")
    UpdateRelStyle(SystemAA, SystemC, $textColor="blue", $lineColor="blue", $offsetY="-40", $offsetX="-50")
    UpdateRelStyle(SystemC, customerA, $textColor="red", $lineColor="red", $offsetX="-50", $offsetY="20")

    UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")
{{< /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") {
        System(SystemA, "Banking System A")
        System(SystemB, "Banking System B", "A system of the bank, with personal bank accounts. next line.")
        }

        System_Ext(SystemC, "E-mail system", "The internal Microsoft Exchange e-mail system.")
        SystemDb(SystemD, "Banking System D Database", "A system of the bank, with personal bank accounts.")

        Boundary(b3, "BankBoundary3", "boundary") {
        SystemQueue(SystemF, "Banking System F Queue", "A system of the bank.")
        SystemQueue_Ext(SystemG, "Banking System G Queue", "A system of the bank, with personal bank accounts.")
        }
    }
    }

    BiRel(customerA, SystemAA, "Uses")
    BiRel(SystemAA, SystemE, "Uses")
    Rel(SystemAA, SystemC, "Sends e-mails", "SMTP")
    Rel(SystemC, customerA, "Sends e-mails to")

    UpdateElementStyle(customerA, $fontColor="red", $bgColor="grey", $borderColor="red")
    UpdateRelStyle(customerA, SystemAA, $textColor="blue", $lineColor="blue", $offsetX="5")
    UpdateRelStyle(SystemAA, SystemE, $textColor="blue", $lineColor="blue", $offsetY="-10")
    UpdateRelStyle(SystemAA, SystemC, $textColor="blue", $lineColor="blue", $offsetY="-40", $offsetX="-50")
    UpdateRelStyle(SystemC, customerA, $textColor="red", $lineColor="red", $offsetX="-50", $offsetY="20")

    UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")

Mindmaps

{{< mermaid >}}
mindmap
  root((mindmap))
    Origins
      Long history
      ::icon(fa fa-book)
      Popularisation
        British popular psychology author Tony Buzan
    Research
      On effectiveness<br/>and features
      On Automatic creation
        Uses
            Creative techniques
            Strategic planning
            Argument mapping
    Tools
      Pen and paper
      Mermaid
{{< /mermaid >}}
mindmap
  root((mindmap))
    Origins
      Long history
      ::icon(fa fa-book)
      Popularisation
        British popular psychology author Tony Buzan
    Research
      On effectiveness<br/>and features
      On Automatic creation
        Uses
            Creative techniques
            Strategic planning
            Argument mapping
    Tools
      Pen and paper
      Mermaid

Timeline

{{< mermaid >}}
timeline
    title History of Social Media Platform
    2002 : LinkedIn
    2004 : Facebook
         : Google
    2005 : Youtube
    2006 : Twitter
{{< /mermaid >}}
timeline
    title History of Social Media Platform
    2002 : LinkedIn
    2004 : Facebook
         : Google
    2005 : Youtube
    2006 : Twitter

Sankey

{{< 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 >}}
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

XYChart

{{< 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 >}}
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]

Notice

The notice shortcode shows various types of disclaimers with adjustable color, title and icon to help you structure your page.

There may be pirates

It is all about the boxes.

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.

{{% notice style="primary" title="There may be pirates" icon="skull-crossbones" %}}
It is all about the boxes.
{{% /notice %}}
{{% notice primary "There may be pirates" "skull-crossbones" %}}
It is all about the boxes.
{{% /notice %}}
{{ partial "shortcodes/notice.html" (dict
  "page"  .
  "style" "primary"
  "title" "There may be pirates"
  "icon" "skull-crossbones"
  "content" "It is all about the boxes."
)}}

Parameter

Name Position Default Notes
style 1 default The style scheme used for the box.

- by severity: info, note, tip, warning
- by brand color: primary, secondary, accent
- by color: blue, green, grey, orange, red
- by special color: default, transparent, code
color see notes The CSS color value to be used. If not set, the chosen color depends on the style. Any given value will overwrite the default.

- for severity styles: a nice matching color for the severity
- for all other styles: the corresponding color
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.

- for severity styles: the matching title for the severity
- for all other styles: <empty>

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 set to the left of the title. Depending on the style there may be a default icon. Any given value will overwrite the default.

- for severity styles: a nice matching icon for the severity
- for all other styles: <empty>

If you want no icon for a severity style, you have to set this parameter to " " (a non empty string filled with spaces)
<content> <empty> Arbitrary text to be displayed in box.

Examples

By Severity

Info with markup

{{% notice style="info" %}}
An **information** disclaimer

You can add standard markdown syntax:

- multiple paragraphs
- bullet point lists
- _emphasized_, **bold** and even ***bold emphasized*** text
- [links](https://example.com)
- etc.

```plaintext
...and even source code
```

> the possibilities are endless (almost - including other shortcodes may or may not work)
{{% /notice %}}
Info

An information disclaimer

You can add standard markdown syntax:

  • multiple paragraphs
  • bullet point lists
  • emphasized, bold and even bold emphasized text
  • links
  • etc.
...and even source code

the possibilities are endless (almost - including other shortcodes may or may not work)

Note

{{% notice style="note" %}}
A **notice** disclaimer
{{% /notice %}}
Note

A notice disclaimer

Tip

{{% notice style="tip" %}}
A **tip** disclaimer
Tip

A tip disclaimer

Warning

{{% notice style="warning" %}}
A **warning** disclaimer
{{% /notice %}}
Warning

A warning disclaimer

Warning with Non-Default Title and Icon

{{% notice style="warning" title="Here are dragons" icon="dragon" %}}
A **warning** disclaimer
{{% /notice %}}
Here are dragons

A warning disclaimer

Warning without a Title and Icon

{{% notice style="warning" title=" " icon=" " %}}
A **warning** disclaimer
{{% /notice %}}

A warning disclaimer

By Brand Colors

Primary with Title only

{{% notice style="primary" title="Primary" %}}
A **primary** disclaimer
{{% /notice %}}
Primary

A primary disclaimer

Secondary with Icon only

{{% notice style="secondary" icon="stopwatch" %}}
A **secondary** disclaimer
{{% /notice %}}

A secondary disclaimer

Accent

{{% notice style="accent" %}}
An **accent** disclaimer
{{% /notice %}}

An accent disclaimer

By Color

Blue without a Title and Icon

{{% notice style="blue" %}}
A **blue** disclaimer
{{% /notice %}}

A blue disclaimer

Green with Title only

{{% notice style="green" title="Green" %}}
A **green** disclaimer
{{% /notice %}}
Green

A green disclaimer

Grey with Icon only

{{% notice style="grey" icon="bug" %}}
A **grey** disclaimer
{{% /notice %}}

A grey disclaimer

Orange with Title and Icon

{{% notice style="orange" title="Orange" icon="bug" %}}
A **orange** disclaimer
{{% /notice %}}
Orange

A orange disclaimer

Red without a Title and Icon

{{% notice style="red" %}}
A **red** disclaimer
{{% /notice %}}

A red disclaimer

By Special Color

Default with Positional Parameter

{{% notice default "Pay Attention to this Note!" "skull-crossbones" %}}
Some serious information.
{{% /notice %}}
Pay Attention to this Note!

Some serious information.

Transparent with Title and Icon

{{% notice style="transparent" title="Pay Attention to this Note!" icon="skull-crossbones" %}}
Some serious information.
{{% /notice %}}
Pay Attention to this Note!

Some serious information.

With User-Defined Color, Font Awesome Brand Icon and Markdown Title

{{% notice color="fuchsia" title="**Hugo**" icon="fab fa-hackerrank" %}}
Victor? Is it you?
{{% /notice %}}
Hugo

Victor? Is it you?

OpenAPI

The openapi shortcode uses the Swagger UI library to display your OpenAPI / Swagger specifications.

Note

This only works in modern browsers.

Usage

While the examples are using shortcodes with named parameter you are free to also call this shortcode from your own partials.

{{< openapi src="https://petstore3.openapi.io/api/v3/openapi.json" >}}
{{ partial "shortcodes/openapi.html" (dict
  "page" .
  "src"  "https://petstore3.openapi.io/api/v3/openapi.json"
)}}

Parameter

Name Default Notes
src <empty> The URL to the OpenAPI specification file. This can be relative to the URL of your page if it is a leaf or branch bundle.
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.

Instead, open the print preview in your browser and initiate printing from that page. This page is optimized for reading and expands most of the available sections.

Example

Using Local File

{{< openapi src="petstore.json" >}}

SiteParam

The siteparam shortcode prints values of site params.

Usage

While the examples are using shortcodes with named parameter you are free to use positional aswell or call this shortcode from your own partials.

{{% siteparam name="editURL" %}}
{{% siteparam "editURL" %}}
{{ partial "shortcodes/siteparam.html" (dict
  "page" .
  "name" "editURL"
)}}

Parameter

Name Position Default Notes
name 1 <empty> The name of the site param to be displayed.

Examples

editURL from config.toml

`editURL` value: {{% siteparam name="editURL" %}}

editURL value: https://github.com/McShelby/hugo-theme-relearn/edit/main/exampleSite/content/

Nested parameter with Markdown and HTML formatting

To use formatted parameter, add this in your config.toml:

[markup.goldmark.renderer]
    unsafe = true
[params]
    [params.siteparam.test]
        text = "A **nested** parameter <b>with</b> formatting"
Formatted parameter: {{% siteparam name="siteparam.test.text" %}}

Formatted parameter: A nested option <b>with</b> formatting

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.

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.

{{% tab title="c" %}}
```c
printf("Hello World!");
```
{{% /tab %}}
{{ partial "shortcodes/tab.html" (dict
  "page"  .
  "title" "c"
  "content" ("```c\nprintf(\"Hello World!\")\n```" | .RenderString)
)}}

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.

- by severity: info, note, tip, warning
- by brand color: primary, secondary, accent
- by color: blue, green, grey, orange, red
- by special color: default, transparent, code
color see notes The CSS color value to be used. If not set, the chosen color depends on the style. Any given value will overwrite the default.

- for severity styles: a nice matching color for the severity
- 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.

- for severity styles: the matching title for the severity
- for all other styles: <empty>

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 set to the left of the title. Depending on the style there may be a default icon. Any given value will overwrite the default.

- for severity styles: a nice matching icon for the severity
- for all other styles: <empty>

If you want no icon for a severity style, you have to set this parameter to " " (a non empty string filled with spaces)
<content> <empty> Arbitrary text to be displayed in the tab.

Examples

Single Code Block with Collapsed Margins

{{% tab title="Code" %}}
```python
printf("Hello World!");
```
{{% /tab %}}
printf("Hello World!");

Mixed Markdown Content

{{% tab title="_**Mixed**_" %}}
A tab can not only contain code but arbitrary text. In this case text **and** code will get a margin.
```python
printf("Hello World!");
```
{{% /tab %}}

A tab can not only contain code but arbitrary text. In this case text and code will get a margin.

printf("Hello World!");

Understanding style and color Behavior

The style parameter affects how the color parameter is applied.

{{< tabs >}}
{{% tab title="just colored style" style="blue" %}}
The `style` parameter is set to a color style.

This will set the background to a lighter version of the chosen style color as configured in your theme variant.
{{% /tab %}}
{{% tab title="just color" color="blue" %}}
Only the `color` parameter is set.

This will set the background to a lighter version of the chosen CSS color value.
{{% /tab %}}
{{% tab title="default style and color" style="default" color="blue" %}}
The `style` parameter affects how the `color` parameter is applied.

The `default` style will set the background to your `--MAIN-BG-color` as configured for your theme variant resembling the default style but with different color.
{{% /tab %}}
{{% tab title="just severity style" style="info" %}}
The `style` parameter is set to a severity style.

This will set the background to a lighter version of the chosen style color as configured in your theme variant and also affects the chosen icon.
{{% /tab %}}
{{% tab title="severity style and color" style="info" color="blue" %}}
The `style` parameter affects how the `color` parameter is applied.

This will set the background to a lighter version of the chosen CSS color value and also affects the chosen icon.
{{% /tab %}}
{{< /tabs >}}

The style parameter is set to a color style.

This will set the background to a lighter version of the chosen style color as configured in your theme variant.

Only the color parameter is set.

This will set the background to a lighter version of the chosen CSS color value.

The style parameter affects how the color parameter is applied.

The default style will set the background to your --MAIN-BG-color as configured for your theme variant resembling the default style but with different color.

The style parameter is set to a severity style.

This will set the background to a lighter version of the chosen style color as configured in your theme variant and also affects the chosen icon.

The style parameter affects how the color parameter is applied.

This will set the background to a lighter version of the chosen CSS color value and also affects the chosen icon.

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 standalone.

hello.
print("Hello World!")
echo "Hello World!"
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 for a description of the parameter for nested tabs.

{{< tabs title="hello." >}}
{{% tab title="py" %}}
```python
print("Hello World!")
```
{{% /tab %}}
{{% tab title="sh" %}}
```bash
echo "Hello World!"
```
{{% /tab %}}
{{% tab title="c" %}}
```c
printf"Hello World!");
```
{{% /tab %}}
{{< /tabs >}}
{{ partial "shortcodes/tabs.html" (dict
  "page"  .
  "title" "hello."
  "content" (slice
    (dict
      "title" "py"
      "content" ("```python\nprint(\"Hello World!\")\n```" | .RenderString)
    )
    (dict
      "title" "sh"
      "content" ("```bash\necho \"Hello World!\"\n```" | .RenderString)
    )
    (dict
      "title" "c"
      "content" ("```c\nprintf(\"Hello World!\");\n```" | .RenderString)
    )
  )
)}}

Parameter

Name Default Notes
groupid <random> Arbitrary name of the group the tab view belongs to.

Tab views with the same groupid sychronize their selected tab. The tab selection is restored automatically based on the groupid for tab view. If the selected tab can not be found in a tab group the first tab is selected instead.

This sychronization applies to the whole site!
style <empty> Sets a default value for every contained tab. Can be overridden by each tab. See the tab shortcode for possible values.
color <empty> Sets a default value for every contained tab. Can be overridden by each tab. See the tab shortcode for possible values.
title <empty> Arbitrary title written in front of the tab view.
icon <empty> Font Awesome icon name set to the left of the title.
<content> <empty> Arbitrary number of tabs defined with the tab sub-shortcode.

Examples

Behavior of the groupid

See what happens to the tab views while you select different tabs.

While pressing a tab of Group A switches all tab views of Group A in sync (if the tab is available), the tabs of Group B are left untouched.

{{< tabs groupid="a" >}}
{{% tab title="json" %}}
{{< highlight json "linenos=true" >}}
{ "Hello": "World" }
{{< /highlight >}}
{{% /tab %}}
{{% tab title="_**XML**_ stuff" %}}
```xml
<Hello>World</Hello>
```
{{% /tab %}}
{{% tab title="text" %}}
    Hello World
{{% /tab %}}
{{< /tabs >}}
{{< tabs groupid="a" >}}
{{% tab title="json" %}}
{{< highlight json "linenos=true" >}}
{ "Hello": "World" }
{{< /highlight >}}
{{% /tab %}}
{{% tab title="XML stuff" %}}
```xml
<Hello>World</Hello>
```
{{% /tab %}}
{{< /tabs >}}
{{< tabs groupid="b" >}}
{{% tab title="json" %}}
{{< highlight json "linenos=true" >}}
{ "Hello": "World" }
{{< /highlight >}}
{{% /tab %}}
{{% tab title="XML stuff" %}}
```xml
<Hello>World</Hello>
```
{{% /tab %}}
{{< /tabs >}}

Group A, Tab View 1

1{ "Hello": "World" }
<Hello>World</Hello>
Hello World

Group A, Tab View 2

1{ "Hello": "World" }
<Hello>World</Hello>

Group B

1{ "Hello": "World" }
<Hello>World</Hello>

Nested Tab Views and Color

In case you want to nest tab views, the parent tab that contains nested tab views needs to be declared with {{< tab >}} instead of {{% tab %}}. Note, that in this case it is not possible to put markdown in the parent tab.

You can also set style and color parameter for all tabs and overwrite them on tab level. See the tab shortcode for possible values.

{{< tabs groupid="main" style="primary" title="Rationale" icon="thumbtack" >}}
{{< tab title="Text" >}}
  Simple text is possible here...
  {{< tabs groupid="tabs-example-language" >}}
  {{% tab title="python" %}}
  Python is **super** easy.

  - most of the time.
  - if you don't want to output unicode
  {{% /tab %}}
  {{% tab title="bash" %}}
  Bash is for **hackers**.
  {{% /tab %}}
  {{< /tabs >}}
{{< /tab >}}

{{< tab title="Code" style="default" color="darkorchid" >}}
  ...but no markdown
  {{< tabs groupid="tabs-example-language" >}}
  {{% tab title="python" %}}
  ```python
  print("Hello World!")
  ```
  {{% /tab %}}
  {{% tab title="bash" %}}
  ```bash
  echo "Hello World!"
  ```
  {{% /tab %}}
  {{< /tabs >}}
{{< /tab >}}
{{< /tabs >}}
Rationale

Simple text is possible here...

Python is super easy.

  • most of the time.
  • if you don’t want to output unicode

Bash is for hackers.

...but no markdown

print("Hello World!")
echo "Hello World!"