Hugo shortcodes

This page describes shortcodes that we use in Chef documentation.

Shortcodes add short snippets of Hugo code, Markdown, or HTML to a page. For example, the readfile shortcode can add a text file to a page, the note shortcode puts text inside an HTML div, and the automate_cli_commands shortcode reads through YAML files and outputs formatted text from those files.

Accordion list

The accordion shortcodes create a Foundation Framework Accordion.

To add an accordion, wrap the accordion-list shortcode around as many accordion-item shortcodes as you want.

The following example creates a basic accordion list with a single list item:

{{< accordion-list >}}
{{< accordion-item accordion-title="List item description" >}}
Hello, world.
{{< /accordion-item >}}
{{< /accordion-list >}}

Parameters

accordion-list parameters

The accordion-list shortcode has the following parameters:

data-multi-expand: Whether more than one list item can be displayed at the same time.
Default value: false
data-allow-all-closed: Whether all list items can be closed at the same time.
Default value: false
id: A unique ID on the page. This adds deep linking to the list. Required if accordion-title-link is used in the accordion-item.

accordion-item parameters

The accordion-item shortcode has the following parameters:

accordion-title: The accordion item title.
accordion-title-link: A link to the accordion list item. This adds deep linking to the list item. Required if id is used in accordion-list.
is-active: Whether the list item is active by default.
Default value: false

Examples

The following example creates and accordion with two list items, the second is active by default, all items can be displayed at the same time, and both can be closed at the same time.

{{< accordion-list data-multi-expand="true" data-allow-all-closed="true" >}}
{{< accordion-item accordion-title="List item description" >}}
Hello, world.
{{< /accordion-item >}}
{{< accordion-item accordion-title="Active item" is-active="true" >}}
This is active by default
{{< /accordion-item >}}
{{< /accordion-list >}}

Which looks like this:

List item description
Hello, world.
Active item
This is active by default

The following creates an accordion list with deep linking and the first item is active.

{{< accordion-list id="my-accordion" data-multi-expand="true" data-allow-all-closed="true" >}}
  {{< accordion-item accordion-title="Item 1" accordion-title-link="accordion-list-deep-linking-item1" is-active="true" >}}
    Content for item 1
  {{< /accordion-item >}}
  {{< accordion-item accordion-title="Item 2" accordion-title-link="accordion-list-deep-linking-item2" >}}
    Content for item 2
  {{< /accordion-item >}}
{{< /accordion-list >}}

Which produces this:

Item 1
Content for item 1
Item 2
Content for item 2

`figure` shortcode

Use the figure shortcode to add images to a page.

Basic example:

{{< figure src="path/to/image" >}}

figure accepts the following parameters:

src: The path to the image file. Required.
link: An HTML link. Optional
target: The target attribute for a link. Optional.
alt: Alt text for an image.
title: Image title. Optional.
caption: An image caption. Optional.
class: A class to add to an image. Optional.
height: The image height. Optional.
width: The image width. Optional.

`fontawesome` shortcode

The fontawesome shortcode will display any free Font Awesome icon in a page.

It accepts the following parameters:

background-color
border
border-radius
class
color
font-size
margin
padding

The only required parameter is class, which is the same as the class name of the icon.

The following shortcode examples will display these icons:

{{< fontawesome class="fas fa-ellipsis-h" >}}
{{< fontawesome class="fas fa-anchor" font-size="3rem" border="2px dashed" padding="1px" border-radius="5px" >}}
{{< fontawesome class="fas fa-archive" color="#cc814b" margin="0 0 0 12px">}}
{{< fontawesome class="far fa-address-book" background-color="DarkBlue" color="rgb(168, 218, 220)" >}}

Foundation tabs container

You can combine four shortcodes to create a tabbed container that allows users to click on a tab to reveal content in a matching panel. For example, you may want to display matching Ruby and YAML code blocks. You can create two tabs, one titled Ruby and the other YAML, and the user can click on one tab to show the Ruby code block and another tab to show the YAML code block. See the example below.

The four shortcodes are:

foundation_tabs
foundation_tab
foundation_tabs_panels
foundation_tabs_panel

These shortcodes use the Zurb Foundation Tabs component.

The container consists of two parts, the tabs and the panels.

Tabs

Each tab is created with a foundation_tab shortcode. Use as many foundation_tab shortcodes as you need to display the number of code blocks or text blocks that you want the user to be able to click on and reveal.

All foundation_tab shortcodes must be contained within opening and closing foundation_tabs shortcodes.

For example:

{{< foundation_tabs tabs-id="ruby-python-panel" >}}
  {{< foundation_tab active="true" panel-link="ruby-panel" tab-text="Ruby" >}}
  {{< foundation_tab panel-link="python-panel" tab-text="Python" >}}
{{< /foundation_tabs >}}

