Attachments

The attachments shortcode displays a list of files attached to a page with adjustable color, title and icon.

Usage

The shortcurt lists files found in a specific folder.

{{% attachments /%}}

Currently, it support two implementations for pages

1. If your page is a Markdown file, attachements must be placed in a folder named like your page and ending with .files.

   • content
     • _index.md
     • page.files
       • attachment.pdf
     • page.md

2. If your page is a folder, attachements must be placed in a nested ‘files’ folder.

   • content
     • _index.md
     • page
       • index.md
       • files
         • attachment.pdf

Be aware that if you use a multilingual website, you will need to have as many folders as languages.

Parameter

Examples

Custom title, list of attachments ending in pdf or mp4

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

Info styled box, descending sort order

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

Style and icons

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

A button is a just a clickable button with optional icon.

{{% button href="https://gohugo.io/" %}}Get Hugo{{% /button %}}
{{% button href="https://gohugo.io/" icon="fas fa-download" %}}Get Hugo with icon{{% /button %}}
{{% button href="https://gohugo.io/" icon="fas fa-download" icon-position="right" %}}Get Hugo with icon right{{% /button %}}

Get Hugo Get Hugo with icon Get Hugo with icon right

Children

Use the children shortcode to list the child pages of a page and the further descendants (children’s children). By default, the shortcode displays links to the child pages.

Usage

Demo

{{% children  %}}

• page X
• page 1
• page 2
• page 3

{{% children description="true" %}}

• page X

This is a plain page test, and the beginning of a YAML multiline description...

• page 1

This is a demo child page

• page 2

This is a demo child page with no description. So its content is used as description.

• page 3

This is a demo child page

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

• page X
• page 1
• page 1-1
• page 1-1-1 (hidden)
• page 1-1-1-1
• page 1-1-1-1-1 (hidden)
• page 1-1-1-1-1-1
• page 1-1-2
• page 1-1-2-1
• page 1-1-2-2
• page 1-1-3
• page 2
• page 3
• page 3-1
• page 4 (hidden)

{{% children containerstyle="div" style="h2" depth="3" description="true" %}}

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

Expand

The Expand shortcode displays an expandable/collapsible section of text on your page.

Usage

{{% expand [ <string> [ "true" | "false" ] ] %}}
Yes!
{{% /expand %}}

The first optional parameter defines the text that appears next to the expand/collapse icon. The default text is "Expand me...".

The second optional parameter controls if the block is initially shown as expanded ("true") or collapsed ("false"). The default ist "false".

Examples

All defaults

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

Initially expanded

{{% expand "Expand me..." "true" %}}
No need to press you!
{{% /expand %}}

Arbitrary text

...and even source code

{{% expand "Show me almost endless possibilities" %}}
Some expandable text.

You can add standard markdown syntax:

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

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

> the possiblities are endless (almost - including other shortcodes may or may not work)
{{% /expand %}}

Include

The include shortcode includes other files from your project inside of the current file. This can even contain Markdown and will be taken into account when generating the table of contents.

Usage

{{% include <string> [ "true" | "false" ] %}}

The first required parameter is the path to the file to be included.

If the file’s content will be displayed as HTML, the second optional parameter controls if the first heading of the included file should be displayed ("true")- which is the default - or be hidden.

Examples

Arbitray content

You can add standard markdown syntax:

• multiple paragraphs
• bullet point lists
• emphasized, bold and even bold emphasized text
• links
• etc.

...and even source code

the possiblities are endless (almost - including other shortcodes may or may not work) (almost - including other shortcodes may or may not work)

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

Mermaid

Mermaid is a library helping you to generate diagram and flowcharts from text, in a similar manner as Markdown.

Usage

Just insert your Mermaid code in the mermaid shortcode like this:

{{< mermaid [ align=("left"|"right"|"center"|"justify") ] >}}
classDiagram
    Person *-- Dog
{{< /mermaid >}}

You can set an optional align attribute which defaults to "center".

If you don’t need alignment you can use the alternative syntax using code fences if you have turned off guessSyntax for the markup.highlight setting (see below):

```mermaid
classDiagram
    Person *-- Dog
```

The generated graphs can be be panned by dragging them and zoomed by using the mousewheel. On mobile devices you can use finger gestures.

Examples

Flowchart

{{< mermaid align="left" >}}
%%{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 >}}

Sequence

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

GANTT

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

Class

{{< mermaid >}}
classDiagram
    Class01 <|-- AveryLongClass : Cool
    Class03 *-- Class04
    Class05 o-- Class06
    Class07 .. Class08
    Class09 --> C2 : Where am i?
    Class09 --* C3
    Class09 --|> Class07
    Class07 : equals()
    Class07 : Object[] elementData
    Class01 : size()
    Class01 : int chimp
    Class01 : int gorilla
    Class08 <--> C2: Cool label
{{< /mermaid >}}

