Fello' pirrates, be awarrre some featurrres may not work fer us in this trrranslat'n. Like table of rrramblings, some Merrrmaids 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.
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 featurrres may not work fer us in this trrranslat'n. Like table of rrramblings, some Merrrmaids 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 featurrres may not work fer us in this trrranslat'n. Like table of rrramblings, some Merrrmaids and stuff.
Th' children shorrrtcode lists th' child planks o' a plank an' its descendants .
Usage
{{%children%}}
Parameter
Name
Default
Notes
plank
<current>
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.
{{%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%}}
When false 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)
Merrrmaid
Arrr! Pirrrates
Fello' pirrates, be awarrre some featurrres may not work fer us in this trrranslat'n. Like table of rrramblings, some Merrrmaids and stuff.
Wit' th' Merrrmaid library an' shorrrtcode, ye can generate diagrams an' flowcharts from text, 'n a similar manner as Marrrkdown.
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
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.
While th' examples be us'n shorrrtcode rules it be recommended t' use codefence rules instead. This be because more an' more other software supports Merrrmaid codefences (eg. GitHub) an' so yer markdown becomes more port'ble.
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
```
Parameter be only supported when us'n shorrrtcode 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 set t' `guessSyntax = true`, there will be no unstyled code even if no language# was given BUT mermaid code fences will not work anymore! So this be a mandatory# sett'n fer yer shipguessSyntax=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 featurrres may not work fer us in this trrranslat'n. Like table of rrramblings, some Merrrmaids 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 named parameter ye be free t' use positional aswell.
{{%noticestyle="primary"title="There may be pirates"ay'con="skull-crossbones"%}}Itbeallaboutth'boxes.{{%/notice%}}
{{%noticeprimary"There may be pirates""skull-crossbones"%}}Itbeallaboutth'boxes.{{%/notice%}}
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)
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 featurrres may not work fer us in this trrranslat'n. Like table of rrramblings, some Merrrmaids 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.
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.
Arrr
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 all tabs will be empty at first!
