Hugo uses Markdown as its content format. However, there are a lot of things that Markdown doesn’t support well.
You could use pure HTML to expand your possibilities. But this happens to be a bad idea. Everyone uses Markdown because it’s pure and simple to read. You should avoid HTML to keep it as simple and portable as possible.
To avoid Markdown’s limitations, Hugo created shortcodes. A shortcode is a simple snippet inside of a page.
The badge shortcode displays little markers in your text with adjustable color, title and icon.
ImportantVersion6.6.6Captain InfoNewAwesome
Usage
{{%badge%}}Important{{%/badge%}}{{%badgestyle="primary"title="Version"%}}6.6.6{{%/badge%}}{{%badgestyle="red"icon="angle-double-up"%}}Captain{{%/badge%}}{{%badgestyle="info"%}}New{{%/badge%}}{{%badgecolor="fuchsia"icon="fa-fw fab fa-hackerrank"%}}Awesome{{%/badge%}}
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
The button shortcode displays a clickable button with adjustable color, title and icon.
Either the destination URL for the button or JavaScript code to be executed on click. If this parameter is not set, the button will do nothing but is still displayed as clickable.
- if starting with javascript: all following text will be executed in your browser - every other string will be interpreted as URL
style
transparent
The style scheme used for the button.
- by severity: caution, important, info, note, tip, warning - by brand color: primary, secondary, accent - by color: blue, cyan, green, grey, magenta, orange, red - by special color: default, transparent, code
The CSS color value to be used. If not set, the chosen color depends on the style. Any given value will overwrite the default.
- for severity styles: a nice matching color for the severity - for all other styles: the corresponding color
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 styles: <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.
target
see notes
The destination frame/window if href is an URL. Otherwise the parameter is not used. This behaves similar to normal links. If the parameter is not given it defaults to:
- the setting of externalLinkTarget or _blank if not set, for any address starting with http:// or https:// - no specific value for all other links
type
see notes
The button type if href is JavaScript. Otherwise the parameter is not used. If the parameter is not given it defaults to button
<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 styles: <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
auto
The sort criteria of the displayed list.
- auto defaults to ordersectionsby of the page’s Front Matter or to ordersectionsby of the configuration Option or to weight - weight - title - modifieddate - expirydate - publishdate - date - length - default adhering to Hugo’s default sort criteria
{{%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%}}
This shortcode is fully compatible with Hugo’s highlight shortcode but offers some extensions.
It is called interchangeably in the same way as Hugo’s own shortcode by providing positional parameter or simply by using Markdown codefences.
You are free to also call this shortcode from your own partials. In this case it resembles Hugo’s highlight function syntax if you call it using compatibility syntax.
Codefence syntax is widely available in other Markdown parsers like GitHub and therefore is the recommend syntax for generating portable Markdown.
The tab shortcode is also capable of displaying code but with limited options.
Parameter
Name
Position
Default
Notes
type
1
<empty>
The language of the code to highlight. Choose from one of the supported languages. Case-insensitive.
title
<empty>
Extension. Arbitrary title for code. This displays the code like a single tab if hl_inline=false (which is Hugo’s default).
wrap
see notes
Extension. When true the content may wrap on long lines otherwise it will be scrollable.
The default value can be set in your hugo.toml and overwritten via front matter. See below.
options
2
<empty>
An optional, comma-separated list of zero or more Hugo supported options as well as extension parameter from this table.
You can configure the color style used for code blocks in your color variants stylesheet file using the --CODE-theme variable. This requires further configuration as described in the above link.
Examples
Line Numbers with Starting Offset
As mentioned above, line numbers in a table layout will shift if code is wrapping, so better use inline. To make things easier for you, set lineNumbersInTable = false in your hugo.toml and add lineNos = true when calling the shortcode instead of the specific values table or inline.
666# the hardest part is to start writing code; here's a kickstart; just copy and paste this; it's free; the next lines will cost you serious credits667print("Hello")668print(" ")669print("World")670print("!")
Markdown Codefence with Title
```py { title="python" }
# a bit shorter
print("Hello World!")
```
Font Awesome icon name to be displayed. It will be displayed in the text color of its according context.
Finding an icon
Browse through the available icons in the Font Awesome Gallery. Notice that the free filter is enabled, as only the free icons are available by default.
Once on the Font Awesome page for a specific icon, for example the page for the heart, copy the icon name and paste into the Markdown content.
Customising Icons
Font Awesome provides many ways to modify the icon
Change color (by default the icon will inherit the parent color)
While the shortcode simplifies using standard icons, the icon customization and other advanced features of the Font Awesome library require you to use HTML directly. Paste the <i> HTML into markup, and Font Awesome will load the relevant icon.
Built with <iclass="fas fa-heart"></i> by Relearn and Hugo
Built with by Relearn and Hugo
To use these native HTML elements in your Markdown, add this in your hugo.toml:
[markup.goldmark.renderer]unsafe=true
Include
The include shortcode includes other pages, resources or files from your project.
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.
Settings
Enabling Link Warnings
OptionFront Matter You can use include.errorlevel to control what should happen if a local link can not be resolved to a resource.
If not set or empty, any unresolved link is written as given into the resulting output. If set to warning the same happens and an additional warning is printed in the built console. If set to error an error message is printed and the build is aborted.
Please note that this can not resolve files inside of your static directory. The file must be a resource of the page or the site.
the possibilities are endless (almost - including other shortcodes may or may not work) (almost - including other shortcodes may or may not work)
Et Cetera (English: /ɛtˈsɛtərə/), abbreviated to etc., etc, et cet., is a Latin expression that is used in English to mean “and other similar things”, or “and so forth” ↩︎
Math
If this is not enough, the math shortcode helps you rendering math and chemical formulae using the MathJax library.
You can also use pure Markdown for writing simple math expressions.
Passthrough syntax is only available by further configuration and has limited features as it does not provide any of the below parameter. Nevertheless, it is widely available in other Markdown parsers like GitHub and therefore is the recommend syntax for generating portable Markdown.
Parameter
Name
Default
Notes
align
center
The vertical alignment.
Allowed values are left, center or right.
<content>
<empty>
Your formulae.
Settings
Providing Initialization Options for the MathJax Library
OptionFront Matter The MathJax library is configured with default settings for initialization.
You can overwrite the settings by providing a JSON object in mathJaxInitialize. See MathJax’s documentation for all allowed settings.
Keep in mind that initialization settings of your pages front matter overwrite all settings of your configuration options.
Loading an External Version of the MathJax Library
OptionFront Matter The theme uses the shipped MathJax library by default.
In case you want do use a different version of the MathJax library but don’t want to override the shipped version, you can set customMathJaxURL to the URL of the external MathJax library.
OptionFront Matter The MathJax library will be loaded if the page contains a math shortcode or codefence.
You can force loading the MathJax library if no shortcode or codefence was used by setting math=true. If a shortcode or codefence was found, the option has no effect. This must be set in case you are using the passthrough configuration to render math.
Instead of math=true you can also use the alias math.force=true.
math=true
math:true
{"math":true}
Passthrough Configuration
You can use your math without enclosing it in a shortcode or codefence by using a passthrough configuration
In this case you have to force load the MathJax library either in your hugo.toml or in your page’s front matter as the theme doesn’t know if math is used.
See the example on how a passthrough configurations makes using math really easy.
Examples
Passthrough Block Math
With passthrough configuration enabled you can just drop your math without enclosing it by shortcodes or codefences but no other parameters are available.
In this case you have to force load the MathJax library by setting math=true either in your hugo.toml or in your page’s front matter.
In passthrough default configuration, block math is generated if you use two consecutive $$ as a delimiter around your formulae.
$$\left|
\begin{array}{cc}
a & b \\
c & d
\end{array}\right|$$
$$\left|
\begin{array}{cc}
a & b \\
c & d
\end{array}\right|$$
Passthrough Inline Math
The same usage restrictions as of the previous example apply here as well.
In passthrough default configuration, inline math is generated if you use a single $ as a delimiter around your formulae.
Euclid already knew, $\sqrt{2}$ is irrational.
Euclid already knew, $\sqrt{2}$ is irrational.
Codefence Block Math with Right Alignment
If you are using codefences, more parameter are available. Your formulae still needs to be enclosed by $ or $$ as delimiters respectively.
{{partial"shortcodes/mermaid.html"(dict"page"."content""graph LR;\n If --> Then\n Then --> Else""align""center""zoom""true")}}
Codefence syntax is widely available in other Markdown parsers like GitHub and therefore is the recommend syntax for generating portable Markdown.
Parameter
Name
Default
Notes
align
center
The vertical alignment.
Allowed values are left, center or right.
zoom
see notes
Whether the graph is pan- and zoomable.
If not set the value is determined by the mermaidZoom setting of your configurations options or the pages front matter or false if not set at all.
- false: no pan or zoom - true: pan and zoom active
<content>
<empty>
Your Mermaid graph.
Settings
Configuring Pan and Zoom
OptionFront Matter The generated graphs can be panned by dragging them and zoomed by using the mousewheel. On mobile devices you can use finger gestures.
By default this is disabled. Set mermaidZoom=true to enable it.
Individual settings of a graphs zoom parameter have precedence over the page’s front matter and configuration options in that order.
mermaidZoom=true
mermaidZoom:true
{"mermaidZoom":true}
Providing Initialization Options for the Mermaid Library
OptionFront Matter The Mermaid library is configured with default settings for initialization.
You can overwrite the settings by providing a JSON object in mermaidInitialize. See Mermaid’s documentation for all allowed settings.
Keep in mind that initialization settings of your pages front matter overwrite all settings of your configuration options.
In addition, you can merge settings for each individual graph through diagram directives on top of the settings of your page’s front matter or configuration options.
Loading an External Version of the Mermaid Library
OptionFront Matter The theme uses the shipped Mermaid library by default.
In case you want do use a different version of the Mermaid library but don’t want to override the shipped version, you can set customMermaidURL to the URL of the external Mermaid library.
OptionFront Matter The Mermaid library will be loaded if the page contains an mermaid shortcode or codefence.
You can force loading the Mermaid library if no shortcode or codefence was used by setting mermaid.force=true. If a shortcode or codefence was found, this option has no effect. This comes handy in case you are using scripting to render a graph.
[mermaid]force=true
mermaid:force:true
{"mermaid":{"force":true}}
Setting a Specific Mermaid Theme
While you can configure the Mermaid theme to render your graph by using one of the initialization options, the recommended way is to set the default value using the --MERMAID-theme variable in your color variant stylesheet. This allows your graphs to look pretty when the user switches the color variant.
Examples
Flowchart with YAML-Title
```mermaid
---
title: Example Diagram
---
graph LR;
A[Hard edge] -->|Link text| B(Round edge)
B --> C{<strong>Decision</strong>}
C -->|One| D[Result one]
C -->|Two| E[Result two]
```
---
title: Example Diagram
---
graph LR;
A[Hard edge] -->|Link text| B(Round edge)
B --> C{<strong>Decision</strong>}
C -->|One| D[Result one]
C -->|Two| E[Result two]
Sequence Diagram with Configuration Directive
```mermaid
%%{init:{"fontFamily":"monospace", "sequence":{"showSequenceNumbers":true}}}%%
sequenceDiagram
Alice->>John: Hello John, how are you?
loop Healthcheck
John->>John: Fight against hypochondria
end
Note right of John: Rational thoughts!
John-->>Alice: Great!
John->>Bob: How about you?
Bob-->>John: Jolly good!
```
%%{init:{"fontFamily":"monospace", "sequence":{"showSequenceNumbers":true}}}%%
sequenceDiagram
Alice->>John: Hello John, how are you?
loop Healthcheck
John->>John: Fight against hypochondria
end
Note right of John: Rational thoughts!
John-->>Alice: Great!
John->>Bob: How about you?
Bob-->>John: Jolly good!
Class Diagram
```mermaid
classDiagram
Animal <|-- Duck
Animal <|-- Fish
Animal <|-- Zebra
Animal : +int age
Animal : +String gender
Animal: +isMammal()
Animal: +mate()
class Duck{
+String 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 : +String gender
Animal: +isMammal()
Animal: +mate()
class Duck{
+String beakColor
+swim()
+quack()
}
class Fish{
-int sizeInFeet
-canEat()
}
class Zebra{
+bool is_wild
+run()
}
State Diagram Aligned to the Right Using Shortcode Syntax
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 with Non-Default Mermaid Theme
```mermaid
%%{init:{"theme":"forest"}}%%
erDiagram
CUSTOMER }|..|{ DELIVERY-ADDRESS : has
CUSTOMER ||--o{ ORDER : places
CUSTOMER ||--o{ INVOICE : "liable for"
DELIVERY-ADDRESS ||--o{ ORDER : receives
INVOICE ||--|{ ORDER : covers
ORDER ||--|{ ORDER-ITEM : includes
PRODUCT-CATEGORY ||--|{ PRODUCT : contains
PRODUCT ||--o{ ORDER-ITEM : "ordered in"
```
%%{init:{"theme":"forest"}}%%
erDiagram
CUSTOMER }|..|{ DELIVERY-ADDRESS : has
CUSTOMER ||--o{ ORDER : places
CUSTOMER ||--o{ INVOICE : "liable 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 working day
section Go to 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
```
journey
title My working day
section Go to 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 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
```
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
Pie Chart without Zoom
```mermaid {zoom="false"}
pie title Pets adopted by volunteers
"Dogs" : 386
"Cats" : 85
"Rats" : 15
```
pie title Pets adopted by volunteers
"Dogs" : 386
"Cats" : 85
"Rats" : 15
Quadrant Chart
```mermaid
quadrantChart
title Reach and engagement of campaigns
x-axis Low Reach --> High Reach
y-axis Low Engagement --> High Engagement
quadrant-1 We should expand
quadrant-2 Need to promote
quadrant-3 Re-evaluate
quadrant-4 May be improved
Campaign A: [0.3, 0.6]
Campaign B: [0.45, 0.23]
Campaign C: [0.57, 0.69]
Campaign D: [0.78, 0.34]
Campaign E: [0.40, 0.34]
Campaign F: [0.35, 0.78]
```
quadrantChart
title Reach and engagement of campaigns
x-axis Low Reach --> High Reach
y-axis Low Engagement --> High Engagement
quadrant-1 We should expand
quadrant-2 Need to promote
quadrant-3 Re-evaluate
quadrant-4 May be improved
Campaign A: [0.3, 0.6]
Campaign B: [0.45, 0.23]
Campaign C: [0.57, 0.69]
Campaign D: [0.78, 0.34]
Campaign E: [0.40, 0.34]
Campaign F: [0.35, 0.78]
Requirement Diagram
```mermaid
requirementDiagram
requirement test_req {
id: 1
text: the test text.
risk: high
verifymethod: test
}
element test_entity {
type: simulation
}
test_entity - satisfies -> test_req
```
requirementDiagram
requirement test_req {
id: 1
text: the test text.
risk: high
verifymethod: test
}
element test_entity {
type: simulation
}
test_entity - satisfies -> test_req
```mermaid
C4Context
title System Context diagram for Internet Banking System
Enterprise_Boundary(b0, "BankBoundary0") {
Person(customerA, "Banking Customer A", "A customer of the bank, with personal bank accounts.")
Person(customerB, "Banking Customer B")
Person_Ext(customerC, "Banking Customer C", "desc")
Person(customerD, "Banking Customer D", "A customer of the bank, <br/> with personal bank accounts.")
System(SystemAA, "Internet Banking System", "Allows customers to view information about their bank accounts, and make payments.")
Enterprise_Boundary(b1, "BankBoundary") {
SystemDb_Ext(SystemE, "Mainframe Banking System", "Stores all of the core banking information about customers, accounts, transactions, etc.")
System_Boundary(b2, "BankBoundary2") {
System(SystemA, "Banking System A")
System(SystemB, "Banking System B", "A system of the bank, with personal bank accounts. next line.")
}
System_Ext(SystemC, "E-mail system", "The internal Microsoft Exchange e-mail system.")
SystemDb(SystemD, "Banking System D Database", "A system of the bank, with personal bank accounts.")
Boundary(b3, "BankBoundary3", "boundary") {
SystemQueue(SystemF, "Banking System F Queue", "A system of the bank.")
SystemQueue_Ext(SystemG, "Banking System G Queue", "A system of the bank, with 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")
```
C4Context
title System Context diagram for Internet Banking System
Enterprise_Boundary(b0, "BankBoundary0") {
Person(customerA, "Banking Customer A", "A customer of the bank, with personal bank accounts.")
Person(customerB, "Banking Customer B")
Person_Ext(customerC, "Banking Customer C", "desc")
Person(customerD, "Banking Customer D", "A customer of the bank, <br/> with personal bank accounts.")
System(SystemAA, "Internet Banking System", "Allows customers to view information about their bank accounts, and make payments.")
Enterprise_Boundary(b1, "BankBoundary") {
SystemDb_Ext(SystemE, "Mainframe Banking System", "Stores all of the core banking information about customers, accounts, transactions, etc.")
System_Boundary(b2, "BankBoundary2") {
System(SystemA, "Banking System A")
System(SystemB, "Banking System B", "A system of the bank, with personal bank accounts. next line.")
}
System_Ext(SystemC, "E-mail system", "The internal Microsoft Exchange e-mail system.")
SystemDb(SystemD, "Banking System D Database", "A system of the bank, with personal bank accounts.")
Boundary(b3, "BankBoundary3", "boundary") {
SystemQueue(SystemF, "Banking System F Queue", "A system of the bank.")
SystemQueue_Ext(SystemG, "Banking System G Queue", "A system of the bank, with personal bank accounts.")
}
}
}
BiRel(customerA, SystemAA, "Uses")
BiRel(SystemAA, SystemE, "Uses")
Rel(SystemAA, SystemC, "Sends e-mails", "SMTP")
Rel(SystemC, customerA, "Sends e-mails to")
UpdateElementStyle(customerA, $fontColor="red", $bgColor="grey", $borderColor="red")
UpdateRelStyle(customerA, SystemAA, $textColor="blue", $lineColor="blue", $offsetX="5")
UpdateRelStyle(SystemAA, SystemE, $textColor="blue", $lineColor="blue", $offsetY="-10")
UpdateRelStyle(SystemAA, SystemC, $textColor="blue", $lineColor="blue", $offsetY="-40", $offsetX="-50")
UpdateRelStyle(SystemC, customerA, $textColor="red", $lineColor="red", $offsetX="-50", $offsetY="20")
UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")
Mindmaps
```mermaid
mindmap
root((mindmap))
Origins
Long history
::icon(fa fa-book)
Popularisation
British popular psychology author Tony Buzan
Research
On effectiveness<br/>and features
On Automatic creation
Uses
Creative techniques
Strategic planning
Argument mapping
Tools
Pen and paper
Mermaid
```
mindmap
root((mindmap))
Origins
Long history
::icon(fa fa-book)
Popularisation
British popular psychology author Tony Buzan
Research
On effectiveness<br/>and features
On Automatic creation
Uses
Creative techniques
Strategic planning
Argument mapping
Tools
Pen and paper
Mermaid
Timeline
```mermaid
timeline
title History of Social Media Platform
2002 : LinkedIn
2004 : Facebook
: Google
2005 : Youtube
2006 : Twitter
```
timeline
title History of Social Media Platform
2002 : LinkedIn
2004 : Facebook
: Google
2005 : Youtube
2006 : Twitter
```mermaid
xychart-beta
title "Sales Revenue"
x-axis [jan, feb, mar, apr, may, jun, jul, aug, sep, oct, nov, dec]
y-axis "Revenue (in $)" 4000 --> 11000
bar [5000, 6000, 7500, 8200, 9500, 10500, 11000, 10200, 9200, 8500, 7000, 6000]
line [5000, 6000, 7500, 8200, 9500, 10500, 11000, 10200, 9200, 8500, 7000, 6000]
```
xychart-beta
title "Sales Revenue"
x-axis [jan, feb, mar, apr, may, jun, jul, aug, sep, oct, nov, dec]
y-axis "Revenue (in $)" 4000 --> 11000
bar [5000, 6000, 7500, 8200, 9500, 10500, 11000, 10200, 9200, 8500, 7000, 6000]
line [5000, 6000, 7500, 8200, 9500, 10500, 11000, 10200, 9200, 8500, 7000, 6000]
Block Diagram
```mermaid
block-beta
columns 1
db(("DB"))
blockArrowId6<[" "]>(down)
block:ID
A
B["A wide one in the middle"]
C
end
space
D
ID --> D
C --> D
style B fill:#969,stroke:#333,stroke-width:4px
```
block-beta
columns 1
db(("DB"))
blockArrowId6<[" "]>(down)
block:ID
A
B["A wide one in the middle"]
C
end
space
D
ID --> D
C --> D
style B fill:#969,stroke:#333,stroke-width:4px
```mermaid
architecture-beta
group api(cloud)[API]
service db(database)[Database] in api
service disk1(disk)[Storage] in api
service disk2(disk)[Storage] in api
service server(server)[Server] in api
db:L -- R:server
disk1:T -- B:server
disk2:T -- B:db
```
architecture-beta
group api(cloud)[API]
service db(database)[Database] in api
service disk1(disk)[Storage] in api
service disk2(disk)[Storage] in api
service server(server)[Server] in api
db:L -- R:server
disk1:T -- B:server
disk2:T -- B:db
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
> [!primary] There may be pirates
> It is all about the boxes.
{{%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"page"."style""primary""title""There may be pirates""icon""skull-crossbones""content""It is all about the boxes.")}}
Callout syntax has limited features as it does not provide all of the below parameter. Nevertheless, it is widely available in other Markdown parsers like with GitHub alerts or Obsidian callouts and therefore is the recommend syntax for generating portable Markdown.
If you want to display a transparent expandable box without any border, you can also use the expand shortcode.
Parameter
Name
Position
Default
Notes
style
1
default
The style scheme used for the box.
- by severity: caution, important, info, note, tip, warning - by brand color: primary, secondary, accent - by color: blue, cyan, green, grey, magenta, orange, red - by special color: default, transparent, code
The CSS color value to be used. If not set, the chosen color depends on the style. Any given value will overwrite the default.
- for severity styles: a nice matching color for the severity - for all other styles: the corresponding color
This is not available using callout syntax.
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 styles: <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 styles: <empty>
If you want no icon for a severity style, you have to set this parameter to " " (a non empty string filled with spaces)
This is not available using callout syntax.
expanded
<empty>
Whether to draw an expander and how the content is displayed.
- <empty>: no expander is drawn and the content is permanently shown - true: the expander is drawn and the content is initially shown - false: the expander is drawn and the content is initially hidden
<content>
<empty>
Arbitrary text to be displayed in box.
Settings
Defining own Styles
Option Besides the predefined style values from above, you are able to define your own.
The style parameter used in a shortcode must match the identifier in the configuration. The title for the style will be determined from the configured title. If no title but a i18n is set, the title will be taken from the translation files by that key. The title may be empty in which case, the box does not contain a default title. icon and color are working similar.
You can also redefine the predefined styles if you’re not satisfied with the default values.
> [!CAUTION]
> Advises about risks or negative outcomes of certain actions.
> [!IMPORTANT]
> Key information users need to know to achieve their goal.
> [!INFO]
> Information that users <ins>_might_</ins> find interesting.
> [!NOTE]
> Useful information that users should know, even when skimming content.
> [!TIP]
> Helpful advice for doing things better or more easily.
> [!WARNING]
> Urgent info that needs immediate user attention to avoid problems.
Caution
Advises about risks or negative outcomes of certain actions.
Important
Key information users need to know to achieve their goal.
Info
Information that users might find interesting.
Note
Useful information that users should know, even when skimming content.
Tip
Helpful advice for doing things better or more easily.
Warning
Urgent info that needs immediate user attention to avoid problems.
With User-Defined Color, Font Awesome Brand Icon and Markdown in Title and Content
{{%noticecolor="fuchsia"title="**Hugo** is _awesome_"icon="fa-fw fab fa-hackerrank"%}}Youcanaddstandardmarkdownsyntax:-multipleparagraphs-bulletpointlists-_emphasized_,**bold**andeven**_boldemphasized_**text-[links](https://example.com)
-etc.[^etc][^etc]:EtCetera(English:/ɛtˈsɛtərə/),abbreviatedtoetc.,etc,etcet.,isaLatinexpressionthatisusedinEnglishtomean"and other similar things",or"and so forth"```plaintext
...and even source code
```>thepossibilitiesareendless(almost-includingothershortcodesmayormaynotwork)(almost-includingothershortcodesmayormaynotwork){{%/notice%}}
the possibilities are endless (almost - including other shortcodes may or may not work) (almost - including other shortcodes may or may not work)
Et Cetera (English: /ɛtˈsɛtərə/), abbreviated to etc., etc, et cet., is a Latin expression that is used in English to mean “and other similar things”, or “and so forth” ↩︎
If you want to print out (or generate a PDF) from your OpenAPI 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.
Parameter
Name
Default
Notes
src
<empty>
The path to the to the OpenAPI specification resource or URL to be used. Resource paths adhere to Hugo’s logical path.
Settings
Enabling Link Warnings
OptionFront Matter You can use openapi.errorlevel to control what should happen if a local OpenAPI specification link can not be resolved to a resource.
If not set or empty, any unresolved link is written as given into the resulting output. If set to warning the same happens and an additional warning is printed in the built console. If set to error an error message is printed and the build is aborted.
Please note that this can not resolve files inside of your static directory. The file must be a resource of the page or the site.
Loading an External Version of the Swagger UI Library
OptionFront Matter The theme uses the shipped Swagger UI library by default.
In case you want do use a different version of the Swagger UI library but don’t want to override the shipped version, you can set customOpenapiURL to the URL of the external Swagger UI library.
OptionFront Matter The Swagger UI library will be loaded if the page contains an openapi shortcode or codefence.
You can force loading the Swagger UI library if no shortcode or codefence was used by setting openapi.force=true. If a shortcode or codefence was found, the option has no effect. This comes handy in case you are using scripting to render a spec.
[openapi]force=true
openapi:force:true
{"openapi":{"force":true}}
Setting a Specific Swagger UI Theme
The recommended way to configure your Swagger UI theme is to set the default value using the --OPENAPI-theme variable in your color variant stylesheet. This allows your specs to look pretty when the user switches the color variant.
Example
Using Local File
{{<openapisrc="petstore.json">}}
Resources
The resources shortcode displays links to resources contained in a page bundle.
Multilanguage features are not supported directly by the shortcode but rely on Hugo’s handling for resource translations applied when the theme iterates over all available resources.
Parameter
Name
Default
Notes
style
transparent
The style scheme used for the box.
- by severity: caution, important, info, note, tip, warning - by brand color: primary, secondary, accent - by color: blue, cyan, green, grey, magenta, orange, red - by special color: default, transparent, code
The CSS color value to be used. If not set, the chosen color depends on the style. Any given value will overwrite the default.
- for severity styles: a nice matching color for the severity - for all other styles: the corresponding color
title
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 styles: Resources
If you want no title for a severity style, you have to set this parameter to " " (a non empty string filled with spaces)
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 styles: paperclip
If you want no icon, you have to set this parameter to " " (a non empty string filled with spaces)
expanded
<empty>
Whether to draw an expander and how the resource list is displayed.
- <empty>: no expander is drawn and the resource list is permanently shown - true: the expander is drawn and the resource list is initially shown - false: the expander is drawn and the resource list is initially hidden
sort
asc
Sorting the output in ascending or descending order.
For further examples for style, color, title and icon, see the notice shortcode documentation. The parameter are working the same way for both shortcodes, besides having different defaults.
SiteParam
The siteparam shortcode prints values of params contained in your hugo.toml.
If you want multiple tabs grouped together you can wrap your tabs into the tabs shortcode.
If you want further options when using a single code tab, you can also use the highlight shortcode.
Parameter
Name
Default
Notes
style
see notes
The style scheme used for the tab. If you don’t set a style and you display a single code block inside of the tab, its default styling will adapt to that of a code block. Otherwise default is used.
- by severity: caution, important, info, note, tip, warning - by brand color: primary, secondary, accent - by color: blue, cyan, green, grey, magenta, orange, red - by special color: default, transparent, code
A tab can not only contain code but arbitrary text. In this case text and code will get a margin.
printf("Hello World!");
Understanding style and color Behavior
The style parameter affects how the color parameter is applied.
{{<tabs>}}{{%tabtitle="just colored style"style="blue"%}}The`style`parameterissettoacolorstyle.Thiswillsetthebackgroundtoalighterversionofthechosenstylecolorasconfiguredinyourthemevariant.{{%/tab%}}{{%tabtitle="just color"color="blue"%}}Onlythe`color`parameterisset.ThiswillsetthebackgroundtoalighterversionofthechosenCSScolorvalue.{{%/tab%}}{{%tabtitle="default style and color"style="default"color="blue"%}}The`style`parameteraffectshowthe`color`parameterisapplied.The`default`stylewillsetthebackgroundtoyour`--MAIN-BG-color`asconfiguredforyourthemevariantresemblingthedefaultstylebutwithdifferentcolor.{{%/tab%}}{{%tabtitle="just severity style"style="info"%}}The`style`parameterissettoaseveritystyle.Thiswillsetthebackgroundtoalighterversionofthechosenstylecolorasconfiguredinyourthemevariantandalsoaffectsthechosenicon.{{%/tab%}}{{%tabtitle="severity style and color"style="info"color="blue"%}}The`style`parameteraffectshowthe`color`parameterisapplied.ThiswillsetthebackgroundtoalighterversionofthechosenCSScolorvalueandalsoaffectsthechosenicon.{{%/tab%}}{{</tabs>}}
The style parameter is set to a color style.
This will set the background to a lighter version of the chosen style color as configured in your theme variant.
Only the color parameter is set.
This will set the background to a lighter version of the chosen CSS color value.
The style parameter affects how the color parameter is applied.
The default style will set the background to your --MAIN-BG-color as configured for your theme variant resembling the default style but with different color.
The style parameter is set to a severity style.
This will set the background to a lighter version of the chosen style color as configured in your theme variant and also affects the chosen icon.
The style parameter affects how the color parameter is applied.
This will set the background to a lighter version of the chosen CSS color value and also affects the chosen icon.
Tabs
The tabs shortcode displays arbitrary content in an unlimited number of tabs.
If you just want a single tab you can instead call the tab shortcode standalone.
Also follow the above link to see the parameter for a nested tab.
Parameter
Name
Default
Notes
groupid
<random>
Arbitrary name of the group the tab view belongs to.
Tab views with the same groupid sychronize their selected tab. The tab selection is restored automatically based on the groupid for tab view. If the selected tab can not be found in a tab group the first tab is selected instead.
This sychronization applies to the whole site!
style
<empty>
Sets a default value for every contained tab. Can be overridden by each tab. See the tab shortcode for possible values.
color
<empty>
Sets a default value for every contained tab. Can be overridden by each tab. See the tab shortcode for possible values.
In case you want to nest tab views, the parent tab that contains nested tab views needs to be declared with {{< tab >}} instead of {{% tab %}}. Note, that in this case it is not possible to put markdown in the parent tab.
You can also set style and color parameter for all tabs and overwrite them on tab level. See the tab shortcode for possible values.
