Attachments

The Attachments shortcode displays a list of files attached to a page.

Usage

The shortcurt lists files found in a specific folder. 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.

That’s all!

Parameters

For example:

• To match a file suffix of ‘jpg’, use *.jpg (not *.jpg).
• To match file names ending in ‘jpg’ or ‘png’, use .*(jpg|png)

Examples

List of attachments ending in pdf or mp4

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

renders as

Colored styled box

{{%attachments style="orange" /%}}

renders as

{{%attachments style="grey" /%}}

renders as

{{%attachments style="blue" /%}}

renders as

{{%attachments style="green" /%}}

renders as

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 endless possibilities" %}}
Some expandable text.

You can add:

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

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

> the possiblities are endless
{{% /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

{{% 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 four types of disclaimers to help you structure your page.

Usage

{{% notice ( note | info | tip | warning ) [ <string> [ <string> ] ] %}}
Some markup
{{% /notice %}}

The first parameter is required and indicates the type of notice.

The second parameter is optional. If provided, it will be used as the title of the notice. If not provided, then the type of notice will be used as the title. For example, the title of a warning notice will be “Warning”.

The third parameter is optional. If provided, it will set the icon of near the title. For the standard types of notices, this is automatically determined but can be overridden with this parameter. If you want no icon at all, you have to set this parameter to " " (a non empty string filled with spaces).

Examples

Note

...and even source code

{{% notice note %}}
A **notice** disclaimer

You can add:

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

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

> the possiblities are endless
{{% /notice %}}

Info

...and even source code

{{% notice info %}}
An **information** disclaimer

You can add:

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

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

> the possiblities are endless
{{% /notice %}}

Tip

...and even source code

{{% notice tip %}}
A **tip** disclaimer

You can add:

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

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

> the possiblities are endless
{{% /notice %}}

Warning

...and even source code

{{% notice warning %}}
A **warning** disclaimer

You can add:

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

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

> the possiblities are endless
{{% /notice %}}

Notice with default color, custom title and icon

You can customize the title of the notice by passing it as a second parameter.

{{% notice default "Pay Attention to this Note!" "skull-crossbones" %}}
The title is now the parameter that was provided.
{{% /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