Cap'n Hugo uses Marrrkdown as its rrrambl'n format. However, there be a lot o' th'ns that Marrrkdown doesn’t support well. T' overcome those limitat'ns, Cap'n Hugo created th' concept o' shorrrtcodes.
Th' badge shortcode displays colorful markers 'n yer text wit' optional ay'cons.
ImportantVersion6.6.6Captain AhoiNewAwesome
Usage
{{%badge%}}Important{{%/badge%}}{{%badgestyle="primary"title="Version"%}}6.6.6{{%/badge%}}{{%badgeay'con="angle-double-up"style="red"%}}Captain{{%/badge%}}{{%badgestyle="info"%}}New{{%/badge%}}{{%badgecolor="fuchsia"ay'con="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
Th' style scheme used fer th' badge.
- by severity: caution, important, info, note, tip, warning - by brand color: primary, secondary, accent - by color: blue, cyan, green, grey, magenta, orange, purple, red, yellow - by special color: default, transparent, code, link, action, inline
Th' CSS color value t' be used. If not set, th' chosen color depends on th' style. Any given value will overwrite th' default.
- fer severity styles: a nice match'n color fer th' severity - fer all other styles: th' correspond'n color
title
see notes
Arbitrary text fer th' badge title. Depend'n on th' style there may be a default title. Any given value will overwrite th' default.
- fer severity styles: th' match'n title fer th' severity - fer all other styles: <empty>
If ye want no title fer a severity style, ye have t' set this parameter t' " " (a non empty str'n filled wit' spaces)
ay'con
see notes
Font Awesome ay'con name set t' th' left o' th' title. Depend'n on th' style there may be a default ay'con. Any given value will overwrite th' default.
- fer severity styles: a nice match'n ay'con fer th' severity - fer all other styles: <empty>
If ye want no ay'con fer a severity style, ye have t' set this parameter t' " " (a non empty str'n filled wit' spaces)
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
Th' button shortcode displays a click'ble button wit' adjustable color, title an' ay'con.
Either th' destinat'n URL fer th' button or JavaScript code t' be executed on click. If this parameter be not set, th' button will do noth'n but be still displayed as click'ble.
- if start'n wit' javascript: all follow'n text will be executed 'n yer browser - every other str'n will be interpreted as URL, ye can use link effects as well.
action
<empty>
Name o' an action executed by yer own script on click, without inline JavaScript. Use this instead o' a JavaScript href if yer ship uses a strict Rrrambl'n Security Policy. See example.
type
see notes
Th' button type if href be JavaScript or action be set. Otherwise th' parameter be not used. If th' parameter be not given it defaults t' button.
istoggle
false
When true, th' button announces t' assistive technology that it shows an' hides someth'n. It starts as hidden an' th' theme changes th' state wit' each click. Only used if href be JavaScript or action be set. See example.
borderless
false
When true, no border will be shown around th' button.
hint
<empty>
Tooltip fer th' button.
style
transparent
Th' style scheme used fer th' button.
- by severity: caution, important, info, note, tip, warning - by brand color: primary, secondary, accent - by color: blue, cyan, green, grey, magenta, orange, purple, red, yellow - by special color: default, transparent, code, link, action, inline
Th' CSS color value t' be used. If not set, th' chosen color depends on th' style. Any given value will overwrite th' default.
- fer severity styles: a nice match'n color fer th' severity - fer all other styles: th' correspond'n color
ay'con
see notes
Font Awesome ay'con name set t' th' left o' th' title. Depend'n on th' style there may be a default ay'con. Any given value will overwrite th' default.
- fer severity styles: a nice match'n ay'con fer th' severity - fer all other styles: <empty>
If ye want no ay'con fer a severity style, ye have t' set this parameter t' " " (a non empty str'n filled wit' spaces)
iconposit'n
left
Places th' ay'con t' th' left or right o' th' title.
<content>
see notes
Arbitrary text fer th' button title. Depend'n on th' style there may be a default title. Any given value will overwrite th' default.
- fer severity styles: th' match'n title fer th' severity - fer all other styles: <empty>
If ye want no title fer a severity style, ye have t' set this parameter t' " " (a non empty str'n filled wit' spaces)
{{partial"shortcodes/button.html"(dict"page"."content""Shout it out""href""javascript:alert('Hello world!');this.blur();""icon""bullhorn""style""primary")}}
Button wit' Own Act'n
Th' button be written wit' a data-button-action attribute. Handle it 'n yer assets/js/custom.js, which th' theme loads on every plank.
If yer button shows an' hides someth'n, set istoggle. Th' button be written wit' an aria-expanded attribute tell'n assistive technology whether th' th'n be shown, an' th' theme flips it wit' each click.
{{%calloutay'con="skull-crossbones"style="primary"title="There may be pirates"%}}Itbeallaboutth'boxes.{{%/callout%}}
{{%callout"primary""There may be pirates""skull-crossbones"%}}Itbeallaboutth'boxes.{{%/callout%}}
{{partial"shortcodes/callout.html"(dict"page"."content""It be all about th' boxes.""icon""skull-crossbones""style""primary""title""There may be pirates")}}
If ye want t' display a transparent expand'ble box without any border, ye can also use th' details shortcode.
Parameters
Name
Posit'n
Default
Notes
groupid
<empty>
Arbitrary name o' th' group th' box belongs t'.
Expand'ble boxes wit' th' same groupid synchr'nize their open state.
style
1
default
Th' style scheme used fer th' box.
- by severity: caution, important, info, note, tip, warning - by brand color: primary, secondary, accent - by color: blue, cyan, green, grey, magenta, orange, purple, red, yellow - by special color: default, transparent, code, link, action, inline
Th' CSS color value t' be used. If not set, th' chosen color depends on th' style. Any given value will overwrite th' default.
- fer severity styles: a nice match'n color fer th' severity - fer all other styles: th' correspond'n color
title
2
see notes
Arbitrary text fer th' box title. Depend'n on th' style there may be a default title. Any given value will overwrite th' default.
- fer severity styles: th' match'n title fer th' severity - fer all other styles: <empty>
If ye want no title fer a severity style, ye have t' set this parameter t' " " (a non empty str'n filled wit' spaces)
ay'con
3
see notes
Font Awesome ay'con name set t' th' left o' th' title. Depend'n on th' style there may be a default ay'con. Any given value will overwrite th' default.
- fer severity styles: a nice match'n ay'con fer th' severity - fer all other styles: <empty>
If ye want no ay'con fer a severity style, ye have t' set this parameter t' " " (a non empty str'n filled wit' spaces)
expanded
<empty>
Whether t' draw an expander an' how th' rrrambl'n be displayed.
- <empty>: no expander be drawn an' th' rrrambl'n be permanently shown - true: th' expander be drawn an' th' rrrambl'n be initially shown - false: th' expander be drawn an' th' rrrambl'n be initially hidden
hint
<empty>
Tooltip fer th' title o' th' box.
<content>
<empty>
Arbitrary text t' be displayed 'n box.
Sett'ns
Defin'n own Styles
Opt'n Besides th' predefined style values from above, ye be able t' define yer own.
This must match th' style parameter used 'n a shortcode.
style
<empty>
If ye define this optional parameter, this be whar' default values fer title, ay'con an' color be taken from if style exists beforehand. Ye can reference predefined styles as also yer own styles.
title
<empty>
Th' default title used. If ye have set style an' don’t want any title at all, ye have t' set this parameter t' " “. See th' parameter i18n if ye use multiple languages 'n yer ship.
i18n
<empty>
If no title be given but i18n be set, th' title will be taken from th' translat'n files by that key.
ay'con
<empty>
Th' default ay'con used. If ye have set style an' don’t want any ay'con at all, ye have t' set this parameter t' " “.
color
<empty>
Th' default color used. If ye have set style an' don’t want any color at all, ye have t' set this parameter t' " “.
Th' first line o' th' Marrrkdown rules only has room fer style, title an' expanded. Th' parameters color, ay'con, groupid an' hint be written as Marrrkdown attributes 'n a line follow'n th' callout instead, so Hugo’s block attributes be required if ye use one o' them 'n Marrrkdown rules.
Without it, Cap'n Hugo doesn’t recognize th' line, so it be printed as text below th' box an' th' parameters be ignored. Th' shortcode an' partial rules work regardless.
{{partial"shortcodes/callout.html"(dict"page"."content""Advises about risks or negative outcomes o' certain actions.""style""caution")}}{{partial"shortcodes/callout.html"(dict"page"."content""Key informat'n users need t' know t' achieve their goal.""style""important")}}{{partial"shortcodes/callout.html"(dict"page"."content""Informat'n that users <ins>_might_</ins> find interest'n.""style""info")}}{{partial"shortcodes/callout.html"(dict"page"."content""Useful informat'n that users should know, even when skimm'n rrrambl'n.""style""note")}}{{partial"shortcodes/callout.html"(dict"page"."content""Helpful advice fer do'n th'ns better or more easily.""style""tip")}}{{partial"shortcodes/callout.html"(dict"page"."content""Urgent info that needs immediate user attent'n t' avoid problems.""style""warning")}}
Caut'n
Advises about risks or negative outcomes o' certain actions.
Important
Key informat'n users need t' know t' achieve their goal.
Ahoi
Informat'n that users might find interest'n.
Avast
Useful informat'n that users should know, even when skimm'n rrrambl'n.
Smarrrt Arrrse
Helpful advice fer do'n th'ns better or more easily.
Arrr
Urgent info that needs immediate user attent'n t' 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 vis'ble 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 o' topbar buttons""icon""skull-crossbones""style""link""title""Link")}}{{partial"shortcodes/callout.html"(dict"page"."content""Style o' action buttons like Merrrmaid zoom or block code copy-to-clipboard""icon""skull-crossbones""style""action""title""Action")}}{{partial"shortcodes/callout.html"(dict"page"."content""Style o' inline buttons like inline code copy-to-clipboard""icon""skull-crossbones""style""inline""title""Inline")}}
Default
Just some default color.
Transparent
No vis'ble borders.
Code
Colored like a code fence.
Link
Style o' topbar buttons
Act'n
Style o' action buttons like Merrrmaid zoom or block code copy-to-clipboard
Inline
Style o' inline buttons like inline code copy-to-clipboard
Various Features
Wit' User-Defined Color, Font Awesome Brand Ay'con an' Marrrkdown 'n Title an' Rrrambl'n
>[!default]**Cap'n Hugo**be_awesome_>{{%include"shortcodes/include/INCLUDE_ME.md"%}}{color="fuchsia"ay'con="fa-fw fab fa-hackerrank"}
{{%calloutcolor="fuchsia"ay'con="fa-fw fab fa-hackerrank"title="**Hugo** be _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** be _awesome_")}}
th' possibilities be endless (almost - includ'n other shorrrtcodes may or may not work) (almost - includ'n other shorrrtcodes may or may not work)
Et Cetera (English: /ɛtˈsɛtərə/), abbreviated t' etc., etc, et cet., be a Latin expression that be used 'n English t' mean “and other similar things”, or “and so forth” ↩︎
Expand'ble Rrrambl'n Area wit' groupid
If ye give multiple expand'ble boxes th' same groupid, at most one will be open at any given time. If ye open one o' th' boxes, all other boxes o' th' same group will close.
{{partial"shortcodes/callout.html"(dict"page"."content""Built wit' Cap'n Hugo.""hint""Hugo be a static ship generator""style""tip")}}
Smarrrt Arrrse
Built wit' Cap'n Hugo.
No Rrrambl'n 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 fold'ble?"%}}Yes!Inafold'blecallout,th'contentsbehiddenwhenth'calloutbecollapsed{{%/callout%}}{{%calloutexpanded="true"style="note"title="Are callouts fold'ble?"%}}Yes!Inafold'blecallout,th'contentsbehiddenwhenth'calloutbecollapsed{{%/callout%}}{{%calloutstyle="info"title="Can callouts be nested?"%}}>[!important]Yes!,theycan.>>[!tip]Yecanevenusemultiplelayerso'nest'n.{{%/callout%}}
{{%callout"caution""Callouts can have custom titles"%}}Likethisone.{{%/callout%}}{{%callout"caution""Title-only callout"%}}{{%/callout%}}{{%callout"note""Are callouts fold'ble?"%}}Yes!Inafold'blecallout,th'contentsbehiddenwhenth'calloutbecollapsed{{%/callout%}}{{%callout"note""Are callouts fold'ble?"%}}Yes!Inafold'blecallout,th'contentsbehiddenwhenth'calloutbecollapsed{{%/callout%}}{{%callout"info""Can callouts be nested?"%}}>[!important]Yes!,theycan.>>[!tip]Yecanevenusemultiplelayerso'nest'n.{{%/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 fold'ble callout, th' contents be hidden when th' callout be collapsed""expanded""false""style""note""title""Are callouts fold'ble?")}}{{partial"shortcodes/callout.html"(dict"page"."content""Yes! In a fold'ble callout, th' contents be hidden when th' callout be collapsed""expanded""true""style""note""title""Are callouts fold'ble?")}}{{partial"shortcodes/callout.html"(dict"page"."content""> [!important] Yes!, they can.\n> > [!tip] Ye can even use multiple layers o' nest'n.""style""info""title""Can callouts be nested?")}}
Callouts can have custom titles
Like this one.
Title-only callout
Be callouts fold'ble?
Yes! In a fold'ble callout, th' contents be hidden when th' callout be collapsed
Be callouts fold'ble?
Yes! In a fold'ble callout, th' contents be hidden when th' callout be collapsed
Each card o' th' set be defined wit' th' card shortcode.
Name
Default
Notes
href
<empty>
Either th' destinat'n URL fer th' card or JavaScript code t' be executed on click. If this parameter be set, th' card will hover on mouse over.
- if start'n wit' javascript: all follow'n text will be executed 'n yer browser - every other str'n will be interpreted as URL, ye can use link effects as well.
action
<empty>
Name o' an action executed by yer own script on click, without inline JavaScript. Use this instead o' a JavaScript href if yer ship uses a strict Rrrambl'n Security Policy. If this parameter be set, th' card will hover on mouse over. See example.
image
<empty>
URL t' an image t' be displayed at th' start o' th' card.
imagealt
<empty>
Text alternative fer th' image, announced by a screen reader 'n place o' th' image.
Set it if th' card shows noth'n but its image, as th' image be then th' only th'n left t' name th' card. Without it such a card falls back t' th' title o' th' plank its href leads t', or t' th' href itself.
Leave it empty if th' card also shows a title. Th' title names th' card, so th' image beside it be marked as decorative wit' an empty alt attribute.
title
<empty>
Arbitrary title fer th' card.
template
default
Th' template t' be used t' display th' card. Overrides th' template o' th' set.
- default: Th' standard layout - debug: A debug layout help'n ye 'n development
If ye have advanced requirements t' display yer cards, ye can place a card layout partial into layouts/partials/card that will be used fer each single card.
For example, if ye want t' see debug output display'n th' parameter th' partial receives, ye could set template=debug which will cause th' partial layouts/partials/cards/debug.html t' be called. Th' debug card template be shipped wit' th' theme.
A card template will be called wit' all th' card parameters. href an' image be transformed into a form ready t' be consumed.
Examples
Lots o' Cards
If only an image be displayed, th' full card will be used. As no title be left t' name th' card, describe th' image wit' th' imagealt parameter.
{{<cards>}}{{%cardhref="/images/magic.gif?download"image="/images/magic.gif"title="Everything"%}}Image,title,textan'href.Yecanalsouseimageeffects'nyer`href`.Thiscardwilldownloadth'image.{{%/card%}}{{%cardtitle="Title an' Text"%}}Justatitlean'atext.Yecanuseany**Marrrkdown**'nth'text{{%/card%}}{{%cardtitle="Title Only"%}}{{%/card%}}{{%cardimage="/images/magic.gif"title="Image an' Title"%}}{{%/card%}}{{%cardimage="/images/magic.gif"%}}Imagean'atext{{%/card%}}{{%card%}}Textonly```c
printf("Hello Code!");
```{{%/card%}}{{%cardhref="/images/magic.gif?download"image="/images/magic.gif"imagealt="A top hat wit' a rabbit peek'n out"%}}{{%/card%}}{{</cards>}}
{{partial"shortcodes/cards.html"(dict"page"."content"(slice(dict"content""Image, title, text an' href.\n\nYou can also use image effects 'n yer `href`. This card will download th' image.""href""/images/magic.gif?download""image""/images/magic.gif""title""Everything")(dict"content""Just a title an' a text. Ye can use any **Markdown** 'n th' text""title""Title an' Text")(dict"content""""title""Title Only")(dict"content""""image""/images/magic.gif""title""Image an' Title")(dict"content""Image an' 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 wit' a rabbit peek'n out")))}}
{{partial"shortcodes/cards.html"(dict"page"."content"(slice(dict"content""For th' connoisseur o' programm'n.""params""{\"blub\":\"bla\"}""title""C")(dict"content""For th' guys that can cope wit' rules.""title""C++")(dict"content""For guys that need two destructors.""title""C#"))"template""debug")}}
C
All Parameter
{"action":"","color":"","content":"For th' connoisseur o' programm'n.","href":"","hrefattributes":{},"icon":"","image":null,"imagealt":"","onclick":"","page":"/shortcodes/cards","params":{"blub":"bla"},"style":"filled","template":"debug","title":"C"}
C++
All Parameter
{"action":"","color":"","content":"For th' guys that can cope wit' rules.","href":"","hrefattributes":{},"icon":"","image":null,"imagealt":"","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":"","onclick":"","page":"/shortcodes/cards","params":null,"style":"filled","template":"debug","title":"C#"}
Card wit' Own Act'n
Th' card be written wit' a data-button-action attribute. Handle it 'n yer assets/js/custom.js, which th' theme loads on every plank.
{{%cardaction="shout"title="Shout it out"%}}Clickt'greetth'world{{%/card%}}
{{partial"shortcodes/card.html"(dict"page"."action""shout""content""Click t' greet th' world""title""Shout it out")}}
This shortcode be fully compatable wit' Hugo’s details shortcode but offers some extensions.
Marrrkdown callout rules be avail'ble 'n other Marrrkdown parsers like Obsidian an' therefore be th' recommended rules fer generat'n portable Marrrkdown.
In Marrrkdown rules th' section be a callout o' th' style details. Its first line takes summary an' open, while name an' title be written as th' Marrrkdown attributesgroupid an' hint. class an' raw be not avail'ble.
Th' callout shortcode be also cap'ble o' display'n expandable/collaps'ble sections o' text but wit' additional parameters fer color an' additional ay'cons.
Parameters
Name
Default
Notes
summary
"Details"
Arbitrary text t' appear next t' th' expand/collapse ay'con.
open
false
How th' rrrambl'n be displayed.
- true: th' rrrambl'n be initially shown - false: th' rrrambl'n be initially hidden
name
<empty>
Arbitrary name o' th' group th' section belongs t'.
O' all sections wit' th' same name, at most one be open at any given time.
class
<empty>
CSS classes t' be added t' th' section.
title
<empty>
Arbitrary text t' be displayed as a tooltip fer th' summary.
raw
false
Extension. How th' rrrambl'n be processed.
- false: th' rrrambl'n be rendered as Marrrkdown - true: th' rrrambl'n be written as it be, see below
<content>
<empty>
Arbitrary text t' be displayed on expand.
Examples
All Defaults
>[!details]-Details>Yes,yedidit!
{{<details>}}Yes,yedidit!{{</details>}}
{{partial"shortcodes/details.html"(dict"page"."content""Yes, ye did it!")}}
{{partial"shortcodes/details.html"(dict"page"."content""No need t' press ye!""open""true""summary""Expand me...")}}
Expand me…
No need t' press ye!
Arbitrary Text
>[!details]-Showmealmost**endless**possibilities>Yecanaddstandardmarkdownrules:>>-multipleparagraphs>-bulletpointlists>-_emphasized_,**bold**an'even**_boldemphasized_**text>-[links](https://example.com)>-etc.>>```plaintext
> ...and even source code
> ```>>>th'possibilitiesbeendless(almost-includ'nothershorrrtcodesmayormaynotwork)
{{<detailssummary="Show me almost **endless** possibilities">}}Yecanaddstandardmarkdownrules:-multipleparagraphs-bulletpointlists-_emphasized_,**bold**an'even**_boldemphasized_**text-[links](https://example.com)-etc.```plaintext
...and even source code
```>th'possibilitiesbeendless(almost-includ'nothershorrrtcodesmayormaynotwork){{</details>}}
{{partial"shortcodes/details.html"(dict"page"."content""You can add standard markdown rules:\n\n- multiple paragraphs\n- bullet point lists\n- _emphasized_, **bold** an' even **_bold emphasized_** text\n- [links](https://example.com)\n- etc.\n\n```plaintext\n...and even source code\n```\n\n> th' possibilities be endless (almost - includ'n other shorrrtcodes may or may not work)""summary""Show me almost **endless** possibilities")}}
th' possibilities be endless (almost - includ'n other shorrrtcodes may or may not work)
Grouped Sect'ns
If ye give multiple sections th' same name, they behave like an accordion: at most one will be open at any given time. If ye open one o' th' sections, all other sections o' th' same group will close.
{{partial"shortcodes/details.html"(dict"page"."content""No need t' press ye!""name""details-toggle""open""true""summary""Expand me...")}}{{partial"shortcodes/details.html"(dict"page"."content""Thank ye!""name""details-toggle""summary""Expand me...")}}
Expand me…
No need t' press ye!
Expand me…
Thank ye!
Raw Rrrambl'n
Th' rrrambl'n be rendered as Marrrkdown on its own, apart from th' rest o' yer plank. This has consequences:
A footnote defined inside o' th' rrrambl'n be listed inside o' th' section instead o' at th' end o' yer plank, an' a footnote defined outside o' it can not be referenced.
A head'n inside o' th' rrrambl'n doesn’t show up 'n th' table o' contents.
Wit' marrrkup.goldmark.renderer.unsafe set t' false (which be th' default if ye don’t set it), HTML inside o' th' rrrambl'n be removed. This includes th' HTML written by other shorrrtcodes ye call 'n there.
If th' rrrambl'n be HTML already or contains other shorrrtcodes, set raw=true. Th' rrrambl'n be then written as it be an' no Marrrkdown be rendered.
Call th' shortcode wit' {{< details >}} as shown on this plank. This works regardless o' yer configurat'n.
A call wit' {{% details %}} writes its HTML into th' Marrrkdown o' yer plank. Wit' marrrkup.goldmark.renderer.unsafe set t' false th' whole section be removed.
Highlight
Th' highlight shortcode renders yer code wit' a rules highlighter.
This shortcode be fully compatable wit' Hugo’s highlight shortcode but offers some extensions.
It be called interchangeably 'n th' same way as Hugo’s own shortcode by provid'n positional parameters or simply by us'n Marrrkdown codefences.
Ye be free t' also call this shortcode from yer own partials. In this case it resembles Hugo’s highlight funct'n rules if ye call it us'n compatibility rules.
Marrrkdown codefence rules be widely avail'ble 'n other Marrrkdown parsers like GitHub an' therefore be th' recommended rules fer generat'n portable Marrrkdown.
Th' tab shortcode be also cap'ble o' display'n code but wit' limited options.
Parameters
Name
Posit'n
Default
Notes
type
1
<empty>
Th' language o' th' code t' highlight. Choose from one o' th' supported languages. Case-insensitive.
title
<empty>
Extension. Arbitrary title fer code. This displays th' code like a single tab if hl_inline=false (which be Hugo’s default).
wrap
see notes
Extension. When true th' rrrambl'n may wrap on long lines otherwise it will be scroll'ble.
Th' default value can be set 'n yer project configurat'n an' overwritten via front matter. See below.
options
2
<empty>
An optional, comma-separated list o' zero or more Cap'n Hugo supported options as well as extension parameter from this table.
Ye can configure th' color style used fer code blocks 'n yer color variants stylesheet file us'n th' --CODE-theme vari'ble. This requires further configurat'n as described 'n th' above link.
Examples
Line Numbers wit' Start'n Offset
As mentioned above, line numbers 'n a table layout will shift if code be wrapp'n, so better use inline. T' make th'ns easier fer ye, set marrrkup.highlight.lineNumbersInT'ble t' false 'n yer project configurat'n an' add lineNos=true when call'n th' shortcode instead o' th' specific values table or inline.
```py {lineNoStart="666" lineNos="true"}
# th' hardest part be t' start writ'n code; here's a kickstart; just copy an' paste this; it's free; th' next lines will cost ye serious credits
print("Hello")
print(" ")
print("World")
print("!")
```
{{partial"shortcodes/highlight.html"(dict"page"."content""# th' hardest part be t' start writ'n code; here's a kickstart; just copy an' paste this; it's free; th' next lines will cost ye serious credits\nprint(\"Hello\")\nprint(\" \")\nprint(\"World\")\nprint(\"!\")""lineNoStart""666""lineNos""true""type""py")}}
{{partial"shortcodes/highlight.html"(dict"page"."content""# th' hardest part be t' start writ'n code; here's a kickstart; just copy an' paste this; it's free; th' next lines will cost ye serious credits\nprint(\"Hello\")\nprint(\" \")\nprint(\"World\")\nprint(\"!\")""type""py""options""lineNoStart=666,lineNos=true")}}
666# th' hardest part be t' start writ'n code; here's a kickstart; just copy an' paste this; it's free; th' next lines will cost ye serious credits667print("Hello")668print(" ")669print("World")670print("!")
Wit' 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!")
Wit' Wrap
```py {hl_lines="2" wrap="true"}
# Quicksort Python One-liner
lambda L: [] if L==[] else qsort([x fer x 'n L[1:] if x< L[0]]) + L[0:1] + qsort([x fer x 'n 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 fer x 'n L[1:] if x< L[0]]) + L[0:1] + qsort([x fer x 'n 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 fer x 'n L[1:] if x< L[0]]) + L[0:1] + qsort([x fer x 'n L[1:] if x>=L[0]])\n# Some more stuff""type""py""options""hl_lines=2,wrap=true")}}
# Quicksort Python One-linerlambdaL:[]ifL==[]elseqsort([xferx'nL[1:]ifx<L[0]])+L[0:1]+qsort([xferx'nL[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 fer x 'n L[1:] if x< L[0]]) + L[0:1] + qsort([x fer x 'n 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 fer x 'n L[1:] if x< L[0]]) + L[0:1] + qsort([x fer x 'n 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 fer x 'n L[1:] if x< L[0]]) + L[0:1] + qsort([x fer x 'n L[1:] if x>=L[0]])\n# Some more stuff""type""py""options""hl_lines=2,wrap=false")}}
# Quicksort Python One-linerlambdaL:[]ifL==[]elseqsort([xferx'nL[1:]ifx<L[0]])+L[0:1]+qsort([xferx'nL[1:]ifx>=L[0]])# Some more stuff
Icon
Th' ay'con shortcode displays ay'cons us'n th' Font Awesome library.
Th' CSS color value t' be used. If not set, th' chosen color depends on th' style. Any given value will overwrite th' default.
- fer severity styles: a nice match'n color fer th' severity - fer all other styles: th' correspond'n color
Find'n an ay'con
Browse through th' avail'ble ay'cons 'n th' Font Awesome Gallery. Notice that th' free filter be enabled, as only th' free ay'cons be avail'ble by default.
Once on th' Font Awesome plank fer a specific ay'con, fer example th' plank fer th' heart, copy th' ay'con name an' paste into th' Marrrkdown rrrambl'n.
Customiz'n Ay'cons
Font Awesome provides many ways t' modify th' ay'con
Change color (by default th' ay'con will inherit th' parent color)
Builtwit'{{%ay'conay'con="heart"%}}byRelearrrnan'Cap'n Hugo
Builtwit'{{%ay'con"heart"%}}byRelearrrnan'Cap'n Hugo
Builtwit'{{partial"shortcodes/icon.html"(dict"page"."icon""heart")}}byRelearrrnan'Cap'n Hugo
Built wit' by Relearrrn an' Cap'n Hugo
Wit' Color
Builtwit'{{%ay'conay'con="heart"style="red"%}}byRelearrrnan'Cap'n Hugo
Builtwit'{{%ay'con"heart""red"%}}byRelearrrnan'Cap'n Hugo
Builtwit'{{partial"shortcodes/icon.html"(dict"page"."icon""heart""style""red")}}byRelearrrnan'Cap'n Hugo
Built wit' by Relearrrn an' Cap'n Hugo
Advanced HTML Usage
While th' shortcode simplifies us'n standard ay'cons, th' ay'con customizat'n an' other advanced features o' th' Font Awesome library require ye t' use HTML directly. Paste th' <i> HTML into marrrkup, an' Font Awesome will board th' relevant ay'con.
Built wit' <iclass="fas fa-heart"></i> by Relearrrn an' Cap'n Hugo
Built wit' by Relearrrn an' Cap'n Hugo
T' use these native HTML elements 'n yer Marrrkdown, add this 'n yer project configurat'n:
When true an' th' included file contains head'ns, th' first head'n will be hidden. This comes 'n handy, eg. if ye include otherwise standalone Marrrkdown files.
Sett'ns
Enabl'n Link Warn'ns
Opt'nFront Matter Ye can use include.errorlevel t' control what should happen if a local link cannot be resolved t' a resource.
If not set or empty, any unresolved link be written as given into th' result'n output. If set t' warning th' same happens an' an additional warning be printed 'n th' built console. If set t' error an error message be printed an' th' build be aborted.
Please note that this cannot resolve files inside o' yer static directory. Th' file must be a resource o' th' plank or th' ship.
th' possibilities be endless (almost - includ'n other shorrrtcodes may or may not work) (almost - includ'n other shorrrtcodes may or may not work)
Et Cetera (English: /ɛtˈsɛtərə/), abbreviated t' etc., etc, et cet., be a Latin expression that be used 'n English t' mean “and other similar things”, or “and so forth” ↩︎
Math
Th' math shortcode renders complex math an' chemical formulae us'n Hugo’s built-in KaTeX.
Ye can also use pure Marrrkdown fer writ'n simple math expressions.
Delimiters around yer formulae require th' Passthrough configurat'n, as th' theme finds yer formulae by them. Passthrough rules itself has limited features as it does not provide any o' th' below parameters besides rrrambl'n. Nevertheless, it be widely avail'ble 'n other Marrrkdown parsers like GitHub an' therefore be th' recommended rules fer generat'n portable Marrrkdown.
Parameters
Name
Default
Notes
align
center
Th' vertical alignment.
Allowed values be left, center or right.
<content>
<empty>
Yer formulae.
Enclose each formula 'n th' block or inline delimiters o' yer Passthrough configurat'n. Text outside o' them be written as Marrrkdown.
Without any delimiters, th' whole rrrambl'n be one formula displayed as a block.
Sett'ns
Output o' th' Formulae
Opt'nFront Matter By default, formulae be written as MathML, which every current browser displays without any stylesheet or font o' th' theme. Th' display quality depends on th' browser an' th' math fonts installed on yer reader’s system.
If ye want yer formulae t' look th' same 'n every browser, set math.output t' htmlAndMathml. Th' theme then links th' KaTeX stylesheet an' fonts t' every plank contain'n math. Th' MathML be kept fer screen readers. Th' value html omits it.
params:math:output:htmlAndMathml
[params][params.math]output='htmlAndMathml'
{"params":{"math":{"output":"htmlAndMathml"}}}
Provid'n Opt'ns fer KaTeX
Opt'nFront Matter Besides output, ye can set every option o' Hugo’s transform.ToMath funct'n 'n math, fer example yer own macros.
Each option o' yer page’s front matter overwrites th' option o' th' same name o' yer configurat'n options.
A formula that KaTeX can not render be written as its source an' reported as a warning 'n yer build.
Force Load'n o' th' KaTeX Stylesheet
Opt'nFront Matter If yer output needs th' KaTeX stylesheet, it will be linked t' yer plank if th' plank contains a math shortcode, Marrrkdown codefence, Passthrough rules or th' partial be called from yer templates.
If ye write KaTeX’s HTML by other means, ye can force link'n th' stylesheet by sett'n math.force t' true. If a formula was rendered, th' option has no effect.
Sett'n math t' true does th' same but can’t be combined wit' other math.* options.
params:math:force:true
[params][params.math]force=true
{"params":{"math":{"force":true}}}
Passthrough Configurat'n
Th' theme finds yer formulae by th' delimiters o' Hugo’s Passthrough configurat'n, so it be required if ye use delimiters 'n any rules. It also lets ye write math without enclos'n it 'n a shortcode or Marrrkdown codefence.
Fello' pirrrates, grog made us dizzy! Be awarrre some stuff may look weird in this trrranslat'n. Like seeing Merrrmaids and stuff.
Th' mermaid shortcode generates diagrams an' flowcharts from text us'n th' Merrrmaid library.
graph LR;
If --> Then
Then --> Else
Every graph has a button t' show it 'n a lightbox. Press th' button again, click beside th' graph, press ESC or go back 'n yer browser t' return t' th' plank. Th' enlarged graph has its own URL, so ye can share a link t' it, like ye can fer an enlarged image. In th' lightbox, a graph be panned an' zoomed th' same way as on th' plank.
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
Th' vertical alignment.
Allowed values be left, center or right.
zoom
see notes
Whether th' graph be pan- an' zoom'ble.
If not set th' value be determined by th' mermaidZoom sett'n o' yer configurat'ns options or th' planks front matter or false if not set at all.
- false: no pan or zoom - true: pan an' zoom active
<content>
<empty>
Yer Merrrmaid graph.
Sett'ns
Configur'n Pan an' Zoom
Opt'nFront Matter Th' generated graphs can be panned by dragg'n them an' zoomed by us'n th' mousewheel. On mobile devices ye can use finger gestures. Wit' th' keyboard, a focused graph be panned by th' cursor keys an' zoomed by + an' -, as listed wit' th' other keyboard shortcuts.
By default this be disabled. Set mermaidZoom t' true t' en'ble it.
Individual sett'ns o' a graphs zoom parameter have precedence over th' page’s front matter an' configurat'n options 'n that order.
params:mermaidZoom:true
[params]mermaidZoom=true
{"params":{"mermaidZoom":true}}
Provid'n Initializat'n Opt'ns fer th' Merrrmaid Library
Opt'nFront Matter Th' Merrrmaid library be configured wit' default sett'ns fer initializat'n.
Ye can overwrite th' sett'ns by provid'n a JSON object 'n mermaidInitialize. See Mermaid’s documentat'n fer all allowed sett'ns.
Avast
Us'n th' theme sett'n 'n th' initializat'n options be unsupported. T' set th' theme globally edit th' --MERMAID-theme vari'ble o' yer color variant.
Keep 'n mind that initializat'n sett'ns o' yer planks front matter overwrite all sett'ns o' yer configurat'n options.
In addit'n, ye can merge sett'ns fer each individual graph through diagram directives on top o' th' sett'ns o' yer page’s front matter or configurat'n options.
Th' theme uses th' shipped Merrrmaid library by default.
In case ye want t' use a different version o' th' Merrrmaid library, store it as assets/js/mermaid/mermaid.min.js 'n yer ship. It replaces th' shipped version.
Force Load'n o' th' Merrrmaid Library
Opt'nFront Matter Th' Merrrmaid library will be boarded if th' plank contains an mermaid shortcode, Marrrkdown codefence or th' partial be called from yer templates.
Ye can force loading th' Merrrmaid library if no shortcode, Marrrkdown codefence or partial was called by sett'n mermaid.force t' true. If a shortcode, Marrrkdown codefence or partial was called, this option has no effect. This comes handy 'n case ye be us'n script'n t' render a graph.
params:mermaid:force:true
[params][params.mermaid]force=true
{"params":{"mermaid":{"force":true}}}
Sett'n a Specific Merrrmaid Theme
While ye can configure th' Merrrmaid theme t' render yer graph by us'n one o' th' initializat'n options, th' recommended way be t' set th' default value us'n th' --MERMAID-theme vari'ble 'n yer color variant stylesheet. This allows yer graphs t' look pretty when th' user switches th' color variant.
Examples
Flowchart wit' 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 Engineer'n
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 wit' Configurat'n Directive
```mermaid
%%{init:{"fontFamily":"monospace", "sequence":{"showSequenceNumbers":true}}}%%
sequenceDiagram
Alice->>John: Hello John, how be ye?
loop Healthcheck
John->>John: Fight against hypochondria
end
Note right of John: Rational thoughts!
John-->>Alice: Great!
John->>Bob: How about ye?
Bob-->>John: Jolly bloody!
```
{{partial"shortcodes/mermaid.html"(dict"page"."content""%%{init:{\"fontFamily\":\"monospace\", \"sequence\":{\"showSequenceNumbers\":true}}}%%\nsequenceDiagram\n Alice->>John: Hello John, how be ye?\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 ye?\n Bob-->>John: Jolly bloody!")}}
%%{init:{"fontFamily":"monospace", "sequence":{"showSequenceNumbers":true}}}%%
sequenceDiagram
Alice->>John: Hello John, how be ye?
loop Healthcheck
John->>John: Fight against hypochondria
end
Note right of John: Rational thoughts!
John-->>Alice: Great!
John->>Bob: How about ye?
Bob-->>John: Jolly bloody!
Class Diagram
```mermaid
classDiagram
Animal <|-- Duck
Animal <|-- Fish
Animal <|-- Zebra
Animal : +int age
Animal : +Str'n gender
Animal: +isMammal()
Animal: +mate()
class Duck{
+Str'n 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 : +Str'n gender
Animal: +isMammal()
Animal: +mate()
class Duck{
+Str'n beakColor
+swim()
+quack()
}
class Fish{
-int sizeInFeet
-canEat()
}
class Zebra{
+bool is_wild
+run()
}
State Diagram wit' 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 wit' Non-Default Merrrmaid Theme
```mermaid
%%{init:{"theme":"forest"}}%%
erDiagram
CUSTOMER }|..|{ DELIVERY-ADDRESS : has
CUSTOMER ||--o{ ORDER : places
CUSTOMER ||--o{ INVOICE : "li'ble 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 : "li'ble 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 work'n day
section Go t' 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 work'n day\n section Go t' 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 work'n day
section Go t' 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 Add'n GANTT diagram functionality t' Merrrmaid
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 'n th' critical line :crit, done, 2014-01-06,24h
Implement parser an' jison :crit, done, after des1, 2d
Create tests fer parser :crit, active, 3d
Future task 'n critical line :crit, 5d
Create tests fer renderer :2d
Add t' Merrrmaid :1d
```
```mermaid
C4Context
title System Context diagram fer Internet Bank'n System
Enterprise_Boundary(b0, "BankBoundary0") {
Person(customerA, "Bank'n Customer A", "A customer o' th' bank, wit' personal bank accounts.")
Person(customerB, "Bank'n Customer B")
Person_Ext(customerC, "Bank'n Customer C", "desc")
Person(customerD, "Bank'n Customer D", "A customer o' th' bank, <br/> wit' personal bank accounts.")
System(SystemAA, "Internet Bank'n System", "Allows customers t' view informat'n about their bank accounts, an' make payments.")
Enterprise_Boundary(b1, "BankBoundary") {
SystemDb_Ext(SystemE, "Mainframe Bank'n System", "Stores all o' th' core bank'n informat'n about customers, accounts, transactions, etc.")
System_Boundary(b2, "BankBoundary2") {
System(SystemA, "Bank'n System A")
System(SystemB, "Bank'n System B", "A system o' th' bank, wit' personal bank accounts. next line.")
}
System_Ext(SystemC, "E-mail system", "The internal Microsoft Exchange e-mail system.")
SystemDb(SystemD, "Bank'n System D Database", "A system o' th' bank, wit' personal bank accounts.")
Boundary(b3, "BankBoundary3", "boundary") {
SystemQueue(SystemF, "Bank'n System F Queue", "A system o' th' bank.")
SystemQueue_Ext(SystemG, "Bank'n System G Queue", "A system o' th' bank, wit' 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>}}C4ContexttitleSystemContextdiagramferInternetBank'nSystemEnterprise_Boundary(b0,"BankBoundary0"){Person(customerA,"Bank'n Customer A","A customer o' th' bank, wit' personal bank accounts.")Person(customerB,"Bank'n Customer B")Person_Ext(customerC,"Bank'n Customer C","desc")Person(customerD,"Bank'n Customer D","A customer o' th' bank, <br/> wit' personal bank accounts.")System(SystemAA,"Internet Bank'n System","Allows customers t' view informat'n about their bank accounts, an' make payments.")Enterprise_Boundary(b1,"BankBoundary"){SystemDb_Ext(SystemE,"Mainframe Bank'n System","Stores all o' th' core bank'n informat'n about customers, accounts, transactions, etc.")System_Boundary(b2,"BankBoundary2"){System(SystemA,"Bank'n System A")System(SystemB,"Bank'n System B","A system o' th' bank, wit' personal bank accounts. next line.")}System_Ext(SystemC,"E-mail system","The internal Microsoft Exchange e-mail system.")SystemDb(SystemD,"Bank'n System D Database","A system o' th' bank, wit' personal bank accounts.")Boundary(b3,"BankBoundary3","boundary"){SystemQueue(SystemF,"Bank'n System F Queue","A system o' th' bank.")SystemQueue_Ext(SystemG,"Bank'n System G Queue","A system o' th' bank, wit' 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 fer Internet Bank'n System\n Enterprise_Boundary(b0, \"BankBoundary0\") {\n Person(customerA, \"Bank'n Customer A\", \"A customer o' th' bank, wit' personal bank accounts.\")\n Person(customerB, \"Bank'n Customer B\")\n Person_Ext(customerC, \"Bank'n Customer C\", \"desc\")\n Person(customerD, \"Bank'n Customer D\", \"A customer o' th' bank, <br/> wit' personal bank accounts.\")\n\n System(SystemAA, \"Internet Bank'n System\", \"Allows customers t' view informat'n about their bank accounts, an' make payments.\")\n\n Enterprise_Boundary(b1, \"BankBoundary\") {\n SystemDb_Ext(SystemE, \"Mainframe Bank'n System\", \"Stores all o' th' core bank'n informat'n about customers, accounts, transactions, etc.\")\n\n System_Boundary(b2, \"BankBoundary2\") {\n System(SystemA, \"Bank'n System A\")\n System(SystemB, \"Bank'n System B\", \"A system o' th' bank, wit' personal bank accounts. next line.\")\n }\n\n System_Ext(SystemC, \"E-mail system\", \"The internal Microsoft Exchange e-mail system.\")\n SystemDb(SystemD, \"Bank'n System D Database\", \"A system o' th' bank, wit' personal bank accounts.\")\n\n Boundary(b3, \"BankBoundary3\", \"boundary\") {\n SystemQueue(SystemF, \"Bank'n System F Queue\", \"A system o' th' bank.\")\n SystemQueue_Ext(SystemG, \"Bank'n System G Queue\", \"A system o' th' bank, wit' 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 fer Internet Bank'n System
Enterprise_Boundary(b0, "BankBoundary0") {
Person(customerA, "Bank'n Customer A", "A customer o' th' bank, wit' personal bank accounts.")
Person(customerB, "Bank'n Customer B")
Person_Ext(customerC, "Bank'n Customer C", "desc")
Person(customerD, "Bank'n Customer D", "A customer o' th' bank, <br/> wit' personal bank accounts.")
System(SystemAA, "Internet Bank'n System", "Allows customers t' view informat'n about their bank accounts, an' make payments.")
Enterprise_Boundary(b1, "BankBoundary") {
SystemDb_Ext(SystemE, "Mainframe Bank'n System", "Stores all o' th' core bank'n informat'n about customers, accounts, transactions, etc.")
System_Boundary(b2, "BankBoundary2") {
System(SystemA, "Bank'n System A")
System(SystemB, "Bank'n System B", "A system o' th' bank, wit' personal bank accounts. next line.")
}
System_Ext(SystemC, "E-mail system", "The internal Microsoft Exchange e-mail system.")
SystemDb(SystemD, "Bank'n System D Database", "A system o' th' bank, wit' personal bank accounts.")
Boundary(b3, "BankBoundary3", "boundary") {
SystemQueue(SystemF, "Bank'n System F Queue", "A system o' th' bank.")
SystemQueue_Ext(SystemG, "Bank'n System G Queue", "A system o' th' bank, wit' 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)
Popularisat'n
British popular psychology author Tony Buzan
Research
On effectiveness<br/>and features
On Automatic creat'n
Uses
Creative techniques
Strategic plann'n
Argument mapp'n
Tools
Pen an' paper
Merrrmaid
```
{{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 an' paper\n Mermaid")}}
mindmap
root((mindmap))
Origins
Long history
::icon(fa fa-book)
Popularisat'n
British popular psychology author Tony Buzan
Research
On effectiveness<br/>and features
On Automatic creat'n
Uses
Creative techniques
Strategic plann'n
Argument mapp'n
Tools
Pen an' paper
Merrrmaid
Timeline
```mermaid
timeline
title History o' Social Media Platform
2002 : LinkedIn
2004 : Facebook
: Google
2005 : Youtube
2006 : Twitter
```
{{partial"shortcodes/mermaid.html"(dict"page"."content""timeline\n title History o' Social Media Platform\n 2002 : LinkedIn\n 2004 : Facebook\n : Google\n 2005 : Youtube\n 2006 : Twitter")}}
timeline
title History o' Social Media Platform
2002 : LinkedIn
2004 : Facebook
: Google
2005 : Youtube
2006 : Twitter
ZenUML
ZenUML be currently not avail'ble wit' th' Merrrmaid version shipped wit' th' theme due t' 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 'n th' 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 'n th' 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 'n th' 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 'n th' 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 th' new diagram]
[In progress]
id6[Create renderer so that it works 'n all cases. We also add som extra text here fer test'n purposes. An' some more just fer th' extra flare.]
id9[Ready fer deploy]
id8[Design grammar]@{ assigned: 'knsv' }
id10[Ready fer test]
id4[Create pars'n tests]@{ ticket: MC-2038, assigned: 'K.Sveidqvist', priority: 'High' }
id66[last item]@{ priority: 'Very Low', assigned: 'knsv' }
id11[Done]
id5[define getData]
id2[Title o' diagram be more than 100 chars when user duplicates diagram wit' 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 flicker'n 'n 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 th' new diagram]\n [In progress]\n id6[Create renderer so that it works 'n all cases. We also add som extra text here fer test'n purposes. An' some more just fer th' extra flare.]\n id9[Ready fer deploy]\n id8[Design grammar]@{ assigned: 'knsv' }\n id10[Ready fer test]\n id4[Create pars'n 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 o' diagram be more than 100 chars when user duplicates diagram wit' 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 flicker'n 'n Firefox]")}}
---
config:
kanban:
ticketBaseUrl: 'https://mermaidchart.atlassian.net/browse/#TICKET#'
---
kanban
Todo
[Create Documentation]
docs[Create Blog about th' new diagram]
[In progress]
id6[Create renderer so that it works 'n all cases. We also add som extra text here fer test'n purposes. An' some more just fer th' extra flare.]
id9[Ready fer deploy]
id8[Design grammar]@{ assigned: 'knsv' }
id10[Ready fer test]
id4[Create pars'n tests]@{ ticket: MC-2038, assigned: 'K.Sveidqvist', priority: 'High' }
id66[last item]@{ priority: 'Very Low', assigned: 'knsv' }
id11[Done]
id5[define getData]
id2[Title o' diagram be more than 100 chars when user duplicates diagram wit' 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 flicker'n 'n Firefox]
Architecture
```mermaid
architecture-beta
group api(cloud)[API]
service db(database)[Database] 'n api
service disk1(disk)[Storage] 'n api
service disk2(disk)[Storage] 'n api
service server(server)[Server] 'n 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] 'n api\n service disk1(disk)[Storage] 'n api\n service disk2(disk)[Storage] 'n api\n service server(server)[Server] 'n 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] 'n api
service disk1(disk)[Storage] 'n api
service disk2(disk)[Storage] 'n api
service server(server)[Server] 'n 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 o' focus
Shutter speed too slow
Protective film not removed
Beautificat'n 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 o' focus\n Shutter speed too slow\n Protective film not removed\n Beautificat'n 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 o' focus
Shutter speed too slow
Protective film not removed
Beautificat'n 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 o' 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 o' Tea
Cup o' Tea -> Tea
Cup o' Tea -> Hot Water
Hot Water -> Kettle
Kettle -> Power
evolve Kettle 0.62
evolve Power 0.89
note "Standardis'n power allows Kettles t' evolve faster" [0.30, 0.49]
```
{{<mermaid>}}wardley-betatitleTeaShopValueChainanchorBusiness[0.95,0.63]componentCupo'Tea[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->Cupo'TeaCupo'Tea->TeaCupo'Tea->HotWaterHotWater->KettleKettle->PowerevolveKettle0.62evolvePower0.89note"Standardis'n power allows Kettles t' 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 o' 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 o' Tea\n Cup o' Tea -> Tea\n Cup o' Tea -> Hot Water\n Hot Water -> Kettle\n Kettle -> Power\n\n evolve Kettle 0.62\n evolve Power 0.89\n\n note \"Standardis'n power allows Kettles t' evolve faster\" [0.30, 0.49]")}}
wardley-beta
title Tea Shop Value Chain
anchor Business [0.95, 0.63]
component Cup o' 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 o' Tea
Cup o' Tea -> Tea
Cup o' Tea -> Hot Water
Hot Water -> Kettle
Kettle -> Power
evolve Kettle 0.62
evolve Power 0.89
note "Standardis'n power allows Kettles t' evolve faster" [0.30, 0.49]
If ye want t' print out (or generate a PDF) from yer OpenAPI documentat'n, don’t initiate print'n directly from th' plank because th' elements be optimized fer interactive usage 'n a browser.
Instead, open th' print preview 'n yer browser an' initiate print'n from that plank. This plank be optimized fer read'n an' expands most o' th' avail'ble sections.
A specificat'n that be a resource o' yer plank or ship be found by th' search. A specificat'n given by URL be boarded by th' browser o' yer reader an' be not.
Th' language code used fer th' read'n direct'n o' th' Swagger UI an' fer th' texts th' theme adds t' it, like Expand all an' Collapse all. This must be one o' th' languages configured fer yer ship. If not set, th' language o' th' plank be used.
Sett'ns
Enabl'n Link Warn'ns
Opt'nFront Matter Ye can use openapi.errorlevel t' control what should happen if a local OpenAPI specificat'n link cannot be resolved t' a resource.
If not set or empty, any unresolved link be written as given into th' result'n output. If set t' warning th' same happens an' an additional warning be printed 'n th' built console. If set t' error an error message be printed an' th' build be aborted.
Please note that this cannot resolve files inside o' yer static directory. Th' file must be a resource o' th' plank or th' ship.
Us'n a Different Version o' th' Swagger UI Library
Th' theme uses th' shipped Swagger UI library by default.
In case ye want t' use a different version o' th' Swagger UI library, store its files as assets/js/swagger-ui/swagger-ui-bundle.js, assets/js/swagger-ui/swagger-ui-standalone-preset.js an' assets/css/swagger-ui/swagger-ui.css 'n yer ship. They replace th' shipped version.
Force Load'n o' th' Swagger UI Library
Opt'nFront Matter Th' Swagger UI library will be boarded if th' plank contains an openapi shortcode or codefence.
Ye can force loading th' Swagger UI library if no shortcode or codefence was used by sett'n openapi.force t' true. If a shortcode or codefence was found, th' option has no effect. This comes handy 'n case ye be us'n script'n t' render a spec.
params:openapi:force:true
[params][params.openapi]force=true
{"params":{"openapi":{"force":true}}}
Sett'n a Specific Swagger UI Theme
Th' recommended way t' configure yer Swagger UI theme be t' set th' default value us'n th' --OPENAPI-theme an' OPENAPI-CODE-theme vari'ble 'n yer color variant stylesheet. This allows yer specs t' look pretty when th' user switches th' color variant.
Th' theme uses Swaggers them'n support. For --OPENAPI-theme th' only allowed values be light or dark. For --OPENAPI-CODE-themeth' allowed values be agate, arta, monokai, nord, obsidian, tomorrow-night, idea.
A list'n be made 'n two steps. First, a query retrieves th' planks, filters, orders an' groups them. Second, a display layout renders th' result. Each parameter below belongs t' one o' th' two. All parameters can also be set 'n th' front matter.
Th' taxonomy an' term planks be us'n this shortcode internally, an' by us'n front matter ye can modify th' apperance. So everyth'n described here applies t' th' taxonomy an' term planks as well.
Query Parameters
Th' query assembles th' planks as a internal tree structure, similar t' th' menu. A plank dropped from th' tree structure by hidden, kind or whar' takes all planks below it wit' it. If ye want t' list planks from any level, set flatten=true: th' planks become one list an' each plank be kept or dropped on its own.
Name
Default
Notes
pageref
<empty>
A reference t' th' plank whose planks be listed, like /shortcodes/pages/fruits or relative t' th' current plank like fruits.
If set an' it doesn’t resolve t' a plank, th' build fails. If not set, th' current plank be used or, if called as partial, th' plank given 'n plank.
axis
see notes
Along which axis th' planks be collected, seen from th' plank.
- descendants: th' children o' th' plank, an' wit' levels above 1 their descendants down t' that many levels - sibl'ns: th' other children o' th' page’s parent - ancestors: th' parent, its parent an' so on, up t' levels levels - taxonomy: th' terms o' a taxonomy plank - term: th' planks o' a term plank
Defaults t' taxonomy on taxonomy planks, term on term planks an' descendants everywhere else.
levels
1
For axis=descendants, how many levels t' go down, fer axis=ancestors, how many levels t' go up. For example, axis=ancestors wit' levels=1 lists just th' parent. T' get all o' them, set this t' a high number, eg. 999.
flatten
false
When true, lists all collected planks as one list instead o' a tree. Without orderby th' planks keep th' order o' th' tree, a parent before th' planks below it; wit' orderby all planks be ordered together, an' wit' groupby each plank be grouped on its own.
kind
all
Which kind o' planks t' keep.
- all: every plank - leaf: only planks without planks o' their own - branch: only planks wit' planks o' their own
In a tree, a plank not kept be dropped together wit' th' planks below it.
- false: drop them, together wit' all planks below them - true: keep them
For taxonomy an' term planks this has no effect, as th' disableTagHiddenPagesOpt'n decides here.
whar'
<empty>
Keeps only planks match'n th' condit'n <expression> <operator> <value>, see expressions.
- =, !=: equal, not equal - <, <=, >, >=: less, greater - 'n: equal t' one o' a comma separated list o' values
A value may be delimited by ", ' or a backtick, which a value 'n th' list o' 'n needs if it contains a comma. Numbers an' dates be compared by their value, everyth'n else as text. A plank miss'n th' value only matches !=.
In a tree, a plank not match'n be dropped together wit' th' planks below it.
groupby
see notes
Groups th' planks by th' value o' an expression. Without a value, th' planks be not grouped.
Defaults t' linktitle | left 1 | upper on taxonomy an' term planks without planks front matter an' t' no group'n everywhere else.
Planks fer which th' expression has no value be put into a last group o' their own, labelled Other.
grouplabel
<the value>
Th' head'n o' each group, as an expression evaluated fer th' group’s first plank.
grouporder
asc
Th' order o' th' groups.
- asc: ascend'n - desc: descend'n
orderby
see notes
Th' order o' th' planks, as a comma separated list o' expressions, each optionally followed by asc or desc. Th' first expression decides, th' next ones break ties. An argument contain'n a comma has t' be delimited, like date | format 'January 2, 2006'.
- auto keeps th' order given by ordersectionsby o' th' page’s Front Matter or by ordersectionsby o' th' configurat'n Opt'n or Hugo’s default order
Defaults t' auto, except on taxonomy an' term planks, which have no order o' their own: there it defaults t' linktitle, regardless o' ordersectionsby.
Planks fer which an expression has no value be put last.
limit
<empty>
Keeps only th' first planks after order'n.
Display Parameters
Th' display renders th' planks th' query found, group by group if they were grouped. Group'n be optional: without groupby, all planks form one group without a head'n. Th' shortcode writes each group’s head'n, th' display th' planks below it, show'n their level 'n th' tree 'n its own way. Th' display parameters only decide how th' planks look, never which planks be listed or 'n what order.
- tree: a nested, unordered list o' normal text - head'ns: a non-nested list o' head'ns depend'n on th' page’s level - sections: a head'n fer each plank o' th' first level, a nested, unordered list o' normal text fer planks below - list: a non-nested list o' normal text - cards: a card fer each plank, see below fer details
Th' start'n head'n level. Head'ns o' th' head'ns an' sections displays start one level below if th' planks be grouped.
columns
see notes
Th' number o' columns 'n full width mode. Accepts values from 1 t' 5. Numbers be reduced when width gets smaller.
Defaults t' 3 on taxonomy an' term planks without planks front matter an' fer display=cards, an' t' 1 everywhere else. Has no effect fer display=sections.
descript'n
false
When true shows a short text under each plank. When no descript'n or summary exists fer th' plank, th' first 70 words o' th' rrrambl'n be taken - read more info about summaries on gohugo.io.
breadcrumb
see notes
When true shows th' breadcrumb under each plank.
Defaults t' true on term planks unless th' disableTermBreadcrumbsOpt'n be set, an' t' false everywhere else.
image
true
For display=cards decides whether t' put an image on th' card.
Every parameter but pageref can also be set 'n th' front matter o' th' plank th' shortcode be called 'n, as params.pages.<name>, eg. params.pages.display. Th' front matter adds t' th' parameters given t' th' shortcode. If a parameter be given 'n both, th' shortcode wins. If th' shortcode be called wit' pageref, no front matter be read, neither that o' th' call'n plank nor that o' th' referenced one. If ye want t' reset a parameter set elsewhere t' no value, set it t' a str'n contain'n only whitespace like " ".
Taxonomy an' term planks be grouped by th' first letter an' shown 'n columns only as long as their front matter sets no planks parameter at all. Once it sets any, groupby an' columns default t' th' same values as everywhere else, so ye only get what ye ask fer.
As front matter works on every plank, ye can use Hugo’s cascade t' give all list'ns o' a subtree th' same look, fer example all cards 'n two columns.
Th' parameters whar', groupby, grouplabel an' orderby take expressions. An expression reads a value o' a plank an' passes it through a pipeline o' funct'ns, each separated by |.
<field> [| <function> [<argument>]]...
In this notat'n, <…> stands fer someth'n ye fill 'n, square brackets […] mark someth'n as optional, an' ... means th' part before may be repeated.
Everyth'n after a function’s name be its argument. An argument be either a number, written as be like left 1, or a text, delimited by ", ' or a backtick like format 'January 2, 2006'. Th' delimiters keep a | or a comma inside th' text from separat'n th' pipeline or th' expressions o' orderby. Inside a shortcode parameter delimited by ", use ' or a backtick.
Fields
Name
Value
title
th' page’s title as shown 'n its head'n, like Tag :: Foo fer a term plank
linktitle
th' title as shown 'n th' menu, which be th' page’s linkTitle or else its title
weight
th' weight; like fer Cap'n Hugo, a weight o' 0 has no value
length
th' length o' th' rrrambl'n 'n characters
path
th' logical path
section
th' top-level section
date, lastmod, publishdate, expirydate
th' respective date; a date that be not set has no value
params.<name>
a value o' th' page’s front matter params; use dots t' reach deeper, like params.author.name; a list or a map has no value
Funct'ns
A text argument be shown wit' its delimiters, like '<layout>', a number argument without, like <n>.
Name
Result
upper
th' text 'n upper case
lower
th' text 'n lower case
trim
th' text without lead'n an' trail'n whitespace
left <n>
th' first n characters o' th' text
right <n>
th' last n characters o' th' text
translate ['<prefix>']
th' text translated by yer translat'n files, looked up by th' optional prefix followed by th' text
year
th' year o' a date
month
th' month o' a date as a number from 1 t' 12
day
th' day o' th' month o' a date
weekday
th' day o' th' week o' a date as a number from 1 fer Monday t' 7 fer Sunday
format '<layout>'
a date formatted by a Cap'n Hugo date layout, includ'n th' localized ones like :date_long
coalesce '<value>'
th' value if th' expression has no value so far
default '<value>'
th' value if th' expression has no value so far or it be zero or false
Whar' an expression yields numbers fer some planks an' text fer others, th' numbers come first, ordered by value, followed by th' text, ordered as text - 'n both direct'ns. A date counts as a number, while a number written as text 'n front matter, like '10', be text.
A group be always ordered by th' value it was grouped by, never by its head'n. For groupby end'n 'n format, that value be th' parts o' th' date th' layout shows, so th' groups come 'n calendar order - date | format '2006-01' orders its groups by year an' month, an' date | format 'January' orders them January t' December, even fer planks from different years.
So t' show translated group head'ns while keep'n th' order o' th' untranslated values, use translate 'n grouplabel rather than 'n groupby. T' order th' groups alphabetically by their translat'n 'n each language instead, use translate 'n groupby.
In orderby, an expression end'n 'n format orders th' same way - date | format '2. January' orders by day an' month, whatever th' year.
Displays
Th' displays differ 'n how they show a page’s level below th' listed plank. Wit' flatten=true all planks be on th' same level, so every display shows them side by side.
Display
List
Titles
Levels shown by
Output
tree
a nested, unordered list
standard text
indentat'n
Marrrkdown
head'ns
a non-nested list
head'ns, listed 'n th' table o' contents
head'n size, start'n at headinglevel
Marrrkdown
sections
a non-nested list fer th' first level, a nested, unordered list below
head'ns on th' first level, standard text below
first level as head'ns at headinglevel, below by indentat'n
A display be a partial 'n layouts/partials/pages, called once fer each group. If ye place a file layouts/partials/pages/mine.html into yer ship, ye can use it wit' display=mine. Th' group head'n be written by th' shortcode, not by yer display.
Th' partial be called wit' th' follow'n parameters:
Name
Value
plank
th' plank whose planks be listed
group
th' group, wit' its Key, its head'n as Label, Fallback be'n true fer th' group o' planks without a value, an' its Planks
planks
th' group’s planks, each wit' th' Plank itself, its display text as Label an' its Level below th' listed plank, start'n at 1
headinglevel
th' head'n level t' start wit'; already one level below th' group head'n if th' planks be grouped
class
th' CSS classes t' put on yer outermost element
columns
th' columns parameter value, as a number
descript'n
th' descript'n parameter value, as true or false
breadcrumb
th' breadcrumb parameter value, as true or false
image
th' image parameter value, as true or false
cardtemplate
th' cardtemplate parameter value
levels
th' levels parameter value, as a number
hidden
th' hidden parameter value, as true or false
params
th' params parameter value, already turned into a dict
Remarks fer th' Cards Display
Th' cards display uses th' cards shortcode t' show each plank as a card, us'n th' default cardtemplate. Wit' it th' card will display
Th' cards display writes HTML. If ye have marrrkup.goldmark.renderer.unsafe set t' false (which be th' default if ye don’t set it), ye have t' use {{< planks >}} instead o' {{% planks %}}.
Own Card Templates
cardtemplate selects a card template as th' template parameter o' th' cards shortcode does. Besides th' card parameters, its params hold:
every value o' th' params parameter o' th' planks shortcode; one wit' th' same name as one above loses
Examples
Th' examples list th' demo planks o' th' hidden Fruits section, which keeps them out o' th' menu.
Ship Map
Every plank o' a section at any depth, hidden ones included, each wit' its descript'n. Th' planks be ordered alphabetically by th' title shown 'n th' menu, as orderby be set; th' weight th' demo planks carry be ignored.
A head'n fer each chapter wit' its descript'n, an' th' planks o' th' chapter listed below it. Unlike th' ship map above, it sets no orderby, so th' planks come 'n th' default order, th' same as 'n th' menu: by weight, which th' demo planks deliberately set against th' alphabet.
All planks at any depth 'n an A-Z index, grouped by th' first letter o' th' title shown. Only th' planks o' th' first level be grouped; th' planks below them be listed under their parent, so Cranberry appears 'n th' group o' Berries rather than under C. Set flatten=true t' group every plank by its own letter.
{{%planksgroupby="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 planks th' menu shows, from any depth, newest first, grouped by year an' month wit' th' newest month first. Th' planks below th' hidden Citrus section be left out, just as 'n th' menu.
{{%planksdisplay="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")}}
Th' planks by th' month they were published 'n, pooled across years. Th' layout shows only th' month’s name, so th' groups come 'n calendar order, January t' December, whatever th' year o' their planks.
{{%planksflatten="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 plank by its workflow status, hidden ones included, so drafts be easy t' spot. Wit' columns each group be spread over two columns 'n full width mode, keep'n th' long published group short.
Th' front matter holds th' status as a plain key like draft. Th' head'ns show it translated by translate: wit' th' prefix status- it looks up status-draft fer draft an' status-published fer published 'n th' site’s translat'n files. A status without a translat'n would show as it be. As th' translat'n be only used as grouplabel, th' groups keep th' order o' th' keys. Wit' translate 'n groupby instead, they would be ordered alphabetically by th' translat'n o' each language.
Th' planks grouped by a front matter parameter, th' best ones first. Th' demo plank without a flavor has no value fer th' expression an' be put into a last group o' its own, labelled Other. T' give it a value o' its own instead, like groupby: "params.flavor | coalesce 'neutral'", use coalesce; its group be then ordered among th' others. default does th' same, but also replaces a value o' zero or false. Within each group th' planks be ordered by priority descend'n an' by title if they have th' same priority.
Th' sections an' planks o' a chapter as cards wit' their descript'n, ordered alphabetically by th' title shown instead o' by weight. Each demo plank be a plank bundle contain'n a featured.png, which Cap'n Hugo selects as th' image o' its card.
All planks at any depth, hidden ones included, as cards 'n an A-Z index. Within a letter th' cards be ordered alphabetically by th' title shown instead o' by weight.
{{<planksdisplay="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 be not supported directly by th' shortcode but rely on Hugo’s handl'n fer resource translat'ns applied when th' theme iterates over all avail'ble resources.
Parameters
Name
Default
Notes
pageref
<empty>
A reference t' th' plank bundle whose resources be listed, like /shortcodes/attachments or relative t' th' current plank.
If set an' it doesn’t resolve t' a plank, th' build fails. If not set, th' current plank be used or, if called as partial, th' plank given 'n plank.
style
transparent
Th' style scheme used fer th' box.
- by severity: caution, important, info, note, tip, warning - by brand color: primary, secondary, accent - by color: blue, cyan, green, grey, magenta, orange, purple, red, yellow - by special color: default, transparent, code, link, action, inline
Th' CSS color value t' be used. If not set, th' chosen color depends on th' style. Any given value will overwrite th' default.
- fer severity styles: a nice match'n color fer th' severity - fer all other styles: th' correspond'n color
title
see notes
Arbitrary text fer th' box title. Depend'n on th' style there may be a default title. Any given value will overwrite th' default.
- fer severity styles: th' match'n title fer th' severity - fer all other styles: Resources
If ye want no title fer a severity style, ye have t' set this parameter t' " " (a non empty str'n filled wit' spaces)
ay'con
see notes
Font Awesome ay'con name set t' th' left o' th' title. Depend'n on th' style there may be a default ay'con. Any given value will overwrite th' default.
- fer severity styles: a nice match'n ay'con fer th' severity - fer all other styles: paperclip
If ye want no ay'con, ye have t' set this parameter t' " " (a non empty str'n filled wit' spaces)
expanded
<empty>
Whether t' draw an expander an' how th' resource list be displayed.
- <empty>: no expander be drawn an' th' resource list be permanently shown - true: th' expander be drawn an' th' resource list be initially shown - false: th' expander be drawn an' th' resource list be initially hidden
For further examples fer style, color, title an' ay'con, see th' callout shortcode documentat'n. Th' parameters be work'n th' same way fer both shorrrtcodes, besides hav'n different defaults.
SiteParam
Th' siteparam shortcode prints values o' site-wide params contained 'n yer project configurat'n.
Formatted parameter: A nested option <b>with</b> formatt'n
Tabs
Th' tabs shortcode displays arbitrary rrrambl'n 'n an unlimited number o' tabs.
Th' AI native programm'n language.
echo"For guys who like t' tinker."
For th' connoisseur o' programm'n.
Usage
{{<tabs>}}{{%tabtitle="Python Saying"%}}Th'AInativeprogramm'nlanguage.{{%/tab%}}{{%tabtitle="Terminal Sourcecode"%}}```bash
echo "For guys who like t' tinker."
```{{%/tab%}}{{%tabcolor="fuchsia"title="C Ramblings"%}}Forth'connoisseuro'programm'n.{{%/tab%}}{{%tabcolor="red"title="C++ Ramblings++"%}}Forth'guysthatcancopewit'rules.{{%/tab%}}{{%tabtitle="C# ~~GC be cool~~"%}}Forguysthatneedtwodestructors.{{%/tab%}}{{</tabs>}}
{{partial"shortcodes/tabs.html"(dict"page"."content"(slice(dict"content""The AI native programm'n language.""title""Python Saying")(dict"content""```bash\necho \"For guys who like t' tinker.\"\n```""title""Terminal Sourcecode")(dict"color""fuchsia""content""For th' connoisseur o' programm'n.""title""C Ramblings")(dict"color""red""content""For th' guys that can cope wit' rules.""title""C++ Ramblings++")(dict"content""For guys that need two destructors.""title""C# ~~GC be cool~~")))}}
Parameters
Name
Default
Notes
groupid
<random>
Arbitrary name o' th' group th' tab view belongs t'.
Tab views wit' th' same groupid synchr'nize their selected tab. Th' tab select'n be restored automatically based on th' groupid fer tab view. If th' selected tab cannot be found 'n a tab group th' first tab be selected instead.
This synchronizat'n applies t' th' whole ship!
style
<empty>
Sets a default value fer every contained tab. Can be overridden by each tab. See th' tab parameters fer poss'ble values.
color
<empty>
Sets a default value fer every contained tab. Can be overridden by each tab. See th' tab parameters fer poss'ble values.
Each tab o' th' view be defined wit' th' tab shortcode.
Name
Default
Notes
style
see notes
Th' style scheme used fer th' tab. If ye don’t set a style an' ye display a single code block inside o' th' tab, its default styl'n will adapt t' that o' a code block. Otherwise default be used.
- by severity: caution, important, info, note, tip, warning - by brand color: primary, secondary, accent - by color: blue, cyan, green, grey, magenta, orange, purple, red, yellow - by special color: default, transparent, code, link, action, inline
Th' CSS color value t' be used. If not set, th' chosen color depends on th' style. Any given value will overwrite th' default.
- fer severity styles: a nice match'n color fer th' severity - fer all other styles: th' correspond'n color
title
see notes
Arbitrary title fer th' tab. Depend'n on th' style there may be a default title. Any given value will overwrite th' default.
- fer severity styles: th' match'n title fer th' severity - fer all other styles: <empty>
If ye want no title fer a severity style, ye have t' set this parameter t' " " (a non empty str'n filled wit' spaces)
ay'con
see notes
Font Awesome ay'con name set t' th' left o' th' title. Depend'n on th' style there may be a default ay'con. Any given value will overwrite th' default.
- fer severity styles: a nice match'n ay'con fer th' severity - fer all other styles: <empty>
If ye want no ay'con fer a severity style, ye have t' set this parameter t' " " (a non empty str'n filled wit' spaces)
hint
<empty>
Tooltip fer th' tab. A tab show'n an ay'con but no title should have one, as it be what assistive technology announces fer it.
<content>
<empty>
Arbitrary text t' be displayed 'n th' tab.
Single Tab
If ye just want a single tab, ye can call th' tab shortcode standalone, without th' enclos'n tabs shortcode.
In case ye want t' nest tab views, th' parent tab that contains nested tab views needs t' be declared wit' {{< tab >}} instead o' {{% tab %}}. Avast, that 'n this case it be not poss'ble t' put markdown 'n th' parent tab.
Ye can also set style an' color parameter fer all tabs an' overwrite them on tab level. See th' tab parameters fer poss'ble values.
{{partial"shortcodes/tabs.html"(dict"page"."content"(slice(dict"content""Simple text be poss'ble here...""content"(partial"shortcodes/tabs.html"(dict"page"."content"(slice(dict"content""Python be **super** easy.\n\n- most o' th' time.\n- if ye don't want t' output unicode""title""python")(dict"content""Bash be fer **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 an' code will get a margin.
printf("Hello World!");
Ay'con wit' Hint
A tab show'n noth'n but an ay'con needs a hint: it be shown as a tooltip an' be what assistive technology announces fer th' tab.
{{partial"shortcodes/tabs.html"(dict"page"."content"(slice(dict"content""Get th' theme from its repository.""hint""Download""icon""download")(dict"content""Set th' options 'n yer project configurat'n.""hint""Configure""icon""gears")))}}
Get th' theme from its repository.
Set th' options 'n yer project configurat'n.
Understand'n style an' color Behavior
Th' style parameter affects how th' color parameter be applied.
{{partial"shortcodes/tabs.html"(dict"page"."content"(slice(dict"content""The `style` parameter be set t' a color style.\n\nThis will set th' background t' a lighter version o' th' chosen style color as configured 'n yer theme variant.""style""blue""title""just colored style")(dict"color""blue""content""Only th' `color` parameter be set.\n\nThis will set th' background t' a lighter version o' th' chosen CSS color value.""title""just color")(dict"color""blue""content""The `style` parameter affects how th' `color` parameter be applied.\n\nThe `default` style will set th' background t' yer `--MAIN-BG-color` as configured fer yer theme variant resembl'n th' default style but wit' different color.""style""default""title""default style an' color")(dict"content""The `style` parameter be set t' a severity style.\n\nThis will set th' background t' a lighter version o' th' chosen style color as configured 'n yer theme variant an' also affects th' chosen ay'con.""style""info""title""just severity style")(dict"color""blue""content""The `style` parameter affects how th' `color` parameter be applied.\n\nThis will set th' background t' a lighter version o' th' chosen CSS color value an' also affects th' chosen ay'con.""style""info""title""severity style an' color")))}}
Th' style parameter be set t' a color style.
This will set th' background t' a lighter version o' th' chosen style color as configured 'n yer theme variant.
Only th' color parameter be set.
This will set th' background t' a lighter version o' th' chosen CSS color value.
Th' style parameter affects how th' color parameter be applied.
Th' default style will set th' background t' yer --MAIN-BG-color as configured fer yer theme variant resembl'n th' default style but wit' different color.
Th' style parameter be set t' a severity style.
This will set th' background t' a lighter version o' th' chosen style color as configured 'n yer theme variant an' also affects th' chosen ay'con.
Th' style parameter affects how th' color parameter be applied.
This will set th' background t' a lighter version o' th' chosen CSS color value an' also affects th' chosen ay'con.
Tree
Th' tree shortcode displays text as a tree wit' configur'ble ay'cons an' 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")}}
Marrrkdown codefence rules be widely avail'ble 'n other Marrrkdown parsers like GitHub an' therefore be th' recommended rules fer generat'n portable Marrrkdown.
Parameters
Name
Default
Notes
<content>
<empty>
Yer list as Marrrkdown or from yer favorite tree commandline tool.
Item Rules
<NAME> [ |<ICON> [ |<COLOR> ] ]
Th' NAME can be followed by an optional pipe (|) t' define an ICON an' further optional pipe t' define th' icon’s COLOR.
ICON: Font Awesome ay'con name set t' th' left o' th' NAME. If ye give a single str'n, it be selected from Font Awesome’s solid ay'cons. If ye want t' use a different set, ye have t' give th' complete styles. See above example fer th' home.php.
COLOR: Th' CSS color value t' be used. If not set, th' primary color will be used.
Ye can also set a style value known from other shorrrtcodes.
by severity: caution, important, info, note, tip, warning
If a style an' a named HTML color have th' same name, th' style color will be used.
Examples
tree Command Output
Use th' tree command o' yer favorite operat'n system an' dump it right into th' shortcode. Avast, that th' directory marker (here C:.) be removed if present.