Tab parameters

The foundation_tabs shortcode has one parameter:

tabs-id: This value must be identical to the tabs-id value in the foundation_tabs_panels shortcode, but otherwise it must be a unique HTML ID on the page.

The foundation_tab shortcode has three parameters:

active: Use active="true" to highlight the tab that the user will see when they first load the page. Only add this value to one tab. The matching foundation_tabs_panel should also have active="true" in its parameters.
panel-link: This is the value of the panel ID that this tab will link to. This must be identical to the panel-id value in the matching foundation_tabs_panel shortcode.
tab-text: The text in the tab that the user will click on.

Panels

Each tab has a matching panel which is created with foundation_tabs_panel shortcodes. The Markdown text that’s displayed in each panel must be contained in opening and closing foundation_tabs_panel shortcodes.

All foundation_tab_panel shortcodes must contained within opening and closing foundation_tabs_panels shortcodes.

For example:

{{< foundation_tabs_panels tabs-id="ruby-python-panel" >}}
  {{< foundation_tabs_panel active="true" panel-id="ruby-panel" >}}
  ```ruby
  puts 'Hello, world!'
  ```
  {{< /foundation_tabs_panel >}}

  {{< foundation_tabs_panel panel-id="python-panel" >}}
  ```python
  print('Hello, world!')
  ```
  {{< /foundation_tabs_panel >}}
{{< /foundation_tabs_panels >}}

Panel parameters

The foundation_tabs_panels shortcode has one parameter:

tabs-id: This value must be identical to the tabs-id value in the foundation_tabs shortcode, but otherwise it must be a unique HTML ID on the page.

The foundation_tabs_panel shortcode has two parameters:

active: Use active="true" to indicate which panel the user will see when they first load the page. This value should also be added to the panels matching tab. Only add this value to one panel.
panel-id: The HTML ID attribute of the panel. This value must be identical to the panel-link value in the matching foundation_tab shortcode that will link to this panel. This value must be a unique HTML ID on the page.

Example

Below is an example of a container that shows three code blocks in three languages. You can copy and paste the code below into a page to get started. Note that the tabs-id and panel-id/panel-link values must be unique HTML IDs on the page.

Ruby
Python
Go

puts 'Hello, world!'

print('Hello, world!')

package main

import "fmt"

func main() {
    fmt.Println("Hello, world!")
}

{{< foundation_tabs tabs-id="ruby-python-go-panel" >}}
  {{< foundation_tab active="true" panel-link="ruby-panel" tab-text="Ruby">}}
  {{< foundation_tab panel-link="python-panel" tab-text="Python" >}}
  {{< foundation_tab panel-link="golang-panel" tab-text="Go" >}}
{{< /foundation_tabs >}}

{{< foundation_tabs_panels tabs-id="ruby-python-go-panel" >}}
  {{< foundation_tabs_panel active="true" panel-id="ruby-panel" >}}
  ```ruby
  puts 'Hello, world!'
  ```
  {{< /foundation_tabs_panel >}}

  {{< foundation_tabs_panel panel-id="python-panel" >}}
  ```python
  print('Hello, world!')
  ```
  {{< /foundation_tabs_panel >}}
  {{< foundation_tabs_panel panel-id="golang-panel" >}}
  ```go
  package main

  import "fmt"

  func main() {
      fmt.Println("Hello, world!")
  }
  ```
  {{< /foundation_tabs_panel >}}
{{< /foundation_tabs_panels >}}

`highlight` shortcode

You can add code examples using the highlight shortcode.

For example, this:

{{< highlight ruby >}}
puts 'Hello, world!'
{{< /highlight >}}

produces:

puts 'Hello, world!'

`icons` shortcode

The icons shortcode renders Google Material Symbols into a page.

It accepts the following parameters:

icon

The Material Symbols icon name.

class

Add the icon class.

Required value: material-symbols-outlined

Optional value: icon-filled. This renders the filled version of the icon.

Examples

To add an icon, define the class and icon name. For example, this adds Material Symbols description icon:

Download {{< icons class="material-symbols-outlined" icon="description" >}} the file.

Which looks like this:

Download the file.

You can add the filled description icon by adding the icon-filled class:

Download {{< icons class="material-symbols-outlined icon-filled" icon="description" >}} the file.

Which looks like this:

Download the file.

Notices

Note, warning, and danger notice boxes have a different color than the surrounding text so they can be spotted within a document. If you must use a note or warning, bracket the text of the note or warning in a note, warning, or danger shortcode.

See the notices guidelines for usage recommendations.

Notes

Add a note using the note shortcode:

{{< note >}}

This is the text of a note.

{{< /note >}}

Warnings

Add a warning using the warning shortcode.

{{< warning >}}

