Hugo uses Markdown as its content format. However, there are a lot of things that Markdown doesn’t support well. To overcome those limitations, Hugo created the concept of shortcodes.
The badge shortcode displays colorful markers in your text with optional icons.
ImportantVersion6.6.6Captain InfoNewAwesome
Usage
{{%badge%}}Important{{%/badge%}}{{%badgestyle="primary"title="Version"%}}6.6.6{{%/badge%}}{{%badgeicon="angle-double-up"style="red"%}}Captain{{%/badge%}}{{%badgestyle="info"%}}New{{%/badge%}}{{%badgecolor="fuchsia"icon="fa-fw fab fa-hackerrank"%}}Awesome{{%/badge%}}
{{partial"shortcodes/badge.html"(dict"page"."content""Important")}}{{partial"shortcodes/badge.html"(dict"page"."content""6.6.6""style""primary""title""Version")}}{{partial"shortcodes/badge.html"(dict"page"."content""Captain""icon""angle-double-up""style""red")}}{{partial"shortcodes/badge.html"(dict"page"."content""New""style""info")}}{{partial"shortcodes/badge.html"(dict"page"."color""fuchsia""content""Awesome""icon""fa-fw fab fa-hackerrank")}}
Parameters
Name
Default
Notes
style
default
The style scheme used for the badge.
- by severity: caution, important, info, note, tip, warning - by brand color: primary, secondary, accent - by color: blue, cyan, green, grey, magenta, orange, red - by special color: default, transparent, code, link, action, inline
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.
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, you can use link effects as well.
action
<empty>
Name of an action executed by your own script on click, without inline JavaScript. Use this instead of a JavaScript href if your site uses a strict Content Security Policy. See example.
type
see notes
The button type if href is JavaScript or action is set. Otherwise the parameter is not used. If the parameter is not given it defaults to button.
istoggle
false
When true, the button announces to assistive technology that it shows and hides something. It starts as hidden and the theme changes the state with each click. Only used if href is JavaScript or action is set. See example.
borderless
false
When true, no border will be shown around the button.
hint
<empty>
Tooltip for the button.
style
transparent
The style scheme used for the button.
- by severity: caution, important, info, note, tip, warning - by brand color: primary, secondary, accent - by color: blue, cyan, green, grey, magenta, orange, red - by special color: default, transparent, code, link, action, inline
{{partial"shortcodes/button.html"(dict"page"."content""Shout it out""href""javascript:alert('Hello world!');this.blur();""icon""bullhorn""style""primary")}}
Button with Own Action
The button is written with a data-button-action attribute. Handle it in your assets/js/custom.js, which the theme loads on every page.
If your button shows and hides something, set istoggle. The button is written with an aria-expanded attribute telling assistive technology whether the thing is shown, and the theme flips it with each click.
{{%callouticon="skull-crossbones"style="primary"title="There may be pirates"%}}Itisallabouttheboxes.{{%/callout%}}
{{%callout"primary""There may be pirates""skull-crossbones"%}}Itisallabouttheboxes.{{%/callout%}}
{{partial"shortcodes/callout.html"(dict"page"."content""It is all about the boxes.""icon""skull-crossbones""style""primary""title""There may be pirates")}}
If you want to display a transparent expandable box without any border, you can also use the details shortcode.
Parameters
Name
Position
Default
Notes
groupid
<empty>
Arbitrary name of the group the box belongs to.
Expandable boxes with the same groupid synchronize their open state.
style
1
default
The style scheme used for the box.
- by severity: caution, important, info, note, tip, warning - by brand color: primary, secondary, accent - by color: blue, cyan, green, grey, magenta, orange, red - by special color: default, transparent, code, link, action, inline
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)
expanded
<empty>
Whether to draw an expander and how the content is displayed.
- <empty>: no expander is drawn and the content is permanently shown - true: the expander is drawn and the content is initially shown - false: the expander is drawn and the content is initially hidden
hint
<empty>
Tooltip for the title of the box.
<content>
<empty>
Arbitrary text to be displayed in box.
Settings
Defining own Styles
Option Besides the predefined style values from above, you are able to define your own.
This must match the style parameter used in a shortcode.
style
<empty>
If you define this optional parameter, this is where default values for title, icon and color are taken from if style exists beforehand. You can reference predefined styles as also your own styles.
title
<empty>
The default title used. If you have set style and don’t want any title at all, you have to set this parameter to " “. See the parameter i18n if you use multiple languages in your site.
i18n
<empty>
If no title is given but i18n is set, the title will be taken from the translation files by that key.
icon
<empty>
The default icon used. If you have set style and don’t want any icon at all, you have to set this parameter to " “.
color
<empty>
The default color used. If you have set style and don’t want any color at all, you have to set this parameter to " “.
The first line of the Markdown syntax only has room for style, title and expanded. The parameters color, icon, groupid and hint are written as Markdown attributes in a line following the callout instead, so Hugo’s block attributes are required if you use one of them in Markdown syntax.
Without it, Hugo doesn’t recognize the line, so it is printed as text below the box and the parameters are ignored. The shortcode and partial syntax work regardless.
{{partial"shortcodes/callout.html"(dict"page"."content""Advises about risks or negative outcomes of certain actions.""style""caution")}}{{partial"shortcodes/callout.html"(dict"page"."content""Key information users need to know to achieve their goal.""style""important")}}{{partial"shortcodes/callout.html"(dict"page"."content""Information that users <ins>_might_</ins> find interesting.""style""info")}}{{partial"shortcodes/callout.html"(dict"page"."content""Useful information that users should know, even when skimming content.""style""note")}}{{partial"shortcodes/callout.html"(dict"page"."content""Helpful advice for doing things better or more easily.""style""tip")}}{{partial"shortcodes/callout.html"(dict"page"."content""Urgent info that needs immediate user attention to avoid problems.""style""warning")}}
Caution
Advises about risks or negative outcomes of certain actions.
Important
Key information users need to know to achieve their goal.
Info
Information that users might find interesting.
Note
Useful information that users should know, even when skimming content.
Tip
Helpful advice for doing things better or more easily.
Warning
Urgent info that needs immediate user attention to avoid problems.
{{partial"shortcodes/callout.html"(dict"page"."content""Just some default color.""icon""skull-crossbones""style""default""title""Default")}}{{partial"shortcodes/callout.html"(dict"page"."content""No visible borders.""icon""skull-crossbones""style""transparent""title""Transparent")}}{{partial"shortcodes/callout.html"(dict"page"."content""Colored like a code fence.""icon""skull-crossbones""style""code""title""Code")}}{{partial"shortcodes/callout.html"(dict"page"."content""Style of topbar buttons""icon""skull-crossbones""style""link""title""Link")}}{{partial"shortcodes/callout.html"(dict"page"."content""Style of action buttons like Mermaid zoom or block code copy-to-clipboard""icon""skull-crossbones""style""action""title""Action")}}{{partial"shortcodes/callout.html"(dict"page"."content""Style of inline buttons like inline code copy-to-clipboard""icon""skull-crossbones""style""inline""title""Inline")}}
Default
Just some default color.
Transparent
No visible borders.
Code
Colored like a code fence.
Link
Style of topbar buttons
Action
Style of action buttons like Mermaid zoom or block code copy-to-clipboard
Inline
Style of inline buttons like inline code copy-to-clipboard
Various Features
With User-Defined Color, Font Awesome Brand Icon and Markdown in Title and Content
>[!default]**Hugo**is_awesome_>{{%include"shortcodes/include/INCLUDE_ME.md"%}}{color="fuchsia"icon="fa-fw fab fa-hackerrank"}
{{%calloutcolor="fuchsia"icon="fa-fw fab fa-hackerrank"title="**Hugo** is _awesome_"%}}{{%include"shortcodes/include/INCLUDE_ME.md"%}}{{%/callout%}}
{{partial"shortcodes/callout.html"(dict"page"."color""fuchsia""content""{{% include \"shortcodes/include/INCLUDE_ME.md\" %}}""icon""fa-fw fab fa-hackerrank""title""**Hugo** is _awesome_")}}
the possibilities are endless (almost - including other shortcodes may or may not work) (almost - including other shortcodes may or may not work)
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” ↩︎
Expandable Content Area with groupid
If you give multiple expandable boxes the same groupid, at most one will be open at any given time. If you open one of the boxes, all other boxes of the same group will close.
{{partial"shortcodes/callout.html"(dict"page"."content""No need to press you!""expanded""true""groupid""callout-toggle""style""green""title""Expand me...")}}{{partial"shortcodes/callout.html"(dict"page"."content""Thank you!""expanded""false""groupid""callout-toggle""style""red""title""Expand me...")}}
Expand me…
No need to press you!
Expand me…
Thank you!
With Hint
Mouse-over the title of the box to see the hint.
>[!tip]>BuiltwithHugo.{hint="Hugo is a static site generator"}
{{%callouthint="Hugo is a static site generator"style="tip"%}}BuiltwithHugo.{{%/callout%}}
{{%callout"tip"%}}BuiltwithHugo.{{%/callout%}}
{{partial"shortcodes/callout.html"(dict"page"."content""Built with Hugo.""hint""Hugo is a static site generator""style""tip")}}
Tip
Built with Hugo.
No Content or No Title
>[!accent]Justabar>[!accent]>Justabox
{{%calloutstyle="accent"title="Just a bar"%}}{{%/callout%}}{{%calloutstyle="accent"%}}Justabox{{%/callout%}}
{{%callout"accent""Just a bar"%}}{{%/callout%}}{{%callout"accent"%}}Justabox{{%/callout%}}
{{partial"shortcodes/callout.html"(dict"page"."style""accent""title""Just a bar")}}{{partial"shortcodes/callout.html"(dict"page"."content""Just a box""style""accent")}}
{{%calloutstyle="caution"title="Callouts can have custom titles"%}}Likethisone.{{%/callout%}}{{%calloutstyle="caution"title="Title-only callout"%}}{{%/callout%}}{{%calloutexpanded="false"style="note"title="Are callouts foldable?"%}}Yes!Inafoldablecallout,thecontentsarehiddenwhenthecalloutiscollapsed{{%/callout%}}{{%calloutexpanded="true"style="note"title="Are callouts foldable?"%}}Yes!Inafoldablecallout,thecontentsarehiddenwhenthecalloutiscollapsed{{%/callout%}}{{%calloutstyle="info"title="Can callouts be nested?"%}}>[!important]Yes!,theycan.>>[!tip]Youcanevenusemultiplelayersofnesting.{{%/callout%}}
{{%callout"caution""Callouts can have custom titles"%}}Likethisone.{{%/callout%}}{{%callout"caution""Title-only callout"%}}{{%/callout%}}{{%callout"note""Are callouts foldable?"%}}Yes!Inafoldablecallout,thecontentsarehiddenwhenthecalloutiscollapsed{{%/callout%}}{{%callout"note""Are callouts foldable?"%}}Yes!Inafoldablecallout,thecontentsarehiddenwhenthecalloutiscollapsed{{%/callout%}}{{%callout"info""Can callouts be nested?"%}}>[!important]Yes!,theycan.>>[!tip]Youcanevenusemultiplelayersofnesting.{{%/callout%}}
{{partial"shortcodes/callout.html"(dict"page"."content""Like this one.""style""caution""title""Callouts can have custom titles")}}{{partial"shortcodes/callout.html"(dict"page"."style""caution""title""Title-only callout")}}{{partial"shortcodes/callout.html"(dict"page"."content""Yes! In a foldable callout, the contents are hidden when the callout is collapsed""expanded""false""style""note""title""Are callouts foldable?")}}{{partial"shortcodes/callout.html"(dict"page"."content""Yes! In a foldable callout, the contents are hidden when the callout is collapsed""expanded""true""style""note""title""Are callouts foldable?")}}{{partial"shortcodes/callout.html"(dict"page"."content""> [!important] Yes!, they can.\n> > [!tip] You can even use multiple layers of nesting.""style""info""title""Can callouts be nested?")}}
Callouts can have custom titles
Like this one.
Title-only callout
Are callouts foldable?
Yes! In a foldable callout, the contents are hidden when the callout is collapsed
Are callouts foldable?
Yes! In a foldable callout, the contents are hidden when the callout is collapsed
{{partial"shortcodes/cards.html"(dict"page"."content"(slice(dict"content""The AI native programming language.\n\n```python\nprint(\"Hello World!\")\n```""href""https://example.com""title""Python Example")(dict"content""For guys who like to tinker around.\n\n```bash\necho \"Hello World!\"\n```""title""Terminal Example")(dict"content""For the connoisseur of programming.\n\n```c\nprintf(\"Hello World!\");\n```""title""C Example")))}}
Parameters
Name
Default
Notes
columns
3
The number of columns in full width mode to display the cards in. Accepts values from 1 to 5. Numbers are reduced when width gets smaller.
template
default
The template to be used to display all cards in the set. Can be overridden for each card.
- default: The standard layout - debug: A debug layout helping you in development
Each card of the set is defined with the card shortcode.
Name
Default
Notes
href
<empty>
Either the destination URL for the card or JavaScript code to be executed on click. If this parameter is set, the card will hover on mouse over.
- if starting with javascript: all following text will be executed in your browser - every other string will be interpreted as URL, you can use link effects as well.
action
<empty>
Name of an action executed by your own script on click, without inline JavaScript. Use this instead of a JavaScript href if your site uses a strict Content Security Policy. If this parameter is set, the card will hover on mouse over. See example.
image
<empty>
URL to an image to be displayed at the start of the card.
imagealt
<empty>
Text alternative for the image, announced by a screen reader in place of the image.
Set it if the card shows nothing but its image, as the image is then the only thing left to name the card. Without it such a card falls back to the title of the page its href leads to, or to the href itself.
Leave it empty if the card also shows a title. The title names the card, so the image beside it is marked as decorative with an empty alt attribute.
title
<empty>
Arbitrary title for the card.
template
default
The template to be used to display the card. Overrides the template of the set.
- default: The standard layout - debug: A debug layout helping you in development
If you have advanced requirements to display your cards, you can place a card layout partial into layouts/partials/card that will be used for each single card.
For example, if you want to see debug output displaying the parameter the partial receives, you could set template=debug which will cause the partial layouts/partials/cards/debug.html to be called. The debug card template is shipped with the theme.
A card template will be called with all the card parameters. href and image are transformed into a form ready to be consumed.
Examples
Lots of Cards
If only an image is displayed, the full card will be used. As no title is left to name the card, describe the image with the imagealt parameter.
{{<cards>}}{{%cardhref="/images/magic.gif?download"image="/images/magic.gif"title="Everything"%}}Image,title,textandhref.Youcanalsouseimageeffectsinyour`href`.Thiscardwilldownloadtheimage.{{%/card%}}{{%cardtitle="Title and Text"%}}Justatitleandatext.Youcanuseany**Markdown**inthetext{{%/card%}}{{%cardtitle="Title Only"%}}{{%/card%}}{{%cardimage="/images/magic.gif"title="Image and Title"%}}{{%/card%}}{{%cardimage="/images/magic.gif"%}}Imageandatext{{%/card%}}{{%card%}}Textonly```c
printf("Hello Code!");
```{{%/card%}}{{%cardhref="/images/magic.gif?download"image="/images/magic.gif"imagealt="A top hat with a rabbit peeking out"%}}{{%/card%}}{{</cards>}}
{{partial"shortcodes/cards.html"(dict"page"."content"(slice(dict"content""Image, title, text and href.\n\nYou can also use image effects in your `href`. This card will download the image.""href""/images/magic.gif?download""image""/images/magic.gif""title""Everything")(dict"content""Just a title and a text. You can use any **Markdown** in the text""title""Title and Text")(dict"content""""title""Title Only")(dict"content""""image""/images/magic.gif""title""Image and Title")(dict"content""Image and a text""image""/images/magic.gif")(dict"content""Text only\n\n```c\nprintf(\"Hello Code!\");\n```")(dict"content""""href""/images/magic.gif?download""image""/images/magic.gif""imagealt""A top hat with a rabbit peeking out")))}}
{{partial"shortcodes/cards.html"(dict"page"."content"(slice(dict"content""For the connoisseur of programming.""params""{\"blub\":\"bla\"}""title""C")(dict"content""For the guys that can cope with syntax.""title""C++")(dict"content""For guys that need two destructors.""title""C#"))"template""debug")}}
C
All Parameter
{"action":"","color":"","content":"For the connoisseur of programming.","href":"","hrefattributes":{},"icon":"","image":null,"imagealt":"","imageattributes":{},"onclick":"","page":"/shortcodes/cards","params":{"blub":"bla"},"style":"filled","template":"debug","title":"C"}
C++
All Parameter
{"action":"","color":"","content":"For the guys that can cope with syntax.","href":"","hrefattributes":{},"icon":"","image":null,"imagealt":"","imageattributes":{},"onclick":"","page":"/shortcodes/cards","params":null,"style":"filled","template":"debug","title":"C++"}
C#
All Parameter
{"action":"","color":"","content":"For guys that need two destructors.","href":"","hrefattributes":{},"icon":"","image":null,"imagealt":"","imageattributes":{},"onclick":"","page":"/shortcodes/cards","params":null,"style":"filled","template":"debug","title":"C#"}
Card with Own Action
The card is written with a data-button-action attribute. Handle it in your assets/js/custom.js, which the theme loads on every page.
{{%cardaction="shout"title="Shout it out"%}}Clicktogreettheworld{{%/card%}}
{{partial"shortcodes/card.html"(dict"page"."action""shout""content""Click to greet the world""title""Shout it out")}}
This shortcode is fully compatible with Hugo’s details shortcode but offers some extensions.
Markdown callout syntax is available in other Markdown parsers like Obsidian and therefore is the recommended syntax for generating portable Markdown.
In Markdown syntax the section is a callout of the style details. Its first line takes summary and open, while name and title are written as the Markdown attributesgroupid and hint. class and raw are not available.
The callout shortcode is also capable of displaying expandable/collapsible sections of text but with additional parameters for color and additional icons.
Parameters
Name
Default
Notes
summary
"Details"
Arbitrary text to appear next to the expand/collapse icon.
open
false
How the content is displayed.
- true: the content is initially shown - false: the content is initially hidden
name
<empty>
Arbitrary name of the group the section belongs to.
Of all sections with the same name, at most one is open at any given time.
class
<empty>
CSS classes to be added to the section.
title
<empty>
Arbitrary text to be displayed as a tooltip for the summary.
raw
false
Extension. How the content is processed.
- false: the content is rendered as Markdown - true: the content is written as it is, see below
<content>
<empty>
Arbitrary text to be displayed on expand.
Examples
All Defaults
>[!details]-Details>Yes,youdidit!
{{<details>}}Yes,youdidit!{{</details>}}
{{partial"shortcodes/details.html"(dict"page"."content""Yes, you did it!")}}
{{partial"shortcodes/details.html"(dict"page"."content""No need to press you!""open""true""summary""Expand me...")}}
Expand me…
No need to press you!
Arbitrary Text
>[!details]-Showmealmost**endless**possibilities>Youcanaddstandardmarkdownsyntax:>>-multipleparagraphs>-bulletpointlists>-_emphasized_,**bold**andeven**_boldemphasized_**text>-[links](https://example.com)>-etc.>>```plaintext
> ...and even source code
> ```>>>thepossibilitiesareendless(almost-includingothershortcodesmayormaynotwork)
{{<detailssummary="Show me almost **endless** possibilities">}}Youcanaddstandardmarkdownsyntax:-multipleparagraphs-bulletpointlists-_emphasized_,**bold**andeven**_boldemphasized_**text-[links](https://example.com)-etc.```plaintext
...and even source code
```>thepossibilitiesareendless(almost-includingothershortcodesmayormaynotwork){{</details>}}
{{partial"shortcodes/details.html"(dict"page"."content""You can add standard markdown syntax:\n\n- multiple paragraphs\n- bullet point lists\n- _emphasized_, **bold** and even **_bold emphasized_** text\n- [links](https://example.com)\n- etc.\n\n```plaintext\n...and even source code\n```\n\n> the possibilities are endless (almost - including other shortcodes may or may not work)""summary""Show me almost **endless** possibilities")}}
the possibilities are endless (almost - including other shortcodes may or may not work)
Grouped Sections
If you give multiple sections the same name, they behave like an accordion: at most one will be open at any given time. If you open one of the sections, all other sections of the same group will close.
{{partial"shortcodes/details.html"(dict"page"."content""No need to press you!""name""details-toggle""open""true""summary""Expand me...")}}{{partial"shortcodes/details.html"(dict"page"."content""Thank you!""name""details-toggle""summary""Expand me...")}}
Expand me…
No need to press you!
Expand me…
Thank you!
Raw Content
The content is rendered as Markdown on its own, apart from the rest of your page. This has consequences:
A footnote defined inside of the content is listed inside of the section instead of at the end of your page, and a footnote defined outside of it can not be referenced.
A heading inside of the content doesn’t show up in the table of contents.
With goldmark.renderer.unsafe=false (which is the default if you don’t set it), HTML inside of the content is removed. This includes the HTML written by other shortcodes you call in there.
If the content is HTML already or contains other shortcodes, set raw=true. The content is then written as it is and no Markdown is rendered.
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 by providing positional parameters 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 syntax if you call it using compatibility syntax.
Markdown codefence syntax is widely available in other Markdown parsers like GitHub and therefore is the recommended syntax for generating portable Markdown.
The tab shortcode is also capable of displaying code but with limited options.
Parameters
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 Hugo’s 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 hugo.toml and overwritten via front matter. 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.
You can configure the color style used for code blocks in your color variants stylesheet file using the --CODE-theme variable. This requires further configuration as described in the above link.
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 hugo.toml and add lineNos = true when calling the shortcode instead of the specific values table or inline.
```py {lineNoStart="666" lineNos="true"}
# 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("!")
```
{{partial"shortcodes/highlight.html"(dict"page"."content""# 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\nprint(\"Hello\")\nprint(\" \")\nprint(\"World\")\nprint(\"!\")""lineNoStart""666""lineNos""true""type""py")}}
{{partial"shortcodes/highlight.html"(dict"page"."content""# 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\nprint(\"Hello\")\nprint(\" \")\nprint(\"World\")\nprint(\"!\")""type""py""options""lineNoStart=666,lineNos=true")}}
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 credits667print("Hello")668print(" ")669print("World")670print("!")
With Title
```py {title="python"}
# a bit shorter
print("Hello World!")
```
{{partial"shortcodes/highlight.html"(dict"page"."content""# a bit shorter\nprint(\"Hello World!\")""title""python""type""py")}}
{{partial"shortcodes/highlight.html"(dict"page"."content""# a bit shorter\nprint(\"Hello World!\")""type""py""options""title=python")}}
# a bit shorterprint("Hello World!")
With Wrap
```py {hl_lines="2" wrap="true"}
# 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
```
{{partial"shortcodes/highlight.html"(dict"page"."content""# Quicksort Python One-liner\nlambda 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]])\n# Some more stuff""hl_lines""2""type""py""wrap""true")}}
{{partial"shortcodes/highlight.html"(dict"page"."content""# Quicksort Python One-liner\nlambda 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]])\n# Some more stuff""type""py""options""hl_lines=2,wrap=true")}}
# Quicksort Python One-linerlambdaL:[]ifL==[]elseqsort([xforxinL[1:]ifx<L[0]])+L[0:1]+qsort([xforxinL[1:]ifx>=L[0]])# Some more stuff
Without Wrap
```py {hl_lines="2" wrap="false"}
# 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
```
{{partial"shortcodes/highlight.html"(dict"page"."content""# Quicksort Python One-liner\nlambda 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]])\n# Some more stuff""hl_lines""2""type""py""wrap""false")}}
{{partial"shortcodes/highlight.html"(dict"page"."content""# Quicksort Python One-liner\nlambda 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]])\n# Some more stuff""type""py""options""hl_lines=2,wrap=false")}}
# Quicksort Python One-linerlambdaL:[]ifL==[]elseqsort([xforxinL[1:]ifx<L[0]])+L[0:1]+qsort([xforxinL[1:]ifx>=L[0]])# Some more stuff
Icon
The icon shortcode displays icons using the Font Awesome library.
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
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.
Customizing Icons
Font Awesome provides many ways to modify the icon
Change color (by default the icon will inherit the parent color)
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 <iclass="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 hugo.toml:
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
OptionFront Matter You can use include.errorlevel to control what should happen if a local link cannot 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 cannot resolve files inside of your static directory. The file must be a resource of the page or the site.
the possibilities are endless (almost - including other shortcodes may or may not work) (almost - including other shortcodes may or may not work)
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 renders complex math and chemical formulae using Hugo’s built-in KaTeX.
You can also use pure Markdown for writing simple math expressions.
Delimiters around your formulae require the Passthrough configuration, as the theme finds your formulae by them. Passthrough syntax itself has limited features as it does not provide any of the below parameters besides content. Nevertheless, it is widely available in other Markdown parsers like GitHub and therefore is the recommended syntax for generating portable Markdown.
Parameters
Name
Default
Notes
align
center
The vertical alignment.
Allowed values are left, center or right.
<content>
<empty>
Your formulae.
Enclose each formula in the block or inline delimiters of your Passthrough configuration. Text outside of them is written as Markdown.
Without any delimiters, the whole content is one formula displayed as a block.
Settings
Output of the Formulae
OptionFront Matter By default, formulae are written as MathML, which every current browser displays without any stylesheet or font of the theme. The display quality depends on the browser and the math fonts installed on your reader’s system.
If you want your formulae to look the same in every browser, set math.output to htmlAndMathml. The theme then links the KaTeX stylesheet and fonts to every page containing math. The MathML is kept for screen readers. The value html omits it.
[params][params.math]output='htmlAndMathml'
params:math:output:htmlAndMathml
{"params":{"math":{"output":"htmlAndMathml"}}}
Providing Options for KaTeX
OptionFront Matter Besides output, you can set every option of Hugo’s transform.ToMath function in math, for example your own macros.
Each option of your page’s front matter overwrites the option of the same name of your configuration options.
A formula that KaTeX can not render is written as its source and reported as a warning in your build.
Force Loading of the KaTeX Stylesheet
OptionFront Matter If your output needs the KaTeX stylesheet, it will be linked to your page if the page contains a math shortcode, Markdown codefence, Passthrough syntax or the partial is called from your templates.
If you write KaTeX’s HTML by other means, you can force linking the stylesheet by setting math.force=true. If a formula was rendered, the option has no effect.
math=true does the same but can’t be combined with other math.* options.
[params][params.math]force=true
params:math:force:true
{"params":{"math":{"force":true}}}
Passthrough Configuration
The theme finds your formulae by the delimiters of Hugo’s Passthrough configuration, so it is required if you use delimiters in any syntax. It also lets you write math without enclosing it in a shortcode or Markdown codefence.
The mermaid shortcode generates diagrams and flowcharts from text using the Mermaid library.
graph LR;
If --> Then
Then --> Else
Every graph has a button to show it in a lightbox. Press the button again, click beside the graph, press ESC or go back in your browser to return to the page. The enlarged graph has its own URL, so you can share a link to it, like you can for an enlarged image. In the lightbox, a graph is panned and zoomed the same way as on the page.
Usage
```mermaid {align="center" zoom="true"}
graph LR;
If --> Then
Then --> Else
```
{{partial"shortcodes/mermaid.html"(dict"page"."align""center""content""graph LR;\n If --> Then\n Then --> Else""zoom""true")}}
Parameters
Name
Default
Notes
align
center
The vertical alignment.
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 your configurations options or the pages front matter or false if not set at all.
- false: no pan or zoom - true: pan and zoom active
<content>
<empty>
Your Mermaid graph.
Settings
Configuring Pan and Zoom
OptionFront Matter The generated graphs can be panned by dragging them and zoomed by using the mousewheel. On mobile devices you can use finger gestures. With the keyboard, a focused graph is panned by the cursor keys and zoomed by + and -, as listed with the other keyboard shortcuts.
By default this is disabled. Set mermaidZoom=true to enable it.
Individual settings of a graphs zoom parameter have precedence over the page’s front matter and configuration options in that order.
[params]mermaidZoom=true
params:mermaidZoom:true
{"params":{"mermaidZoom":true}}
Providing Initialization Options for the Mermaid Library
OptionFront Matter 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 for all allowed settings.
Note
Using the theme setting in the initialization options is unsupported. To set the theme globally edit the --MERMAID-theme variable of your color variant.
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 on top of the settings of your page’s front matter or configuration options.
The theme uses the shipped Mermaid library by default.
In case you want to use a different version of the Mermaid library, store it as assets/js/mermaid/mermaid.min.js in your site. It replaces the shipped version.
Force Loading of the Mermaid Library
OptionFront Matter The Mermaid library will be loaded if the page contains an mermaid shortcode, Markdown codefence or the partial is called from your templates.
You can force loading the Mermaid library if no shortcode, Markdown codefence or partial was called by setting mermaid.force=true. If a shortcode, Markdown codefence or partial was called, this option has no effect. This comes handy in case you are using scripting to render a graph.
[params][params.mermaid]force=true
params:mermaid:force:true
{"params":{"mermaid":{"force":true}}}
Setting a Specific Mermaid Theme
While you can configure the Mermaid theme to render your graph by using one of the initialization options, the recommended way is to set the default value using the --MERMAID-theme variable in your color variant stylesheet. This allows your graphs to look pretty when the user switches the color variant.
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]
```
swimlane-beta LR
subgraph Customer
request[Request service]
receive[Receive update]
end
subgraph Support
triage[Triage request]
answer[Send answer]
end
subgraph Engineering
investigate[Investigate issue]
fix[Prepare fix]
end
request --> triage
triage -->|Known issue| answer
triage -->|Needs code change| investigate
investigate --> fix --> answer
answer --> receive
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!
```
{{partial"shortcodes/mermaid.html"(dict"page"."content""%%{init:{\"fontFamily\":\"monospace\", \"sequence\":{\"showSequenceNumbers\":true}}}%%\nsequenceDiagram\n Alice->>John: Hello John, how are you?\n loop Healthcheck\n John->>John: Fight against hypochondria\n end\n Note right of John: Rational thoughts!\n John-->>Alice: Great!\n John->>Bob: How about you?\n Bob-->>John: Jolly good!")}}
%%{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
```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 with Right Alignment
```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
```
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"
```
%%{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
```
{{partial"shortcodes/mermaid.html"(dict"page"."content""journey\n title My working day\n section Go to work\n Make tea: 5: Me\n Go upstairs: 3: Me\n Do work: 1: Me, Cat\n section Go home\n Go downstairs: 5: Me\n Sit down: 3: Me")}}
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
```
{{partial"shortcodes/mermaid.html"(dict"page"."content""gantt\n dateFormat YYYY-MM-DD\n title Adding GANTT diagram functionality to Mermaid\n section A section\n Completed task :done, des1, 2014-01-06,2014-01-08\n Active task :active, des2, 2014-01-09, 3d\n Future task : des3, after des2, 5d\n Future task2 : des4, after des3, 5d\n section Critical tasks\n Completed task in the critical line :crit, done, 2014-01-06,24h\n Implement parser and jison :crit, done, after des1, 2d\n Create tests for parser :crit, active, 3d\n Future task in critical line :crit, 5d\n Create tests for renderer :2d\n Add to Mermaid :1d")}}
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
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>}}C4ContexttitleSystemContextdiagramforInternetBankingSystemEnterprise_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>}}
{{partial"shortcodes/mermaid.html"(dict"page"."content""C4Context\n title System Context diagram for Internet Banking System\n Enterprise_Boundary(b0, \"BankBoundary0\") {\n Person(customerA, \"Banking Customer A\", \"A customer of the bank, with personal bank accounts.\")\n Person(customerB, \"Banking Customer B\")\n Person_Ext(customerC, \"Banking Customer C\", \"desc\")\n Person(customerD, \"Banking Customer D\", \"A customer of the bank, <br/> with personal bank accounts.\")\n\n System(SystemAA, \"Internet Banking System\", \"Allows customers to view information about their bank accounts, and make payments.\")\n\n Enterprise_Boundary(b1, \"BankBoundary\") {\n SystemDb_Ext(SystemE, \"Mainframe Banking System\", \"Stores all of the core banking information about customers, accounts, transactions, etc.\")\n\n System_Boundary(b2, \"BankBoundary2\") {\n System(SystemA, \"Banking System A\")\n System(SystemB, \"Banking System B\", \"A system of the bank, with personal bank accounts. next line.\")\n }\n\n System_Ext(SystemC, \"E-mail system\", \"The internal Microsoft Exchange e-mail system.\")\n SystemDb(SystemD, \"Banking System D Database\", \"A system of the bank, with personal bank accounts.\")\n\n Boundary(b3, \"BankBoundary3\", \"boundary\") {\n SystemQueue(SystemF, \"Banking System F Queue\", \"A system of the bank.\")\n SystemQueue_Ext(SystemG, \"Banking System G Queue\", \"A system of the bank, with personal bank accounts.\")\n }\n }\n }\n\n BiRel(customerA, SystemAA, \"Uses\")\n BiRel(SystemAA, SystemE, \"Uses\")\n Rel(SystemAA, SystemC, \"Sends e-mails\", \"SMTP\")\n Rel(SystemC, customerA, \"Sends e-mails to\")\n\n UpdateElementStyle(customerA, $fontColor=\"red\", $bgColor=\"grey\", $borderColor=\"red\")\n UpdateRelStyle(customerA, SystemAA, $textColor=\"blue\", $lineColor=\"blue\", $offsetX=\"5\")\n UpdateRelStyle(SystemAA, SystemE, $textColor=\"blue\", $lineColor=\"blue\", $offsetY=\"-10\")\n UpdateRelStyle(SystemAA, SystemC, $textColor=\"blue\", $lineColor=\"blue\", $offsetY=\"-40\", $offsetX=\"-50\")\n UpdateRelStyle(SystemC, customerA, $textColor=\"red\", $lineColor=\"red\", $offsetX=\"-50\", $offsetY=\"20\")\n\n UpdateLayoutConfig($c4ShapeInRow=\"3\", $c4BoundaryInRow=\"1\")")}}
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
```
{{partial"shortcodes/mermaid.html"(dict"page"."content""mindmap\n root((mindmap))\n Origins\n Long history\n ::icon(fa fa-book)\n Popularisation\n British popular psychology author Tony Buzan\n Research\n On effectiveness<br/>and features\n On Automatic creation\n Uses\n Creative techniques\n Strategic planning\n Argument mapping\n Tools\n Pen and paper\n 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
```
{{partial"shortcodes/mermaid.html"(dict"page"."content""timeline\n title History of Social Media Platform\n 2002 : LinkedIn\n 2004 : Facebook\n : Google\n 2005 : Youtube\n 2006 : Twitter")}}
timeline
title History of Social Media Platform
2002 : LinkedIn
2004 : Facebook
: Google
2005 : Youtube
2006 : Twitter
ZenUML
ZenUML is currently not available with the Mermaid version shipped with the theme due to further required dependencies. Use sequence diagrams instead.
```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-betatitle"Sales Revenue"x-axis[jan,feb,mar,apr,may,jun,jul,aug,sep,oct,nov,dec]y-axis"Revenue (in $)"4000-->11000bar[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>}}
{{partial"shortcodes/mermaid.html"(dict"page"."content""xychart-beta\n title \"Sales Revenue\"\n x-axis [jan, feb, mar, apr, may, jun, jul, aug, sep, oct, nov, dec]\n y-axis \"Revenue (in $)\" 4000 --> 11000\n bar [5000, 6000, 7500, 8200, 9500, 10500, 11000, 10200, 9200, 8500, 7000, 6000]\n line [5000, 6000, 7500, 8200, 9500, 10500, 11000, 10200, 9200, 8500, 7000, 6000]")}}
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]
Block Diagram
```mermaid
block-beta
columns 1
db(("DB"))
blockArrowId6<[" "]>(down)
block:ID
A
B["A wide one in the middle"]
C
end
space
D
ID --> D
C --> D
style B fill:#969,stroke:#333,stroke-width:4px
```
{{<mermaid>}}block-betacolumns1db(("DB"))blockArrowId6<[" "]>(down)block:IDAB["A wide one in the middle"]CendspaceDID-->DC-->DstyleBfill:#969,stroke:#333,stroke-width:4px{{</mermaid>}}
{{partial"shortcodes/mermaid.html"(dict"page"."content""block-beta\n columns 1\n db((\"DB\"))\n blockArrowId6<[\" \"]>(down)\n block:ID\n A\n B[\"A wide one in the middle\"]\n C\n end\n space\n D\n ID --> D\n C --> D\n style B fill:#969,stroke:#333,stroke-width:4px")}}
block-beta
columns 1
db(("DB"))
blockArrowId6<[" "]>(down)
block:ID
A
B["A wide one in the middle"]
C
end
space
D
ID --> D
C --> D
style B fill:#969,stroke:#333,stroke-width:4px
```mermaid
---
config:
kanban:
ticketBaseUrl: 'https://mermaidchart.atlassian.net/browse/#TICKET#'
---
kanban
Todo
[Create Documentation]
docs[Create Blog about the new diagram]
[In progress]
id6[Create renderer so that it works in all cases. We also add som extra text here for testing purposes. And some more just for the extra flare.]
id9[Ready for deploy]
id8[Design grammar]@{ assigned: 'knsv' }
id10[Ready for test]
id4[Create parsing tests]@{ ticket: MC-2038, assigned: 'K.Sveidqvist', priority: 'High' }
id66[last item]@{ priority: 'Very Low', assigned: 'knsv' }
id11[Done]
id5[define getData]
id2[Title of diagram is more than 100 chars when user duplicates diagram with 100 char]@{ ticket: MC-2036, priority: 'Very High'}
id3[Update DB function]@{ ticket: MC-2037, assigned: knsv, priority: 'High' }
id12[Can't reproduce]
id3[Weird flickering in Firefox]
```
{{partial"shortcodes/mermaid.html"(dict"page"."content""---\nconfig:\n kanban:\n ticketBaseUrl: 'https://mermaidchart.atlassian.net/browse/#TICKET#'\n---\nkanban\n Todo\n [Create Documentation]\n docs[Create Blog about the new diagram]\n [In progress]\n id6[Create renderer so that it works in all cases. We also add som extra text here for testing purposes. And some more just for the extra flare.]\n id9[Ready for deploy]\n id8[Design grammar]@{ assigned: 'knsv' }\n id10[Ready for test]\n id4[Create parsing tests]@{ ticket: MC-2038, assigned: 'K.Sveidqvist', priority: 'High' }\n id66[last item]@{ priority: 'Very Low', assigned: 'knsv' }\n id11[Done]\n id5[define getData]\n id2[Title of diagram is more than 100 chars when user duplicates diagram with 100 char]@{ ticket: MC-2036, priority: 'Very High'}\n id3[Update DB function]@{ ticket: MC-2037, assigned: knsv, priority: 'High' }\n\n id12[Can't reproduce]\n id3[Weird flickering in Firefox]")}}
---
config:
kanban:
ticketBaseUrl: 'https://mermaidchart.atlassian.net/browse/#TICKET#'
---
kanban
Todo
[Create Documentation]
docs[Create Blog about the new diagram]
[In progress]
id6[Create renderer so that it works in all cases. We also add som extra text here for testing purposes. And some more just for the extra flare.]
id9[Ready for deploy]
id8[Design grammar]@{ assigned: 'knsv' }
id10[Ready for test]
id4[Create parsing tests]@{ ticket: MC-2038, assigned: 'K.Sveidqvist', priority: 'High' }
id66[last item]@{ priority: 'Very Low', assigned: 'knsv' }
id11[Done]
id5[define getData]
id2[Title of diagram is more than 100 chars when user duplicates diagram with 100 char]@{ ticket: MC-2036, priority: 'Very High'}
id3[Update DB function]@{ ticket: MC-2037, assigned: knsv, priority: 'High' }
id12[Can't reproduce]
id3[Weird flickering in Firefox]
Architecture
```mermaid
architecture-beta
group api(cloud)[API]
service db(database)[Database] in api
service disk1(disk)[Storage] in api
service disk2(disk)[Storage] in api
service server(server)[Server] in api
db:L -- R:server
disk1:T -- B:server
disk2:T -- B:db
```
{{partial"shortcodes/mermaid.html"(dict"page"."content""architecture-beta\n group api(cloud)[API]\n\n service db(database)[Database] in api\n service disk1(disk)[Storage] in api\n service disk2(disk)[Storage] in api\n service server(server)[Server] in api\n\n db:L -- R:server\n disk1:T -- B:server\n disk2:T -- B:db")}}
architecture-beta
group api(cloud)[API]
service db(database)[Database] in api
service disk1(disk)[Storage] in api
service disk2(disk)[Storage] in api
service server(server)[Server] in api
db:L -- R:server
disk1:T -- B:server
disk2:T -- B:db
{{partial"shortcodes/mermaid.html"(dict"page"."content""venn-beta\n title \"Team overlap\"\n set Frontend\n set Backend\n union Frontend,Backend[\"APIs\"]")}}
venn-beta
title "Team overlap"
set Frontend
set Backend
union Frontend,Backend["APIs"]
Ishikawa
```mermaid
ishikawa-beta
Blurry Photo
Process
Out of focus
Shutter speed too slow
Protective film not removed
Beautification filter applied
User
Shaky hands
Equipment
LENS
Inappropriate lens
Damaged lens
Dirty lens
SENSOR
Damaged sensor
Dirty sensor
Environment
Subject moved too quickly
Too dark
```
{{partial"shortcodes/mermaid.html"(dict"page"."content""ishikawa-beta\n Blurry Photo\n Process\n Out of focus\n Shutter speed too slow\n Protective film not removed\n Beautification filter applied\n User\n Shaky hands\n Equipment\n LENS\n Inappropriate lens\n Damaged lens\n Dirty lens\n SENSOR\n Damaged sensor\n Dirty sensor\n Environment\n Subject moved too quickly\n Too dark")}}
ishikawa-beta
Blurry Photo
Process
Out of focus
Shutter speed too slow
Protective film not removed
Beautification filter applied
User
Shaky hands
Equipment
LENS
Inappropriate lens
Damaged lens
Dirty lens
SENSOR
Damaged sensor
Dirty sensor
Environment
Subject moved too quickly
Too dark
Wardley
```mermaid
wardley-beta
title Tea Shop Value Chain
anchor Business [0.95, 0.63]
component Cup of Tea [0.79, 0.61]
component Tea [0.63, 0.81]
component Hot Water [0.52, 0.80]
component Kettle [0.43, 0.35]
component Power [0.10, 0.70]
Business -> Cup of Tea
Cup of Tea -> Tea
Cup of Tea -> Hot Water
Hot Water -> Kettle
Kettle -> Power
evolve Kettle 0.62
evolve Power 0.89
note "Standardising power allows Kettles to evolve faster" [0.30, 0.49]
```
{{<mermaid>}}wardley-betatitleTeaShopValueChainanchorBusiness[0.95,0.63]componentCupofTea[0.79,0.61]componentTea[0.63,0.81]componentHotWater[0.52,0.80]componentKettle[0.43,0.35]componentPower[0.10,0.70]Business->CupofTeaCupofTea->TeaCupofTea->HotWaterHotWater->KettleKettle->PowerevolveKettle0.62evolvePower0.89note"Standardising power allows Kettles to evolve faster"[0.30,0.49]{{</mermaid>}}
{{partial"shortcodes/mermaid.html"(dict"page"."content""wardley-beta\n title Tea Shop Value Chain\n\n anchor Business [0.95, 0.63]\n component Cup of Tea [0.79, 0.61]\n component Tea [0.63, 0.81]\n component Hot Water [0.52, 0.80]\n component Kettle [0.43, 0.35]\n component Power [0.10, 0.70]\n\n Business -> Cup of Tea\n Cup of Tea -> Tea\n Cup of Tea -> Hot Water\n Hot Water -> Kettle\n Kettle -> Power\n\n evolve Kettle 0.62\n evolve Power 0.89\n\n note \"Standardising power allows Kettles to evolve faster\" [0.30, 0.49]")}}
wardley-beta
title Tea Shop Value Chain
anchor Business [0.95, 0.63]
component Cup of Tea [0.79, 0.61]
component Tea [0.63, 0.81]
component Hot Water [0.52, 0.80]
component Kettle [0.43, 0.35]
component Power [0.10, 0.70]
Business -> Cup of Tea
Cup of Tea -> Tea
Cup of Tea -> Hot Water
Hot Water -> Kettle
Kettle -> Power
evolve Kettle 0.62
evolve Power 0.89
note "Standardising power allows Kettles to evolve faster" [0.30, 0.49]
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.
A specification that is a resource of your page or site is found by the search. A specification given by URL is loaded by the browser of your reader and is not.
Parameters
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.
lang
<empty>
The language code used for the reading direction of the Swagger UI and for the texts the theme adds to it, like Expand all and Collapse all. This must be one of the languages configured for your site. If not set, the language of the page is used.
Settings
Enabling Link Warnings
OptionFront Matter You can use openapi.errorlevel to control what should happen if a local OpenAPI specification link cannot 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 cannot resolve files inside of your static directory. The file must be a resource of the page or the site.
Using a Different Version of the Swagger UI Library
The theme uses the shipped Swagger UI library by default.
In case you want to use a different version of the Swagger UI library, store its files as assets/js/swagger-ui/swagger-ui-bundle.js, assets/js/swagger-ui/swagger-ui-standalone-preset.js and assets/css/swagger-ui/swagger-ui.css in your site. They replace the shipped version.
Force Loading of the Swagger UI Library
OptionFront Matter The Swagger UI library will be loaded if the page contains an openapi shortcode or codefence.
You can force loading the Swagger UI library if no shortcode or codefence was used by setting openapi.force=true. If a shortcode or codefence was found, the option has no effect. This comes handy in case you are using scripting to render a spec.
[params][params.openapi]force=true
params:openapi:force:true
{"params":{"openapi":{"force":true}}}
Setting a Specific Swagger UI Theme
The recommended way to configure your Swagger UI theme is to set the default value using the --OPENAPI-theme and OPENAPI-CODE-theme variable in your color variant stylesheet. This allows your specs to look pretty when the user switches the color variant.
The theme uses Swaggers theming support. For --OPENAPI-theme the only allowed values are light or dark. For --OPENAPI-CODE-themethe allowed values are agate, arta, monokai, nord, obsidian, tomorrow-night, idea.
A listing is made in two steps. First, a query retrieves the pages, filters, orders and groups them. Second, a display layout renders the result. Each parameter below belongs to one of the two. All parameters can also be set in the front matter.
The taxonomy and term pages are using this shortcode internally, and by using front matter you can modify the apperance. So everything described here applies to the taxonomy and term pages as well.
Query Parameters
The query assembles the pages as a internal tree structure, similar to the menu. A page dropped from the tree structure by hidden, kind or where takes all pages below it with it. If you want to list pages from any level, set flatten=true: the pages become one list and each page is kept or dropped on its own.
Name
Default
Notes
pageref
<empty>
A reference to the page whose pages are listed, like /shortcodes/pages/fruits or relative to the current page like fruits.
If set and it doesn’t resolve to a page, the build fails. If not set, the current page is used or, if called as partial, the page given in page.
axis
see notes
Along which axis the pages are collected, seen from the page.
- descendants: the children of the page, and with levels above 1 their descendants down to that many levels - siblings: the other children of the page’s parent - ancestors: the parent, its parent and so on, up to levels levels - taxonomy: the terms of a taxonomy page - term: the pages of a term page
Defaults to taxonomy on taxonomy pages, term on term pages and descendants everywhere else.
levels
1
For axis=descendants, how many levels to go down, for axis=ancestors, how many levels to go up. For example, axis=ancestors with levels=1 lists just the parent. To get all of them, set this to a high number, eg. 999.
flatten
false
When true, lists all collected pages as one list instead of a tree. Without orderby the pages keep the order of the tree, a parent before the pages below it; with orderby all pages are ordered together, and with groupby each page is grouped on its own.
kind
all
Which kind of pages to keep.
- all: every page - leaf: only pages without pages of their own - branch: only pages with pages of their own
In a tree, a page not kept is dropped together with the pages below it.
- false: drop them, together with all pages below them - true: keep them
For taxonomy and term pages this has no effect, as the disableTagHiddenPagesOption decides here.
where
<empty>
Keeps only pages matching the condition <expression> <operator> <value>, see expressions.
- =, !=: equal, not equal - <, <=, >, >=: less, greater - in: equal to one of a comma separated list of values
A value may be delimited by ", ' or a backtick, which a value in the list of in needs if it contains a comma. Numbers and dates are compared by their value, everything else as text. A page missing the value only matches !=.
In a tree, a page not matching is dropped together with the pages below it.
groupby
see notes
Groups the pages by the value of an expression. Without a value, the pages are not grouped.
Defaults to linktitle | left 1 | upper on taxonomy and term pages without pages front matter and to no grouping everywhere else.
Pages for which the expression has no value are put into a last group of their own, labelled Other.
grouplabel
<the value>
The heading of each group, as an expression evaluated for the group’s first page.
grouporder
asc
The order of the groups.
- asc: ascending - desc: descending
orderby
see notes
The order of the pages, as a comma separated list of expressions, each optionally followed by asc or desc. The first expression decides, the next ones break ties. An argument containing a comma has to be delimited, like date | format 'January 2, 2006'.
- auto keeps the order given by ordersectionsby of the page’s Front Matter or by ordersectionsby of the configuration Option or Hugo’s default order
Defaults to auto, except on taxonomy and term pages, which have no order of their own: there it defaults to linktitle, regardless of ordersectionsby.
Pages for which an expression has no value are put last.
limit
<empty>
Keeps only the first pages after ordering.
Display Parameters
The display renders the pages the query found, group by group if they were grouped. Grouping is optional: without groupby, all pages form one group without a heading. The shortcode writes each group’s heading, the display the pages below it, showing their level in the tree in its own way. The display parameters only decide how the pages look, never which pages are listed or in what order.
- tree: a nested, unordered list of normal text - headings: a non-nested list of headings depending on the page’s level - sections: a heading for each page of the first level, a nested, unordered list of normal text for pages below - list: a non-nested list of normal text - cards: a card for each page, see below for details
The starting heading level. Headings of the headings and sections displays start one level below if the pages are grouped.
columns
see notes
The number of columns in full width mode. Accepts values from 1 to 5. Numbers are reduced when width gets smaller.
Defaults to 3 on taxonomy and term pages without pages front matter and for display=cards, and to 1 everywhere else. Has no effect for display=sections.
description
false
When true shows a short text under each page. 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.
breadcrumb
see notes
When true shows the breadcrumb under each page.
Defaults to true on term pages unless the disableTermBreadcrumbsOption is set, and to false everywhere else.
image
true
For display=cards decides whether to put an image on the card.
Every parameter but pageref can also be set in the front matter of the page the shortcode is called in, as params.pages.<name>, eg. params.pages.display. The front matter adds to the parameters given to the shortcode. If a parameter is given in both, the shortcode wins. If the shortcode is called with pageref, no front matter is read, neither that of the calling page nor that of the referenced one. If you want to reset a parameter set elsewhere to no value, set it to a string containing only whitespace like " ".
Taxonomy and term pages are grouped by the first letter and shown in columns only as long as their front matter sets no pages parameter at all. Once it sets any, groupby and columns default to the same values as everywhere else, so you only get what you ask for.
As front matter works on every page, you can use Hugo’s cascade to give all listings of a subtree the same look, for example all cards in two columns.
The parameters where, groupby, grouplabel and orderby take expressions. An expression reads a value of a page and passes it through a pipeline of functions, each separated by |.
<field> [| <function> [<argument>]]...
In this notation, <…> stands for something you fill in, square brackets […] mark something as optional, and ... means the part before may be repeated.
Everything after a function’s name is its argument. An argument is either a number, written as is like left 1, or a text, delimited by ", ' or a backtick like format 'January 2, 2006'. The delimiters keep a | or a comma inside the text from separating the pipeline or the expressions of orderby. Inside a shortcode parameter delimited by ", use ' or a backtick.
Fields
Name
Value
title
the page’s title as shown in its heading, like Tag :: Foo for a term page
linktitle
the title as shown in the menu, which is the page’s linkTitle or else its title
weight
the weight; like for Hugo, a weight of 0 has no value
length
the length of the content in characters
path
the logical path
section
the top-level section
date, lastmod, publishdate, expirydate
the respective date; a date that is not set has no value
params.<name>
a value of the page’s front matter params; use dots to reach deeper, like params.author.name; a list or a map has no value
Functions
A text argument is shown with its delimiters, like '<layout>', a number argument without, like <n>.
Name
Result
upper
the text in upper case
lower
the text in lower case
trim
the text without leading and trailing whitespace
left <n>
the first n characters of the text
right <n>
the last n characters of the text
translate ['<prefix>']
the text translated by your translation files, looked up by the optional prefix followed by the text
year
the year of a date
month
the month of a date as a number from 1 to 12
day
the day of the month of a date
weekday
the day of the week of a date as a number from 1 for Monday to 7 for Sunday
format '<layout>'
a date formatted by a Hugo date layout, including the localized ones like :date_long
coalesce '<value>'
the value if the expression has no value so far
default '<value>'
the value if the expression has no value so far or it is zero or false
Where an expression yields numbers for some pages and text for others, the numbers come first, ordered by value, followed by the text, ordered as text - in both directions. A date counts as a number, while a number written as text in front matter, like '10', is text.
A group is always ordered by the value it was grouped by, never by its heading. For groupby ending in format, that value is the parts of the date the layout shows, so the groups come in calendar order - date | format '2006-01' orders its groups by year and month, and date | format 'January' orders them January to December, even for pages from different years.
So to show translated group headings while keeping the order of the untranslated values, use translate in grouplabel rather than in groupby. To order the groups alphabetically by their translation in each language instead, use translate in groupby.
In orderby, an expression ending in format orders the same way - date | format '2. January' orders by day and month, whatever the year.
Displays
The displays differ in how they show a page’s level below the listed page. With flatten=true all pages are on the same level, so every display shows them side by side.
Display
List
Titles
Levels shown by
Output
tree
a nested, unordered list
standard text
indentation
Markdown
headings
a non-nested list
headings, listed in the table of contents
heading size, starting at headinglevel
Markdown
sections
a non-nested list for the first level, a nested, unordered list below
headings on the first level, standard text below
first level as headings at headinglevel, below by indentation
A display is a partial in layouts/partials/pages, called once for each group. If you place a file layouts/partials/pages/mine.html into your site, you can use it with display=mine. The group heading is written by the shortcode, not by your display.
The partial is called with the following parameters:
Name
Value
page
the page whose pages are listed
group
the group, with its Key, its heading as Label, Fallback being true for the group of pages without a value, and its Pages
pages
the group’s pages, each with the Page itself, its display text as Label and its Level below the listed page, starting at 1
headinglevel
the heading level to start with; already one level below the group heading if the pages are grouped
class
the CSS classes to put on your outermost element
columns
the columns parameter value, as a number
description
the description parameter value, as true or false
breadcrumb
the breadcrumb parameter value, as true or false
image
the image parameter value, as true or false
cardtemplate
the cardtemplate parameter value
levels
the levels parameter value, as a number
hidden
the hidden parameter value, as true or false
params
the params parameter value, already turned into a dict
Remarks for the Cards Display
The cards display uses the cards shortcode to show each page as a card, using the default cardtemplate. With it the card will display
The cards display writes HTML. If you have goldmark.renderer.unsafe=false (which is the default if you don’t set it), you have to use {{< pages >}} instead of {{% pages %}}.
Own Card Templates
cardtemplate selects a card template as the template parameter of the cards shortcode does. Besides the card parameters, its params hold:
params.page: the displayed page
params.level: the displayed page’s level below the listed page
params.description: the description parameter value
every value of the params parameter of the pages shortcode; one with the same name as one above loses
Examples
The examples list the demo pages of the hidden Fruits section, which keeps them out of the menu.
Site Map
Every page of a section at any depth, hidden ones included, each with its description. The pages are ordered alphabetically by the title shown in the menu, as orderby is set; the weight the demo pages carry is ignored.
A heading for each chapter with its description, and the pages of the chapter listed below it. Unlike the site map above, it sets no orderby, so the pages come in the default order, the same as in the menu: by weight, which the demo pages deliberately set against the alphabet.
All pages at any depth in an A-Z index, grouped by the first letter of the title shown. Only the pages of the first level are grouped; the pages below them are listed under their parent, so Cranberry appears in the group of Berries rather than under C. Set flatten=true to group every page by its own letter.
{{%pagesgroupby="linktitle | left 1 | upper"headinglevel="4"levels="999"pageref="fruits"%}}
{{partial"shortcodes/pages.html"(dict"page"."groupby""linktitle | left 1 | upper""headinglevel""4""levels""999""pageref""fruits")}}
All pages the menu shows, from any depth, newest first, grouped by year and month with the newest month first. The pages below the hidden Citrus section are left out, just as in the menu.
{{%pagesdisplay="list"flatten="true"groupby="date | format '2006-01'"grouporder="desc"headinglevel="4"kind="leaf"levels="999"orderby="date desc"pageref="fruits"%}}
{{partial"shortcodes/pages.html"(dict"page"."display""list""flatten""true""groupby""date | format '2006-01'""grouporder""desc""headinglevel""4""kind""leaf""levels""999""orderby""date desc""pageref""fruits")}}
The pages by the month they were published in, pooled across years. The layout shows only the month’s name, so the groups come in calendar order, January to December, whatever the year of their pages.
{{%pagesflatten="true"groupby="date | format 'January'"headinglevel="4"kind="leaf"levels="999"pageref="fruits"%}}
{{partial"shortcodes/pages.html"(dict"page"."flatten""true""groupby""date | format 'January'""headinglevel""4""kind""leaf""levels""999""pageref""fruits")}}
Every page by its workflow status, hidden ones included, so drafts are easy to spot. With columns each group is spread over two columns in full width mode, keeping the long published group short.
The front matter holds the status as a plain key like draft. The headings show it translated by translate: with the prefix status- it looks up status-draft for draft and status-published for published in the site’s translation files. A status without a translation would show as it is. As the translation is only used as grouplabel, the groups keep the order of the keys. With translate in groupby instead, they would be ordered alphabetically by the translation of each language.
The pages grouped by a front matter parameter, the best ones first. The demo page without a flavor has no value for the expression and is put into a last group of its own, labelled Other. To give it a value of its own instead, like groupby: "params.flavor | coalesce 'neutral'", use coalesce; its group is then ordered among the others. default does the same, but also replaces a value of zero or false. Within each group the pages are ordered by priority descending and by title if they have the same priority.
The sections and pages of a chapter as cards with their description, ordered alphabetically by the title shown instead of by weight. Each demo page is a page bundle containing a featured.png, which Hugo selects as the image of its card.
All pages at any depth, hidden ones included, as cards in an A-Z index. Within a letter the cards are ordered alphabetically by the title shown instead of by weight.
{{<pagesdisplay="cards"flatten="true"groupby="linktitle | left 1 | upper"headinglevel="4"hidden="true"kind="leaf"levels="999"orderby="linktitle"pageref="fruits">}}
{{partial"shortcodes/pages.html"(dict"page"."display""cards""flatten""true""groupby""linktitle | left 1 | upper""headinglevel""4""hidden""true""kind""leaf""levels""999""orderby""linktitle""pageref""fruits")}}
Multilanguage features are not supported directly by the shortcode but rely on Hugo’s handling for resource translations applied when the theme iterates over all available resources.
Parameters
Name
Default
Notes
pageref
<empty>
A reference to the page bundle whose resources are listed, like /shortcodes/attachments or relative to the current page.
If set and it doesn’t resolve to a page, the build fails. If not set, the current page is used or, if called as partial, the page given in page.
style
transparent
The style scheme used for the box.
- by severity: caution, important, info, note, tip, warning - by brand color: primary, secondary, accent - by color: blue, cyan, green, grey, magenta, orange, red - by special color: default, transparent, code, link, action, inline
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: Resources
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 string filled with spaces)
expanded
<empty>
Whether to draw an expander and how the resource list is displayed.
- <empty>: no expander is drawn and the resource list is permanently shown - true: the expander is drawn and the resource list is initially shown - false: the expander is drawn and the resource list is initially hidden
sort
asc
Sorting the output in ascending or descending order.
For further examples for style, color, title and icon, see the callout shortcode documentation. The parameters are working the same way for both shortcodes, besides having different defaults.
SiteParam
The siteparam shortcode prints values of site-wide params contained in your hugo.toml.
Formatted parameter: A nested option <b>with</b> formatting
Tabs
The tabs shortcode displays arbitrary content in an unlimited number of tabs.
The AI native programming language.
echo"For guys who like to tinker."
For the connoisseur of programming.
Usage
{{<tabs>}}{{%tabtitle="Python Saying"%}}TheAInativeprogramminglanguage.{{%/tab%}}{{%tabtitle="Terminal Sourcecode"%}}```bash
echo "For guys who like to tinker."
```{{%/tab%}}{{%tabcolor="fuchsia"title="C Ramblings"%}}Fortheconnoisseurofprogramming.{{%/tab%}}{{%tabcolor="red"title="C++ Ramblings++"%}}Fortheguysthatcancopewithsyntax.{{%/tab%}}{{%tabtitle="C# ~~GC is cool~~"%}}Forguysthatneedtwodestructors.{{%/tab%}}{{</tabs>}}
{{partial"shortcodes/tabs.html"(dict"page"."content"(slice(dict"content""The AI native programming language.""title""Python Saying")(dict"content""```bash\necho \"For guys who like to tinker.\"\n```""title""Terminal Sourcecode")(dict"color""fuchsia""content""For the connoisseur of programming.""title""C Ramblings")(dict"color""red""content""For the guys that can cope with syntax.""title""C++ Ramblings++")(dict"content""For guys that need two destructors.""title""C# ~~GC is cool~~")))}}
Parameters
Name
Default
Notes
groupid
<random>
Arbitrary name of the group the tab view belongs to.
Tab views with the same groupid synchronize their selected tab. The tab selection is restored automatically based on the groupid for tab view. If the selected tab cannot be found in a tab group the first tab is selected instead.
This synchronization applies to the whole site!
style
<empty>
Sets a default value for every contained tab. Can be overridden by each tab. See the tab parameters for possible values.
color
<empty>
Sets a default value for every contained tab. Can be overridden by each tab. See the tab parameters for possible values.
Each tab of the view is defined with the tab shortcode.
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: caution, important, info, note, tip, warning - by brand color: primary, secondary, accent - by color: blue, cyan, green, grey, magenta, orange, red - by special color: default, transparent, code, link, action, inline
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 parameters for possible values.
{{partial"shortcodes/tabs.html"(dict"page"."content"(slice(dict"content""Simple text is possible here...""content"(partial"shortcodes/tabs.html"(dict"page"."content"(slice(dict"content""Python is **super** easy.\n\n- most of the time.\n- if you don't want to output unicode""title""python")(dict"content""Bash is for **hackers**.""title""bash"))"groupid""tabs-example-language"))"title""Text")(dict"color""darkorchid""content""...but no markdown""content"(partial"shortcodes/tabs.html"(dict"page"."content"(slice(dict"content""```python\nprint(\"Hello World!\")\n```""title""python")(dict"content""```bash\necho \"Hello World!\"\n```""title""bash"))"groupid""tabs-example-language"))"style""default""title""Code"))"groupid""main""icon""thumbtack""style""primary""title""Rationale")}}
{{partial"shortcodes/tab.html"(dict"page"."content""A tab cannot only contain code but arbitrary text. In this case text **and** code will get a margin.\n```python\nprintf(\"Hello World!\");\n```""title""_**Mixed**_")}}
A tab cannot only contain code but arbitrary text. In this case text and code will get a margin.
printf("Hello World!");
Icon with Hint
A tab showing nothing but an icon needs a hint: it is shown as a tooltip and is what assistive technology announces for the tab.
{{partial"shortcodes/tabs.html"(dict"page"."content"(slice(dict"content""Get the theme from its repository.""hint""Download""icon""download")(dict"content""Set the options in your `hugo.toml`.""hint""Configure""icon""gears")))}}
Get the theme from its repository.
Set the options in your hugo.toml.
Understanding style and color Behavior
The style parameter affects how the color parameter is applied.
{{<tabs>}}{{%tabstyle="blue"title="just colored style"%}}The`style`parameterissettoacolorstyle.Thiswillsetthebackgroundtoalighterversionofthechosenstylecolorasconfiguredinyourthemevariant.{{%/tab%}}{{%tabcolor="blue"title="just color"%}}Onlythe`color`parameterisset.ThiswillsetthebackgroundtoalighterversionofthechosenCSScolorvalue.{{%/tab%}}{{%tabcolor="blue"style="default"title="default style and color"%}}The`style`parameteraffectshowthe`color`parameterisapplied.The`default`stylewillsetthebackgroundtoyour`--MAIN-BG-color`asconfiguredforyourthemevariantresemblingthedefaultstylebutwithdifferentcolor.{{%/tab%}}{{%tabstyle="info"title="just severity style"%}}The`style`parameterissettoaseveritystyle.Thiswillsetthebackgroundtoalighterversionofthechosenstylecolorasconfiguredinyourthemevariantandalsoaffectsthechosenicon.{{%/tab%}}{{%tabcolor="blue"style="info"title="severity style and color"%}}The`style`parameteraffectshowthe`color`parameterisapplied.ThiswillsetthebackgroundtoalighterversionofthechosenCSScolorvalueandalsoaffectsthechosenicon.{{%/tab%}}{{</tabs>}}
{{partial"shortcodes/tabs.html"(dict"page"."content"(slice(dict"content""The `style` parameter is set to a color style.\n\nThis will set the background to a lighter version of the chosen style color as configured in your theme variant.""style""blue""title""just colored style")(dict"color""blue""content""Only the `color` parameter is set.\n\nThis will set the background to a lighter version of the chosen CSS color value.""title""just color")(dict"color""blue""content""The `style` parameter affects how the `color` parameter is applied.\n\nThe `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.""style""default""title""default style and color")(dict"content""The `style` parameter is set to a severity style.\n\nThis 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.""style""info""title""just severity style")(dict"color""blue""content""The `style` parameter affects how the `color` parameter is applied.\n\nThis will set the background to a lighter version of the chosen CSS color value and also affects the chosen icon.""style""info""title""severity style and color")))}}
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.
Tree
The tree shortcode displays text as a tree with configurable icons and colors.
{{partial"shortcodes/tree.html"(dict"page"."content""- home | folder\r\n - [.config](http://example.com) | folder\r\n - My Documents | folder | magic\r\n - home.php | fa-fw fab fa-php | #888cc4")}}
Markdown codefence syntax is widely available in other Markdown parsers like GitHub and therefore is the recommended syntax for generating portable Markdown.
Parameters
Name
Default
Notes
<content>
<empty>
Your list as Markdown or from your favorite tree commandline tool.
Item Syntax
<NAME> [ |<ICON> [ |<COLOR> ] ]
The NAME can be followed by an optional pipe (|) to define an ICON and further optional pipe to define the icon’s COLOR.
ICON: Font Awesome icon name set to the left of the NAME. If you give a single string, it is selected from Font Awesome’s solid icons. If you want to use a different set, you have to give the complete styles. See above example for the home.php.
COLOR: The CSS color value to be used. If not set, the primary color will be used.
You can also set a style value known from other shortcodes.
by severity: caution, important, info, note, tip, warning
by brand color: primary, secondary, accent
by color: blue, cyan, green, grey, magenta, orange, red
by special color: default, transparent, code, link, action, inline
If a style and a named HTML color have the same name, the style color will be used.
Examples
tree Command Output
Use the tree command of your favorite operating system and dump it right into the shortcode. Note, that the directory marker (here C:.) is removed if present.
