Hugo uses Markdown for its simple content format. However, there are a lot of things that Markdown doesn’t support well. You could use pure HTML to expand possibilities.
But this happens to be a bad idea. Everyone uses Markdown because it’s pure and simple to read even non-rendered. You should avoid HTML to keep it as simple as possible.
To avoid this limitations, Hugo created shortcodes. A shortcode is a simple snippet inside a page.
The Relearn theme provides multiple shortcodes on top of existing ones.
For further examples for style, title and icon, see the notice shortcode documentation. The parameter are working the same way for both shortcodes, besides having different defaults.
Button
The button shortcode displays a clickable button with adjustable color, title and icon.
Once the button is clicked, it opens another browser tab for the given URL.
Parameter
Name
Default
Notes
href
<empty>
The destination URL for the button. If this parameter is not set, the button will do nothing but is still displayed as clickable.
style
transparent
The color scheme used to paint the button.
- by severity: info, note, tip, warning - by brand color: primary, secondary - by color: blue, green, grey, orange, red - by special color: default, transparent
icon
see notes
Font Awesome icon name set to the left of the title. Depending on the style there may be a default icon. Any given value will overwrite the default.
- for severity styles: a nice matching icon for the severity - for all other colors: <empty>
If you want no icon for a severity style, you have to set this parameter to " " (a non empty string filled with spaces)
iconposition
left
Places the icon to the left or right of the title.
<content>
see notes
Arbitrary text for the button title. Depending on the style there may be a default title. Any given value will overwrite the default.
- for severity styles: the matching title for the severity - for all other colors: <empty>
If you want no title for a severity style, you have to set this parameter to " " (a non empty string filled with spaces)
Choose the style used to group all children. It could be any HTML tag name.
style
li
Choose the style used to display each descendant. It could be any HTML tag name.
showhidden
false
When true, child pages hidden from the menu will be displayed as well.
description
false
When true shows a short text under each page in the list. When no description or summary exists for the page, the first 70 words of the content is taken - read more info about summaries on gohugo.io.
depth
1
The depth of descendants to display. For example, if the value is 2, the shortcode will display two levels of child pages. To get all descendants, set this value to a high number eg. 999.
sort
see notes
The sort order of the displayed list.
If not set it is sorted by the ordersectionsby setting of the site and the pages frontmatter
- weight: to sort on menu order - title: to sort alphabetically on menu label.
While the examples are using shortcodes with named parameter you are free to use positional as well or also call this shortcode from your own partials.
{{%expandtitle="Show me almost endless possibilities"%}}Youcanaddstandardmarkdownsyntax:-multipleparagraphs-bulletpointlists-_emphasized_,**bold**andeven**_boldemphasized_**text-[links](https://example.com)
-etc.```plaintext
...and even source code
```>thepossibilitiesareendless(almost-includingothershortcodesmayormaynotwork){{%/expand%}}
When true and the included file contains headings, the first heading will be hidden. This comes in handy, eg. if you include otherwise standalone Markdown files.
While the examples are using shortcodes with named parameter it is recommended to use codefences instead. This is because more and more other software supports Math codefences (eg. GitHub) and so your markdown becomes more portable.
You are free to also call this shortcode from your own partials.
Note
To use codefence syntax you have to turn off guessSyntax for the markup.highlight setting (see the configuration section).
Parameter are only supported when using shortcode or partial syntax. Defaults are used when using codefence syntax.
Name
Default
Notes
align
center
Allowed values are left, center or right.
<content>
<empty>
Your formuale.
Configuration
MathJax is configured with default settings. You can customize MathJax’s default settings for all of your files thru a JSON object in your config.toml or override these settings per page thru your pages frontmatter.
The JSON object of your config.toml / frontmatter is forwarded into MathJax’s configuration object.
To use codefence syntax you have to turn off guessSyntax for the markup.highlight setting.
Global Configuration File
[params]mathJaxInitialize="{ \"chtml\": { \"displayAlign\": \"left\" } }"[markup][markup.highlight]# if `guessSyntax = true`, there will be no unstyled code even if no language# was given BUT Mermaid and Math codefences will not work anymore! So this is a# mandatory setting for your site if you want to use Math codefencesguessSyntax=false
Inline math is generated if you use a single `$` as a delimiter around your formulae: {{<math>}}$\sqrt{3}${{</math>}}
Inline math is generated if you use a single $ as a delimiter around your formulae:
$\sqrt{3}$
Blocklevel Math with Left Alignment
If you delimit your 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 you delimit your formulae by two consecutive $$ it generates a new block.
The mermaid shortcode generates diagrams and flowcharts from text, in a similar manner as Markdown using the Mermaid library.
graph LR;
If --> Then
Then --> Else
Note
This only works in modern browsers.
Warning
Due to limitations with Mermaid, it is currently not possible to use Mermaid code fences in an initially collapsed expand shortcode. This is a know issue and can’t be fixed by this theme.
Usage
While the examples are using shortcodes with named parameter it is recommended to use codefences instead. This is because more and more other software supports Mermaid codefences (eg. GitHub) and so your markdown becomes more portable.
You are free to also call this shortcode from your own partials.
Note
To use codefence syntax you have to turn off guessSyntax for the markup.highlight setting (see the configuration section).
```mermaid
graph LR;
If --> Then
Then --> Else
```
The generated graphs can be be panned by dragging them and zoomed by using the mousewheel. On mobile devices you can use finger gestures.
Parameter
Parameter are only supported when using shortcode or partial syntax. Defaults are used when using codefence syntax.
Name
Default
Notes
align
center
Allowed values are left, center or right.
<content>
<empty>
Your Mermaid graph.
Configuration
Mermaid is configured with default settings. You can customize Mermaid’s default settings for all of your files thru a JSON object in your config.toml, override these settings per page thru your pages frontmatter or override these setting per diagramm thru diagram directives.
The JSON object of your config.toml / frontmatter is forwarded into Mermaid’s mermaid.initialize() function.
The theme setting can also be set by your used color variant. This will be the sitewide default and can - again - be overridden by your settings in config.toml, frontmatter or diagram directives.
Note
To use codefence syntax you have to turn off guessSyntax for the markup.highlight setting.
Global Configuration File
[params]mermaidInitialize="{ \"theme\": \"dark\" }"[markup][markup.highlight]# if `guessSyntax = true`, there will be no unstyled code even if no language# was given BUT Mermaid and Math codefences will not work anymore! So this is a# mandatory setting for your site if you want to use Mermaid codefencesguessSyntax=false
sequenceDiagram
participant Alice
participant Bob
Alice->>John: Hello John, how are you?
loop Healthcheck
John->John: Fight against hypochondria
end
Note right of John: Rational thoughts <br>prevail...
John-->Alice: Great!
John->Bob: How about you?
Bob-->John: Jolly good!
gantt
dateFormat YYYY-MM-DD
title Adding GANTT diagram functionality to Mermaid
section A section
Completed task :done, des1, 2014-01-06,2014-01-08
Active task :active, des2, 2014-01-09, 3d
Future task : des3, after des2, 5d
Future task2 : des4, after des3, 5d
section Critical tasks
Completed task in the critical line :crit, done, 2014-01-06,24h
Implement parser and jison :crit, done, after des1, 2d
Create tests for parser :crit, active, 3d
Future task in critical line :crit, 5d
Create tests for renderer :2d
Add to Mermaid :1d
```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
The notice shortcode shows various types of disclaimers with adjustable color, title and icon to help you structure your page.
There may be pirates
It is all about the boxes.
Usage
While the examples are using shortcodes with named parameter you are free to use positional as well or also call this shortcode from your own partials.
{{%noticestyle="primary"title="There may be pirates"icon="skull-crossbones"%}}Itisallabouttheboxes.{{%/notice%}}
{{%noticeprimary"There may be pirates""skull-crossbones"%}}Itisallabouttheboxes.{{%/notice%}}
{{partial"shortcodes/notice.html"(dict"context"."style""primary""title""There may be pirates""icon""skull-crossbones""content""It is all about the boxes.")}}
Parameter
Name
Position
Default
Notes
style
1
default
The color scheme used to highlight the box content.
- 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
Arbitrary text for the box title. Depending on the style there may be a default title. Any given value will overwrite the default.
- for severity styles: the matching title for the severity - for all other colors: <empty>
If you want no title for a severity style, you have to set this parameter to " " (a non empty string filled with spaces)
icon
3
see notes
Font Awesome icon name set to the left of the title. Depending on the style there may be a default icon. Any given value will overwrite the default.
- for severity styles: a nice matching icon for the severity - for all other colors: <empty>
If you want no icon for a severity style, you have to set this parameter to " " (a non empty string filled with spaces)
<content>
<empty>
Arbitrary text to be displayed in box.
Examples
By Severity
Info with markup
{{%noticestyle="info"%}}An**information**disclaimerYoucanaddstandardmarkdownsyntax:-multipleparagraphs-bulletpointlists-_emphasized_,**bold**andeven***boldemphasized***text-[links](https://example.com)
-etc.```plaintext
...and even source code
```>thepossibilitiesareendless(almost-includingothershortcodesmayormaynotwork){{%/notice%}}
The URL to the OpenAPI Specification file. This can be relative to the URL of your page if it is a leaf or branch bundle.
Note
If you want to print out (or generate a PDF) from your Swagger documentation, don’t initiate printing directly from the page because the elements are optimized for interactive usage in a browser.
Instead, open the print preview in your browser and initiate printing from that page. This page is optimized for reading and expands most of the available sections.
Configuration
Swagger is configured with default settings. You can customize Swagger’s default settings for all of your files thru a JSON object in your config.toml or override these settings per page thru your pages frontmatter.
The JSON object of your config.toml / frontmatter is forwarded into Swagger’s initialization. At the moment, only the theme setting is supported.
The theme setting can also be set by your used color variant. This will be the sitewide default and can - again - be overridden by your settings in config.toml or frontmatter.
The tabs shortcode displays arbitrary content in unlimited number of tabs. This comes in handy eg. for providing code snippets for multiple languages or providing configuration in different formats.
print("Hello World!")
echo"Hello World!"
Usage
While the examples are using shortcodes with named parameter you are free to also call this shortcode from your own partials.
Arbitrary name of the group the tab view belongs to.
Tab views with the same groupid sychronize their selected tab. This sychronization applies to the whole site!
<content>
<empty>
Arbitrary number of tabs defined with the tab sub-shortcode.
Note
When using tab views with different content sets, make sure to use a common groupid for equal sets of tabs but distinct groupid for different sets.
The tab selection is restored automatically based on the groupid and if it cannot find a tab item because it came from the 'default' group on a different page then the first tab is selected instead.