This is text in a warning.

{{< /warning >}}

Danger

Add a danger notice using the danger shortcode.

{{< danger >}}

This is text in a warning.

{{< /danger >}}

`readfile` shortcode

The readfile shortcode adds text from a file to a page. You can add a Markdown file, HTML file, or code file by specifying the path to the file from the project root directory.

By default, it accepts a Markdown file:

{{< readfile file="content/workstation/reusable/md/example.md" >}}

You can also add an HTML file:

{{< readfile file="content/workstation/reusable/html/example.html" html="true" >}}

You can pass in a sample code file:

{{< readfile file="content/workstation/reusable/rb/example.rb" highlight="ruby" >}}

or:

{{< readfile file="content/workstation/reusable/json/example.json" highlight="json" >}}

See the full list of highlighting languages and aliases that Hugo accepts.

It also converts between JSON, YAML, TOML, and XML data types using the remarshal option. For example:

{{< readfile file="data/test/test.json" remarshal="yaml" >}}

`relref` shortcode

We recommend using Hugo’s built-in relref shortcode for making relative links to other pages in Chef’s documentation. If a link is made to a page that doesn’t exist, the site build will fail when Hugo generates a preview of the site. This will help us prevent dead links in our own documentation if a page is moved or deleted.

To format link to pages:

[link text]({{< relref "some_page" >}})
[link text]({{< relref "section/some_page" >}})

To format links to headings:

[link text]({{< relref "#heading_on_this_page" >}})
[link text]({{< relref "some_page#heading_on_other_page" >}})
[link text]({{< relref "section/some_page#heading_on_other_page" >}})

Note

relref doesn’t validate links to headings, only page links. Double-check your headings when adding or updating heading links.

Create a new shortcode

You can create shortcodes in Markdown or HTML format in layouts/shortcodes or in the chef/chef-docs-theme repository layouts/shortcodes directory.

In repositories other than chef-web-docs, store shortcodes in layouts/shortcodes/REPOSITORY_NAME/.

Add a shortcode to a page

The two types of shortcodes are Markdown and HTML. The shortcode type determines how it’s added to a page and how Hugo processes the text when it renders the page into HTML.

Note

If you add a Markdown shortcode to a page using HTML shortcode delimiters, Hugo will assume that the text is already formatted in HTML and won’t run the shortcode file through its Markdown processor, leaving the bare Markdown in the HTML page output.

Markdown shortcodes

A Markdown shortcode must be processed into HTML when Hugo builds the site.

To include a Markdown shortcode in a page, wrap the name of the shortcode file, without the file type suffix, in between double curly braces and percent characters, {{% SHORTCODE %}}. For example, if you wanted to add the chef.md shortcode to a page, add the following text to the Markdown page:

{{% chef %}}

For shortcodes located in a repository other than chef-web-docs, use {{% REPO_NAME/SHORTCODE %}}. For example:

{{% chef-workstation/bento %}}

HTML shortcodes

To include an HTML shortcode in a page, wrap the name of the shortcode file, without the file type suffix, in between double curly braces and angle brackets, {{< SHORTCODE >}}. For example, add the following text to a page if you want to add the chef_automate_mark.html shortcode:

{{< chef_automate_mark >}}

For shortcodes located in a repository other than chef-web-docs, use {{< REPO_NAME/SHORTCODE >}}. For example:

{{< automate/automate_cli_commands >}}

Parameters

Some shortcodes accept positioned or named parameters. For example, the example_fqdn shortcode requires a hostname, which is added like this: {{< example_fqdn "HOSTNAME" >}}, and produces the following output: HOSTNAME.example.com.

The Fontawesome Shortcode accepts named parameters. For example, it accepts a class value which is added like this: {{< fontawesome class="fas fa-ellipsis-h" >}}

See the Fontawesome Shortcode section for more examples.

Nested content

Some shortcodes nest around Markdown text. Those shortcodes are closed with a forward slash / before the name of the closing shortcode. For example:

{{< shortcode_name >}}

Some Markdown text.

{{< /shortcode_name >}}

See the Notes and Warnings and the Foundation Tabs for examples of nested shortcodes.

Hugo shortcodes

Accordion list

Parameters

accordion-list parameters

accordion-item parameters

Examples

figure shortcode

fontawesome shortcode

Foundation tabs container

Tabs

Tab parameters

Panels

Panel parameters

Example

highlight shortcode

icons shortcode

Examples

Notices

Notes

Warnings

Danger

readfile shortcode

relref shortcode

Create a new shortcode

Add a shortcode to a page

Markdown shortcodes

HTML shortcodes

Parameters

Nested content

`figure` shortcode

`fontawesome` shortcode

`highlight` shortcode

`icons` shortcode

`readfile` shortcode

`relref` shortcode