State

```mermaid
stateDiagram-v2
    open: Open Door
    closed: Closed Door
    locked: Locked Door
    open   --> closed: Close
    closed --> locked: Lock
    locked --> closed: Unlock
    closed --> open: Open
```

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.

See Mermaid documentation for all allowed settings.

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.

Example

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

[markup]
  [markup.highlight]
    # if set to `guessSyntax = true`, there will be no unstyled code even if no language
    # was given BUT mermaid code fences will not work anymore! So this is a mandatory
    # setting for your site
    guessSyntax = false

or pages frontmatter

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

Notice

The notice shortcode shows various types of disclaimers with adjustable title and icon to help you structure your page.

Usage

While the examples are using named parameter you are free to use positional aswell.

{{% notice style="primary" title="There may be pirates" icon="skull-crossbones" %}}
It is all about the boxes.
{{% /notice %}}

{{% notice primary "There may be pirates" "skull-crossbones" %}}
It is all about the boxes.
{{% /notice %}}

Parameter

Examples

By Severity

Info with markup

...and even source code

{{% notice style="info" %}}
An **information** disclaimer

You can add standard markdown syntax:

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

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

> the possiblities are endless (almost - including other shortcodes may or may not work)
{{% /notice %}}

Note

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

Tip

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

Warning

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

Warning with non-default title and icon

{{% notice style="warning" title="Here are dragons" icon="dragon" %}}
A **warning** disclaimer
{{% /notice %}}

Warning without a title and icon

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

By Brand Colors

Primary with title only

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

Secondary with icon only

{{% notice style="secondary" icon="stopwatch" %}}
A **secondary** disclaimer
{{% /notice %}}

By Color

Blue without a title and icon

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

Green with title only

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

Grey with icon only

{{% notice style="grey" icon="bug" %}}
A **grey** disclaimer
{{% /notice %}}

Orange with title and icon

{{% notice style="orange" title="Orange" icon="bug" %}}
A **orange** disclaimer
{{% /notice %}}

Red

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

By Special Color

Default with title and icon

{{% notice style="default" title"Pay Attention to this Note!" icon="skull-crossbones" %}}
Some serious information.
{{% /notice %}}

Transparent with title and icon

{{% notice style="transparent" title"Pay Attention to this Note!" icon="skull-crossbones" %}}
Some serious information.
{{% /notice %}}

Site param

The siteparam shortcode is used to help you print values of site params.

Usage

{{% siteparam <string> %}}

The first required parameter is the name of the site param to be displayed.

Examples

For instance, in this current site, the editURL variable is used in config.toml

[params]
  editURL = "https://github.com/McShelby/hugo-theme-relearn/edit/main/exampleSite/content/"

Use the siteparam shortcode to display its value.

`editURL` Value : {{% siteparam "editURL" %}}

is displayed as

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

Swagger

This shortcode uses the RapiDoc library to display your OpenAPI Specifications.

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.

Example

[params]
  swaggerInitialize = "{ \"theme\": \"dark\" }"

Usage

Just insert give the URL to your OpenAPI Specification like this:

{{< swagger src="https://petstore3.swagger.io/api/v3/openapi.json" >}}

If your page is a leaf or branch bundle, you can also use relative URLs:

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

The src parameter is mandatory and can be either an absolute or a relative URL.

Example

Tabbed views

Choose which content to see across the page. Very handy for providing code snippets for multiple languages or providing configuration in different formats.

Code example

{{< tabs >}}
{{% tab name="python" %}}
```python
print("Hello World!")
```
{{% /tab %}}
{{% tab name="R" %}}
```R
> print("Hello World!")
```
{{% /tab %}}
{{% tab name="Bash" %}}
```Bash
echo "Hello World!"
```
{{% /tab %}}
{{< /tabs >}}

Renders as:

print("Hello World!")

> print("Hello World!")

echo "Hello World!"

Tab views with the same tabs that belong to the same group sychronize their selection:

print("Hello World!")

> print("Hello World!")

echo "Hello World!"

Config example

{{< tabs groupId="config" >}}
{{% tab name="json" %}}
```json
{
  "Hello": "World"
}
```
{{% /tab %}}
{{% tab name="XML" %}}
```xml
<Hello>World</Hello>
```
{{% /tab %}}
{{% tab name="properties" %}}
```properties
Hello = World
```
{{% /tab %}}
{{< /tabs >}}

Renders as:

{
  "Hello": "World"
}

<Hello>World</Hello>

Hello = World