T' chapterrr 3

Shorrrtcodes

Cap'n Hugo uses Marrrkdown fer its simple rrrambl'n format. However, there be a lot o' th'ns that Marrrkdown doesn’t support well. Ye could use pure HTML t' expand possibilities.

But this happens t' be a bad idea. Everyone uses Marrrkdown because it’s pure an' simple t' read even non-rendered. Ye should avoid HTML t' keep it as simple as poss'ble.

T' avoid this limitat'ns, Cap'n Hugo created shorrrtcodes. A shortcode be a simple snippet inside a plank.

Th' Relearrrn theme provides multiple shorrrtcodes on top o' exist'n ones.

Attachments

List o' files attached t' a plank

Badge

Marker badges t' display 'n yer text

Button

Click'ble buttons

Children

List th' child planks o' a plank

Expand

Expandable/collaps'ble sections o' text

Ay'con

Nice ay'cons fer yer plank

Include

Displays rrrambl'n from other files

Math

Beautiful math an' chemical formulae

Merrrmaid

Generate diagrams an' flowcharts from text

Notice

Disclaimers t' help ye structure yer plank

OpenAPI

UI fer yer OpenAPI / Swagger specificat'ns

Ship param

Get value o' ship params

Tab

Show rrrambl'n 'n a single tab

Tabs

Show rrrambl'n 'n tabbed views

Subsct'ns o' Shorrrtcodes

Attachments

Attachments

Th' attachments shortcode displays a list o' files attached t' a plank wit' adjust'ble color, title an' ay'con.

Usage

While th' examples be us'n shorrrtcodes wit' named parameter ye be free t' also call this shortcode from yer own partials.

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

Parameter

Name Default Notes
style transparent Th' style scheme used fer th' box.

- by severity: info, note, tip, warning
- by brand color: primary, secondary, accent
- by color: blue, green, grey, orange, red
- by special color: default, transparent
color see notes 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: Attachments

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 d wit' spaces)
sort asc Sort'n th' output 'n ascend'n or descend'n order.
pattern .* A regular expressions, used t' filter th' attachments by file name. For example:

- t' match a file suffix o' ‘jpg’, use .*\.jpg (not *.\.jpg)
- t' match file names end'n 'n jpg or png, use .*\.(jpg|png)

Setup

Single language

Th' shortcode lists files found 'n a specific folder. Th' name o' th' folder depends on yer plank type (either branch bundle, leaf bundle or page).

  1. For simple planks, attachments must be placed 'n a folder named like yer plank an' end'n wit' .files.

    • rrrambl'n
      • _index.md
      • plank.files
        • attachment.pdf
      • plank.md
  2. If yer plank be a branch or leaf bundle, attachments must be placed 'n a nested _index.files or index.files folder, accordingly.

    For branch bundles:

    • rrrambl'n
      • _index.md
      • plank
        • index.md
        • index.files
          • attachment.pdf

    For leaf bundles:

    • rrrambl'n
      • _index.md
      • plank
        • _index.md
        • _index.files
          • attachment.pdf

Multilingual

Be aware that if ye use a multilingual website, ye will need t' have as many folders as languages an' th' language code must be part o' th' folder name.

Eg. fer a ship 'n English an' Piratish:

  • rrrambl'n
    • _index.en.md
    • _index.pir.md
    • plank.en.files
      • attachment.pdf
    • plank.pir.files
      • attachment.pdf
    • plank.en.md
    • plank.pir.md

Examples

Custom Title, List o' Attachments End'n 'n pdf or mp4

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

Ahoi Styled Box, Descend'n Sort Order

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

Wit' User-Defined Color an' Font Awesome Brand Ay'con

