Fello' pirrates, be awarrre some stuff may not work fer us in this trrranslat'n. Like table of rrramblings, see'ng Merrrmaids, do'ng math or chemistrrry and stuff.
Chapter 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 shorrrtcode be a simple snippet inside a plank.
Th' Relearrrn theme provides multiple shorrrtcodes on top o' exist'n ones.
Fello' pirrates, be awarrre some stuff may not work fer us in this trrranslat'n. Like table of rrramblings, see'ng Merrrmaids, do'ng math or chemistrrry and stuff.
Th' attachments shorrrtcode displays a list o' files attached t' a plank wit' adjust'ble color, title an' ay'con.
For further examples fer style, title an' ay'con, see th' notice shorrrtcode documentat'n. Th' parameter be work'n th' same way fer both shorrrtcodes, besides hav'n different defaults.
Button
Arrr! Pirrrates
Fello' pirrates, be awarrre some stuff may not work fer us in this trrranslat'n. Like table of rrramblings, see'ng Merrrmaids, do'ng math or chemistrrry and stuff.
Th' button shorrrtcode displays a click'ble button wit' adjust'ble color, title an' ay'con.
Once th' button be clicked, it opens another browser tab fer th' given URL.
Parameter
Name
Default
Notes
href
<empty>
Th' destinat'n URL fer th' button. If this parameter be not set, th' button will do noth'n but be still displayed as click'ble.
style
transparent
Th' color scheme used t' paint th' button.
- by severity: info, note, tip, warning - by brand color: primary, secondary - by color: blue, green, grey, orange, red - by special color: default, transparent
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 colors: <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
Arbitray 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 colors: <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)
Fello' pirrates, be awarrre some stuff may not work fer us in this trrranslat'n. Like table of rrramblings, see'ng Merrrmaids, do'ng math or chemistrrry and stuff.
Th' children shorrrtcode lists th' child planks o' a plank an' its descendants .
Specify th' plank name (section name) t' display children fer.
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 aswell.
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' shorrrtcode 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.
Fello' pirrates, be awarrre some stuff may not work fer us in this trrranslat'n. Like table of rrramblings, see'ng Merrrmaids, do'ng math or chemistrrry and stuff.
This be a plain demo child plank.
Plank 1
Arrr! Pirrrates
Fello' pirrates, be awarrre some stuff may not work fer us in this trrranslat'n. Like table of rrramblings, see'ng Merrrmaids, do'ng math or chemistrrry and stuff.
Fello' pirrates, be awarrre some stuff may not work fer us in this trrranslat'n. Like table of rrramblings, see'ng Merrrmaids, do'ng math or chemistrrry and stuff.
This be a demo child plank wit' a hidden child. Ye can still access th' hidden child directly or via th' search.
Fello' pirrates, be awarrre some stuff may not work fer us in this trrranslat'n. Like table of rrramblings, see'ng Merrrmaids, do'ng math or chemistrrry and stuff.
Fello' pirrates, be awarrre some stuff may not work fer us in this trrranslat'n. Like table of rrramblings, see'ng Merrrmaids, do'ng math or chemistrrry and stuff.
This be a plain demo child plank.
Plank 1-1-2-2
Arrr! Pirrrates
Fello' pirrates, be awarrre some stuff may not work fer us in this trrranslat'n. Like table of rrramblings, see'ng Merrrmaids, do'ng math or chemistrrry and stuff.
This be a plain demo child plank.
Plank 1-1-3
Arrr! Pirrrates
Fello' pirrates, be awarrre some stuff may not work fer us in this trrranslat'n. Like table of rrramblings, see'ng Merrrmaids, do'ng math or chemistrrry and stuff.
This be a plain demo child plank.
Plank 2
Arrr! Pirrrates
Fello' pirrates, be awarrre some stuff may not work fer us in this trrranslat'n. Like table of rrramblings, see'ng Merrrmaids, do'ng math or chemistrrry and stuff.
This be a demo child plank wit' no descript'n.
So its rrrambl'n be used as descript'n.
Plank 3
Arrr! Pirrrates
Fello' pirrates, be awarrre some stuff may not work fer us in this trrranslat'n. Like table of rrramblings, see'ng Merrrmaids, do'ng math or chemistrrry and stuff.
Fello' pirrates, be awarrre some stuff may not work fer us in this trrranslat'n. Like table of rrramblings, see'ng Merrrmaids, do'ng math or chemistrrry and stuff.
This be a plain demo child plank.
Expand
Arrr! Pirrrates
Fello' pirrates, be awarrre some stuff may not work fer us in this trrranslat'n. Like table of rrramblings, see'ng Merrrmaids, do'ng math or chemistrrry and stuff.
Th' expand shorrrtcode displays an expandable/collaps'ble section o' text.
{{%expandtitle="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'possiblitiesbeendless(almost-includ'nothershorrrtcodesmayormaynotwork){{%/expand%}}
th' possiblities be endless (almost - includ'n other shorrrtcodes may or may not work)
Include
Arrr! Pirrrates
Fello' pirrates, be awarrre some stuff may not work fer us in this trrranslat'n. Like table of rrramblings, see'ng Merrrmaids, do'ng math or chemistrrry and stuff.
Th' include shorrrtcode 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 shorrrtcode from yer own partials.
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.
th' possiblities 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' pirrates, be awarrre some stuff may not work fer us in this trrranslat'n. Like table of rrramblings, see'ng Merrrmaids, do'ng math or chemistrrry and stuff.
Th' math shorrrtcode generates beautiful formatted math an' chemical formulae us'n th' MathJax library.
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 shorrrtcode 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).
Parameter be only supported when us'n shorrrtcode or partial rules. Defaults be used when us'n codefence rules.
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.
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 mermaid an' math codefences will not work anymore! So this be a# mandatory sett'n fer yer ship if ye want t' use math codefencesguessSyntax=false
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' Left Alignment
If ye delimit yer formulae by two consecutive `$$` it generates a new block.
{{<mathalign="left">}}
$$\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.
Fello' pirrates, be awarrre some stuff may not work fer us in this trrranslat'n. Like table of rrramblings, see'ng Merrrmaids, do'ng math or chemistrrry and stuff.
Th' mermaid shorrrtcode 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 shorrrtcode. 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 shorrrtcode 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
graph LR;
If --> Then
Then --> Else
```
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
Parameter be only supported when us'n shorrrtcode or partial rules. Defaults be used when us'n codefence rules.
Name
Default
Notes
align
center
Allowed values be left, center or right.
<content>
<empty>
Yer mermaid 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.
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\" }"[marrrkup][marrrkup.highlight]# if `guessSyntax = true`, there will be no unstyled code even if no language# was given BUT mermaid an' math codefences will not work anymore! So this be a# mandatory sett'n fer yer ship if ye want t' use mermaid codefencesguessSyntax=false
sequenceDiagram
participant Alice
participant Bob
Alice->>John: Hello John, how be ye?
loop Healthcheck
John->John: Fight against hypochondria
end
Note right of John: Rational thoughts prevail...
John-->Alice: Great!
John->Bob: How about ye?
Bob-->John: Jolly bloody!
```mermaid
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
Notice
Arrr! Pirrrates
Fello' pirrates, be awarrre some stuff may not work fer us in this trrranslat'n. Like table of rrramblings, see'ng Merrrmaids, do'ng math or chemistrrry and stuff.
Th' notice shorrrtcode 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 aswell or also call this shorrrtcode from yer own partials.
{{%noticestyle="primary"title="There may be pirates"ay'con="skull-crossbones"%}}Itbeallaboutth'boxes.{{%/notice%}}
{{%noticeprimary"There may be pirates""skull-crossbones"%}}Itbeallaboutth'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' color scheme used t' highlight th' box rrrambl'n.
- by severity: info, note, tip, warning - by brand color: primary, secondary - by color: blue, green, grey, orange, red - by special color: default, transparent
title
2
see notes
Arbitray 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 colors: <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 colors: <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>
Arbitray text t' be displayed 'n box.
Examples
By Severity
Ahoi wit' marrrkup
{{%noticestyle="info"%}}An**informat'n**disclaimerYecanaddstandardmarkdownrules:-multipleparagraphs-bulletpointlists-_emphasized_,**bold**an'even***boldemphasized***text-[links](https://example.com)
-etc.```plaintext
...and even source code
```>th'possiblitiesbeendless(almost-includ'nothershorrrtcodesmayormaynotwork){{%/notice%}}
{{%noticestyle="default"title"Pay Attent'n t' this Avast!"ay'con="skull-crossbones"%}}Someseriousinformat'n.{{%/notice%}}
Pay Attent'n t' this Avast!
Some serious informat'n.
Transparent wit' Title an' Ay'con
{{%noticestyle="transparent"title"Pay Attent'n t' this Avast!"ay'con="skull-crossbones"%}}Someseriousinformat'n.{{%/notice%}}
Pay Attent'n t' this Avast!
Some serious informat'n.
Ship param
Arrr! Pirrrates
Fello' pirrates, be awarrre some stuff may not work fer us in this trrranslat'n. Like table of rrramblings, see'ng Merrrmaids, do'ng math or chemistrrry and stuff.
Th' siteparam shorrrtcode 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 shorrrtcode from yer own partials.
Fello' pirrates, be awarrre some stuff may not work fer us in this trrranslat'n. Like table of rrramblings, see'ng Merrrmaids, do'ng math or chemistrrry and stuff.
This shorrrtcode uses th' RapiDoc library t' display yer Swagger / OpenAPI 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 shorrrtcode from yer own partials.
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.
Configurat'n
Swagger be configured wit' default sett'ns. Ye can cust'mize Swagger’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 Swagger’s initializat'n. At th' moment, only th' theme sett'n be supported.
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 or frontmatter.
Fello' pirrates, be awarrre some stuff may not work fer us in this trrranslat'n. Like table of rrramblings, see'ng Merrrmaids, do'ng math or chemistrrry and stuff.
Th' tabs shorrrtcode displays arbitrary rrrambl'n 'n unlimited number o' tabs. This comes 'n handy eg. fer provid'n code snippets fer multiple languages or provid'n configurat'n 'n different formats.
print("Hello World!")
echo"Hello World!"
Usage
While th' examples be us'n shorrrtcodes wit' named parameter ye be free t' also call this shorrrtcode from yer own partials.
Arbitrary name o' th' group th' tab view belongs t'.
Tab views wit' th' same groupid sychr'nize their selected tab. This sychronizat'n applies t' th' whole ship!
<content>
<empty>
Arbitrary number o' tabs defined wit' th' tab sub-shortcode.
Avast
When us'n tab views wit' different rrrambl'n sets, make sure t' use a common groupid fer equal sets o' tabs but distinct groupid fer different sets.
Th' tab select'n be restored automatically based on th' groupid an' if it cannot find a tab item because it came from th' 'default' group on a different plank then th' first tab be selected instead.