{{% attachments color="fuchsia" ay'con="fab fa-hackerrank" /%}}

Style, Color, Title an' Ay'cons

For further examples fer style, color, title an' ay'con, see th' notice shortcode documentat'n. Th' parameter be work'n th' same way fer both shorrrtcodes, besides hav'n different defaults.

Badge

Th' badge shortcode displays little markers 'n yer text wit' adjust'ble color, title an' ay'con.

Important Version6.6.6 Captain AhoiNew Awesome

Usage

While th' examples be us'n shorrrtcodes wit' named parameter ye be free t' also call this shortcode from yer own partials.

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

Parameter

Name Default Notes
style default Th' style scheme used fer th' badge.

- by severity: info, note, tip, warning
- by brand color: primary, secondary, accent
- by color: blue, green, grey, orange, red
- by special color: default, transparent
color see notes 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)
<content> <empty> Arbitrary text fer th' badge.

Examples

Style

By Severity

{{% badge style="info" %}}New{{% /badge %}}
{{% badge style="note" %}}Change{{% /badge %}}
{{% badge style="tip" %}}Optional{{% /badge %}}
{{% badge style="warning" %}}Break'n{{% /badge %}}

AhoiNew AvastChange Smarrrt ArrrseOptional ArrrBreak'n

By Brand Colors

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

AnnouncementMandatory AnnouncementOptional AnnouncementSpecial

By Color

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

ColorBlue ColorGreen ColorGrey ColorOrange ColorRed

By Special Color

{{% badge style="default" ay'con="palette" title="Color" %}}Default{{% /badge %}}
{{% badge style="transparent" ay'con="palette" title="Color" %}}Transparent{{% /badge %}}

ColorDefault ColorTransparent

Variants

Without Ay'con an' Title Text

{{% badge %}}6.6.6{{% /badge %}}
{{% badge style="info" ay'con=" " title=" " %}}Awesome{{% /badge %}}
{{% badge style="red" %}}Captain{{% /badge %}}

6.6.6 Awesome Captain

Without Ay'con

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

Version6.6.6 AhoiAwesome RankCaptain

Without Title Text

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

6.6.6 Awesome Captain

All Set

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

Version6.6.6 AhoiAwesome RankCaptain

Override fer Severity

{{% badge style="info" ay'con="rocket" title="Feature" %}}Awesome{{% /badge %}}
FeatureAwesome

Other

Wit' User-Defined Color, Font Awesome Brand Ay'con an' Marrrkdown Title an' Rrrambl'n

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

Wit' Ay'con Rrrambl'n

Ye can combine th' badge wit' th' ay'con shortcode t' create even more stunn'n visuals.

In this case ye need t' declare {{< badge >}} instead o' {{% badge %}}. Avast, that 'n this case it be not poss'ble t' put markdown 'n th' rrrambl'n.

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


Pirate
Rank
Rank Pirate
Rank
Rank Pirate

Inside o' Text

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

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

Button

Th' button shortcode displays a click'ble button wit' adjust'ble color, title an' ay'con.

Get Cap'n Hugo Get Cap'n Hugo

Usage

While th' examples be us'n shorrrtcodes wit' named parameter ye be free t' also call this shortcode from yer own partials.

{{% button href="https://gohugo.io/" %}}Get Cap'n Hugo{{% /button %}}
{{% button href="https://gohugo.io/" style="warning" ay'con="dragon" %}}Get Cap'n Hugo{{% /button %}}
{{ partial "shortcodes/button.html" (dict
    "context" .
    "href" "https://gohugo.io/"
    "content" "Get Hugo"
)}}
{{ partial "shortcodes/button.html" (dict
  "context" .
  "href" "https://gohugo.io/"
  "style" "warning"
  "icon" "dragon"
  "content" "Get Hugo"
)}}

Once th' button be clicked, it opens another browser tab fer th' given URL.

Parameter

Name Default Notes
href <empty> 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
style transparent Th' style scheme used fer th' button.

- by severity: info, note, tip, warning
- by brand color: primary, secondary, accent
- by color: blue, green, grey, orange, red
- by special color: default, transparent
color see notes 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.
target see notes Th' destinat'n frame/window if href be an URL. Otherwise th' parameter be not used. This behaves similar t' normal links. If th' parameter be not given it defaults t':

- th' sett'n o' externalLinkTarget or _blank if not set, fer any address start'n wit' http:// or https://
- no specific value fer all other links
type see notes Th' button type if href be JavaScript. Otherwise th' parameter be not used. If th' parameter be not given it defaults t' button
<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)

Examples

Style

By Severity

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

Get Cap'n Hugo Get Cap'n Hugo Get Cap'n Hugo Get Cap'n Hugo

By Brand Colors

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

Get Cap'n Hugo Get Cap'n Hugo Get Cap'n Hugo

By Color

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

Get Cap'n Hugo Get Cap'n Hugo Get Cap'n Hugo Get Cap'n Hugo Get Cap'n Hugo

By Special Color

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

Get Cap'n Hugo Get Cap'n Hugo

Ay'con

T' th' Left

{{% button href="https://gohugo.io/" ay'con="download" %}}Get Cap'n Hugo{{% /button %}}
Get Cap'n Hugo

T' th' Right

{{% button href="https://gohugo.io/" ay'con="download" iconposit'n="right" %}}Get Cap'n Hugo{{% /button %}}
Get Cap'n Hugo

Override fer Severity

{{% button href="https://gohugo.io/" ay'con="dragon" style="warning" %}}Get Cap'n Hugo{{% /button %}}
Get Cap'n Hugo

Target

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

Get Cap'n Hugo 'n same Window/Frame Get Cap'n Hugo 'n new Window/Frame (default)

Other

Wit' User-Defined Color, Font Awesome Brand Ay'con an' Marrrkdown Title

{{% button href="https://gohugo.io/" color="fuchsia" ay'con="fab fa-hackerrank" %}}Get **Cap'n Hugo**{{% /button %}}
Get Cap'n Hugo

Severity Style wit' All Defaults

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

Button t' Internal Plank

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

Button wit' JavaScript Act'n

If yer JavaScript act'n does not change th' focus afterwards, make sure t' call this.blur() 'n th' end t' unselect th' button.

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

Button within a form Element

T' use native HTML elements 'n yer Marrrkdown, add this 'n yer config.toml

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

Children

Th' children shortcode lists th' child planks o' th' current plank an' its descendants.

Usage

While th' examples be us'n shorrrtcodes wit' named parameter ye be free t' also call this shortcode from yer own partials.

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

Parameter

Name Default Notes
containerstyle ul Choose th' style used t' group all children. It could be any HTML tag name.
style li Choose th' style used t' display each descendant. It could be any HTML tag name.
showhidden false When true, child planks hidden from th' menu will be displayed as well.
descript'n false When true shows a short text under each plank 'n th' list. 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.
depth 1 Th' depth o' descendants t' display. For example, if th' value be 2, th' shortcode will display two levels o' child planks. T' get all descendants, set this value t' a high number eg. 999.
sort see notes Th' sort order o' th' displayed list.

If not set it be sorted by th' ordersectionsby sett'n o' th' ship an' th' planks frontmatter

- weight: t' sort on menu order
- title: t' sort alphabetically on menu label.

Examples

All Default

{{% children  %}}

Wit' Descript'n

{{% children descript'n="true" %}}
  • plank X

    This be a plain plank test, an' th' beginn'n o' a YAML multiline descript'n...

  • plank 1

    This be a demo child plank

  • plank 2

    This be a demo child plank wit' no descript'n. So its rrrambl'n be used as descript'n.

  • plank 3

    This be a demo child plank

Infinite Depth an' Hidden Planks

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

Head'n Styles fer Container an' Elements

{{% children containerstyle="div" style="h2" depth="3" descript'n="true" %}}

plank X

This be a plain plank test, an' th' beginn'n o' a YAML multiline descript'n...

plank 1

This be a demo child plank

plank 1-1

This be a demo child plank

plank 1-1-2

This be a demo child plank

plank 1-1-3

This be a demo child plank

plank 2

This be a demo child plank wit' no descript'n. So its rrrambl'n be used as descript'n.

plank 3

This be a demo child plank

plank 3-1

This be a plain plank test nested 'n a parent

Divs fer Group an' Element Styles

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

Subsct'ns o' Children

plank X

This be a plain demo child plank.

Subsct'ns o' plank 1

Subsct'ns o' plank 1-1

Subsct'ns o' plank 1-1-2

plank 2

This be a demo child plank wit' no descript'n.

So its rrrambl'n be used as descript'n.

Subsct'ns o' plank 3

Expand

Th' expand shortcode displays an expandable/collaps'ble section o' text.

Thank ye!
Avast

This only works 'n modern browsers flawlessly. While Internet Explorer 11 has issues 'n display'n it, th' functionality still works.

Usage

While th' examples be us'n shorrrtcodes wit' named parameter ye be free t' use positional as well or also call this shortcode from yer own partials.

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

Parameter

Name Posit'n Default Notes
title 1 "Expand me..." Arbitrary text t' appear next t' th' expand/collapse ay'con.
open 2 false When true th' rrrambl'n text will be initially shown as expanded.
<content> <empty> Arbitrary text t' be displayed on expand.

Examples

All Defaults

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

Initially Expanded

{{% expand title="Expand me..." open="true" %}}No need t' press ye!{{% /expand %}}
No need t' press ye!

Arbitrary Text

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

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

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

> th' possibilities be endless (almost - includ'n other shorrrtcodes may or may not work)
{{% /expand %}}

Ye can add standard markdown rules:

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

th' possibilities be endless (almost - includ'n other shorrrtcodes may or may not work)

Icon

Th' ay'con shortcode displays ay'cons us'n th' Font Awesome library.

Usage

While th' examples be us'n shorrrtcodes wit' positional parameter ye be free t' also call this shortcode from yer own partials.

{{% ay'con ay'con="exclamation-triangle" %}}
{{% ay'con ay'con="angle-double-up" %}}
{{% ay'con ay'con="skull-crossbones" %}}
{{% ay'con exclamat'n-triangle %}}
{{% ay'con angle-do'ble-up %}}
{{% ay'con skull-crossbones %}}
{{ partial "shortcodes/icon.html" (dict
    "context" .
    "icon" "exclamation-triangle"
)}}
{{ partial "shortcodes/icon.html" (dict
    "context" .
    "icon" "angle-double-up"
)}}
{{ partial "shortcodes/icon.html" (dict
    "context" .
    "icon" "skull-crossbones"
)}}

Parameter

Name Posit'n Default Notes
ay'con 1 <empty> Font Awesome ay'con name t' be displayed. It will be displayed 'n th' text color o' its accord'n context.

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.

Customis'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)
  • Increase or decrease size
  • Rotate
  • Combine wit' other ay'cons

Check th' full documentat'n on web fonts wit' CSS fer more.

Examples

Standard Usage

Built wit' {{% ay'con heart %}} by Relearrrn an' Cap'n Hugo

Built wit' by Relearrrn an' Cap'n Hugo

Advanced HTML Usage

While th' shortcode simplyfies us'n standard ay'cons, th' ay'con customisat'n an' other advanced features o' th' Font Awesome library requires ye t' use HTML directly. Just paste th' <i> HTML into marrrkup an' Font Awesome will board th' relevant ay'con.

Built wit' <i class="fas fa-heart"></i> by Relearrrn an' Cap'n Hugo

Built wit' by Relearrrn an' Cap'n Hugo

Include

Th' include shortcode includes other files from yer project inside o' th' current plank.

Usage

While th' examples be us'n shorrrtcodes wit' named parameter ye be free t' use positional aswell or also call this shortcode from yer own partials.

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

Th' included files can even contain Marrrkdown an' will be taken into account when generat'n th' t'ble o' contents.

Parameter

Name Posit'n Default Notes
file 1 <empty> Th' path t' th' file t' be included. Path resolut'n adheres t' Hugo’s build-in readFile funct'n
hidefirsthead'n 2 false 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.

Examples

Arbitrary Rrrambl'n

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

Ye can add standard markdown rules:

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

th' possibilities be endless (almost - includ'n other shorrrtcodes may or may not work) (almost - includ'n other shorrrtcodes may or may not work)

Math

Arrr! Pirrrates

Fello' pirrrates, grog made us dizzy! Be awarrre some stuff may not work in this trrranslat'n. Like see'n Merrrmaids, do'n math or chemistrrry, writ'n docs and stuff.

Th' math shortcode generates beautiful formatted math an' chemical formulae us'n th' MathJax library.

$$\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)$$
Avast

This only works 'n modern browsers.

Usage

While th' examples be us'n shorrrtcodes wit' named parameter it be recommended t' use codefences instead. This be because more an' more other software supports Math codefences (eg. GitHub) an' so yer markdown becomes more port'ble.

Ye be free t' also call this shortcode from yer own partials.

Avast

T' use codefence rules ye have t' turn off guessSyntax fer th' marrrkup.highlight sett'n (see th' configurat'n section).

```math { align="center" }
$$\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)$$
```
{{< math align="center" >}}
$$\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)$$
{{< /math >}}
{{ partial "shortcodes/math.html" (dict
  "context" .
  "content" "$$left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)$$"
  "align"   "center"
)}}

Parameter

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

Configurat'n

MathJax be configured wit' default sett'ns. Ye can cust'mize MathJax’s default sett'ns fer all o' yer files thru a JSON object 'n yer config.toml or override these sett'ns per plank thru yer planks frontmatter.

Th' JSON object o' yer config.toml / frontmatter be forwarded into MathJax’s configurat'n object.

See MathJax documentat'n fer all allowed sett'ns.

Avast

T' use codefence rules ye have t' turn off guessSyntax fer th' marrrkup.highlight sett'n.

Global Configurat'n File

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

[marrrkup]
  [marrrkup.highlight]
    # if `guessSyntax = true`, there will be no unstyled code even if no language
    # was given BUT Merrrmaid an' Math codefences will not work anymore! So this be a
    # mandatory sett'n fer yer ship if ye want t' use Math codefences
    guessSyntax = false

Page’s Frontmatter

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

Examples

Inline Math

Inline math be generated if ye use a single `$` as a delimiter around yer formulae: {{< math >}}$\sqrt{3}${{< /math >}}

Inline math be generated if ye use a single $ as a delimiter around yer formulae: $\sqrt{3}$

Blocklevel Math wit' Right Alignment

If ye delimit yer formulae by two consecutive `$$` it generates a new block.

{{< math align="right" >}}
$$\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)$$
{{< /math >}}

If ye delimit yer formulae by two consecutive $$ it generates a new block.

$$\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)$$

Codefence

Ye can also use codefences.

```math
$$\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)$$
```
$$\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)$$

Chemical Formulae

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

Merrrmaid

Arrr! Pirrrates

Fello' pirrrates, grog made us dizzy! Be awarrre some stuff may not work in this trrranslat'n. Like see'n Merrrmaids, do'n math or chemistrrry, writ'n docs and stuff.

Th' mermaid shortcode generates diagrams an' flowcharts from text, 'n a similar manner as Marrrkdown us'n th' Merrrmaid library.

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

This only works 'n modern browsers.

Arrr

Due t' limitat'ns wit' Merrrmaid, it be currently not poss'ble t' use Merrrmaid code fences 'n an initially collapsed expand shortcode. This be a know issue an' can’t be fixed by this theme.

Usage

While th' examples be us'n shorrrtcodes wit' named parameter it be recommended t' use codefences instead. This be because more an' more other software supports Merrrmaid codefences (eg. GitHub) an' so yer markdown becomes more port'ble.

Ye be free t' also call this shortcode from yer own partials.

Avast

T' use codefence rules ye have t' turn off guessSyntax fer th' marrrkup.highlight sett'n (see th' configurat'n section).

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

Th' generated graphs can be be panned by dragg'n them an' zoomed by us'n th' mousewheel. On mobile devices ye can use finger gestures.

Parameter

Name Default Notes
align center 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' th' ship or th' planks frontmatter or false if not set at all.

- false: no pan or zoom
- true: pan an' zoom active
<content> <empty> Yer Merrrmaid graph.

Configurat'n

Merrrmaid be configured wit' default sett'ns. Ye can cust'mize Mermaid’s default sett'ns fer all o' yer files thru a JSON object 'n yer config.toml, override these sett'ns per plank thru yer planks frontmatter or override these sett'n per diagramm thru diagram directives.

Th' JSON object o' yer config.toml / frontmatter be forwarded into Mermaid’s mermaid.initialize() funct'n.

See Merrrmaid documentat'n fer all allowed sett'ns.

Th' theme sett'n can also be set by yer used color variant. This will be th' sitewide default an' can - again - be overridden by yer sett'ns 'n config.toml, frontmatter or diagram directives.

Avast

T' use codefence rules ye have t' turn off guessSyntax fer th' marrrkup.highlight sett'n.

Global Configurat'n File

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

[marrrkup]
  [marrrkup.highlight]
    # if `guessSyntax = true`, there will be no unstyled code even if no language
    # was given BUT Merrrmaid an' Math codefences will not work anymore! So this be a
    # mandatory sett'n fer yer ship if ye want t' use Merrrmaid codefences
    guessSyntax = false

Page’s Frontmatter

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

Examples

Flowchart wit' Non-Default Merrrmaid Theme

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

Sequence Diagram 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
    Avast right o' John: Rational thoughts!
    John-->>Alice: Great!
    John->>Bob: How about ye?
    Bob-->>John: Jolly bloody!
{{< /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!

Class Diagram wit' Codefence Rules

```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 Aligned t' th' Right

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

Entity Relationship Model

{{< mermaid >}}
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"
{{< /mermaid >}}
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
{{< /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

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, aft des2, 5d
        Future task2              :         des4, aft des3, 5d
        section Critical tasks
        Completed task 'n th' critical line :crit, done, 2014-01-06,24h
        Implement parser an' jison          :crit, done, aft 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 >}}
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, aft des2, 5d Future task2 : des4, aft des3, 5d section Critical tasks Completed task 'n th' critical line :crit, done, 2014-01-06,24h Implement parser an' jison :crit, done, aft 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

Pie Chart without Zoom

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

Requirement Diagram

{{< mermaid >}}
    requirementDiagram

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

    element test_entity {
    type: simulat'n
    }

    test_entity - satisfies -> test_req
{{< /mermaid >}}
requirementDiagram requirement test_req { id: 1 text: th' test text. risk: high verifymethod: test } element test_entity { type: simulat'n } test_entity - satisfies -> test_req

Git Graph

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

C4 Diagrams

{{< mermaid >}}
C4Context
    title System Context diagram 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, transact'ns, 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 >}}
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, transact'ns, 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
      ::ay'con(fa fa-book)
      Popularisat'n
        British popular psychology author Tony Buzan
    Research
      On effectiveness<br/>an' features
      On Automatic creat'n
        Uses
            Creative techniques
            Strategic plann'n
            Argument mapp'n
    Tools
      Pen an' paper
      Merrrmaid
{{< /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
{{< /mermaid >}}
timeline title History o' Social Media Platform 2002 : LinkedIn 2004 : Facebook : Google 2005 : Youtube 2006 : Twitter

Notice

Th' notice shortcode shows various types o' disclaimers wit' adjust'ble color, title an' ay'con t' help ye structure yer plank.

There may be pirates

It be all about th' boxes.

Usage

While th' examples be us'n shorrrtcodes wit' named parameter ye be free t' use positional as well or also call this shortcode from yer own partials.

{{% notice style="primary" title="There may be pirates" ay'con="skull-crossbones" %}}
It be all about th' boxes.
{{% /notice %}}
{{% notice primary "There may be pirates" "skull-crossbones" %}}
It be all about th' boxes.
{{% /notice %}}
{{ partial "shortcodes/notice.html" (dict
  "context" .
  "style" "primary"
  "title" "There may be pirates"
  "icon" "skull-crossbones"
  "content" "It be all about th' boxes."
)}}

Parameter

Name Posit'n Default Notes
style 1 default Th' style scheme used fer th' box.

- by severity: info, note, tip, warning
- by brand color: primary, secondary, accent
- by color: blue, green, grey, orange, red
- by special color: default, transparent
color see notes 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)
<content> <empty> Arbitrary text t' be displayed 'n box.

Examples

By Severity

Ahoi wit' marrrkup

{{% notice style="info" %}}
An **informat'n** disclaimer

Ye can add standard markdown rules:

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

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

> th' possibilities be endless (almost - includ'n other shorrrtcodes may or may not work)
{{% /notice %}}
Ahoi

An informat'n disclaimer

Ye can add standard markdown rules:

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

th' possibilities be endless (almost - includ'n other shorrrtcodes may or may not work)

Avast

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

A notice disclaimer

Smarrrt Arrrse

{{% notice style="tip" %}}
A **tip** disclaimer
Smarrrt Arrrse

A tip disclaimer

Arrr

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

A warning disclaimer

Arrr wit' Non-Default Title an' Ay'con

{{% notice style="warning" title="Here be dragons" ay'con="dragon" %}}
A **warning** disclaimer
{{% /notice %}}
Here be dragons

A warning disclaimer

Arrr without a Title an' Ay'con

{{% notice style="warning" title=" " ay'con=" " %}}
A **warning** disclaimer
{{% /notice %}}

A warning disclaimer

By Brand Colors

Primary wit' Title only

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

A primary disclaimer

Secondary wit' Ay'con only

{{% notice style="secondary" ay'con="stopwatch" %}}
A **secondary** disclaimer
{{% /notice %}}

A secondary disclaimer

Accent

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

An accent disclaimer

By Color

Blue without a Title an' Ay'con

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

A blue disclaimer

Green wit' Title only

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

A green disclaimer

Grey wit' Ay'con only

{{% notice style="grey" ay'con="bug" %}}
A **grey** disclaimer
{{% /notice %}}

A grey disclaimer

Orange wit' Title an' Ay'con

{{% notice style="orange" title="Orange" ay'con="bug" %}}
A **orange** disclaimer
{{% /notice %}}
Orange

A orange disclaimer

Red without a Title an' Ay'con

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

A red disclaimer

By Special Color

Default wit' Positional Parameter

{{% notice default "Pay Attent'n t' this Avast!" "skull-crossbones" %}}
Some serious informat'n.
{{% /notice %}}
Pay Attent'n t' this Avast!

Some serious informat'n.

Transparent wit' Title an' Ay'con

{{% notice style="transparent" title="Pay Attent'n t' this Avast!" ay'con="skull-crossbones" %}}
Some serious informat'n.
{{% /notice %}}
Pay Attent'n t' this Avast!

Some serious informat'n.

Wit' User-Defined Color, Font Awesome Brand Ay'con an' Marrrkdown Title

{{% notice color="fuchsia" title="**Hugo**" ay'con="fab fa-hackerrank" %}}
Victor? Be it ye?
{{% /notice %}}
Cap'n Hugo

Victor? Be it ye?

OpenAPI

Arrr! Pirrrates

Fello' pirrrates, grog made us dizzy! Be awarrre some stuff may not work in this trrranslat'n. Like see'n Merrrmaids, do'n math or chemistrrry, writ'n docs and stuff.

Th' openapi shortcode uses th' Swagger UI library t' display yer OpenAPI / Swagger specificat'ns.

Avast

This only works 'n modern browsers.

Usage

While th' examples be us'n shorrrtcodes wit' named parameter ye be free t' also call this shortcode from yer own partials.

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

Parameter

Name Default Notes
src <empty> Th' URL t' th' OpenAPI specificat'n file. This can be relative t' th' URL o' yer plank if it be a leaf or branch bundle.
Avast

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.

Example

Us'n Local File

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

Ship param

Th' siteparam shortcode prints values o' ship params.

Usage

While th' examples be us'n shorrrtcodes wit' named parameter ye be free t' use positional aswell or call this shortcode from yer own partials.

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

Parameter

Name Posit'n Default Notes
name 1 <empty> Th' name o' th' ship param t' be displayed.

Examples

editURL from config.toml

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

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

Tab

Ye can use a tab shortcode t' display a single tab.

This be especially useful if ye want t' flag yer code example wit' an explicit language.

If ye want multiple tabs grouped together ye can wrap yer tabs into th' tabs shortcode.

printf("Hello World!");

Usage

While th' examples be us'n shorrrtcodes wit' named parameter ye be free t' also call this shortcode from yer own partials.

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

Parameter

Name Default Notes
name <empty> Arbitrary text fer th' name o' th' tab.
<content> <empty> Arbitrary text t' be displayed 'n th' tab.

Examples

Code wit' collapsed margins

printf("Hello World!");

Mixed rrrambl'n

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

printf("Hello World!");

Tabs

Th' tabs shortcode displays arbitrary rrrambl'n 'n an unlimited number o' tabs.

This comes 'n handy eg. fer provid'n code snippets fer multiple languages.

If ye just want a single tab ye can instead call th' tab shortcode standalone.

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

Usage

While th' examples be us'n shorrrtcodes wit' named parameter ye be free t' also call this shortcode from yer own partials.

See th' tab shortcode fer a descript'n o' th' parameter fer nested tabs.

{{< tabs >}}
{{% tab name="python" %}}
```python
print("Hello World!")
```
{{% /tab %}}
{{% tab name="bash" %}}
```bash
echo "Hello World!"
```
{{% /tab %}}
{{< /tabs >}}
{{ partial "shortcodes/tabs.html" (dict
  "context" .
  "content" (slice
    (dict
      "name" "python"
      "content" ("```python\nprint(\"Hello World!\")\n```" | markdownify)
    )
    (dict
      "name" "bash"
      "content" ("```bash\necho \"Hello World!\"\n```" | markdownify)
    )
  )
)}}

Parameter

Name Default Notes
groupid <random> Arbitrary name o' th' group th' tab view belongs t'.

Tab views wit' th' same groupid sychr'nize their selected tab. Th' tab select'n be restored automatically based on th' groupid fer tab view. If th' selected tab can not be found 'n a tab group th' first tab be selected instead.

This sychronizat'n applies t' th' whole ship!
<content> <empty> Arbitrary number o' tabs defined wit' th' tab sub-shortcode.

Examples

Behavior o' th' groupid

See what happens t' th' tab views while ye select different tabs.

While press'n a tab o' group A switches all tab views o' group A 'n sync (if th' tab be available), th' tabs o' group B be left untouched.

{{< tabs groupid="a" >}}
{{% tab name="json" %}}
```json
{ "Hello": "World" }
```
{{% /tab %}}
{{% tab name="_**XML**_ stuff" %}}
```xml
<Hello>World</Hello>
```
{{% /tab %}}
{{% tab name="properties" %}}
```properties
Hello = World
```
{{% /tab %}}
{{< /tabs >}}
{{< tabs groupid="a" >}}
{{% tab name="json" %}}
```json
{ "Hello": "World" }
```
{{% /tab %}}
{{% tab name="XML stuff" %}}
```xml
<Hello>World</Hello>
```
{{% /tab %}}
{{< /tabs >}}
{{< tabs groupid="b" >}}
{{% tab name="json" %}}
```json
{ "Hello": "World" }
```
{{% /tab %}}
{{% tab name="XML stuff" %}}
```xml
<Hello>World</Hello>
```
{{% /tab %}}
{{< /tabs >}}

Group A, Tab View 1

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

Group A, Tab View 2

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

Group B

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

Nested Tabs

In case ye want t' nest tabs, th' parent tab that contains th' subtabs 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.

{{< tabs groupid="main" >}}
{{< tab name="Text" >}}
  Simple text be poss'ble here...
  {{< tabs groupid="tabs-example-language" >}}
  {{% tab name="python" %}}
  Python be **super** easy.

  - most o' th' time.
  - if ye don't want t' output unicode
  {{% /tab %}}
  {{% tab name="bash" %}}
  Bash be fer **hackers**.
  {{% /tab %}}
  {{< /tabs >}}
{{< /tab >}}

{{< tab name="Code" >}}
  ...but no markdown
  {{< tabs groupid="tabs-example-language" >}}
  {{% tab name="python" %}}
  ```python
  print("Hello World!")
  ```
  {{% /tab %}}
  {{% tab name="bash" %}}
  ```bash
  echo "Hello World!"
  ```
  {{% /tab %}}
  {{< /tabs >}}
{{< /tab >}}
{{< /tabs >}}
Simple text be poss'ble here...

Python be super easy.

  • most o' th' time.
  • if ye don’t want t' output unicode

Bash be fer hackers.

...but no markdown
print("Hello World!")
echo "Hello World!"