Skip to main content

Shortcodes

[edit on GitHub]

Content Reuse and Hugo Shortcodes

Chef docs uses shortcodes to maintain text that appears in more than one location and must be consistent in every location.

Writing a shortcode

All shortcode files are written in Markdown and stored in the layouts/shortcodes directory in the chef-web-docs repo.

Adding a Shortcode to a Page

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

{{% chef %}}

Notes, Warnings, and Admonitions

In general, notes, warnings, and admonitions are not the best way to present important information. Before using them ask yourself how important the information is. If you want the information to be returned in a search result, then it is better for the information to have its own topic or section heading. Notes and warnings have a different color than the surrounding text so they can be easily spotted within a doc. If notes and warnings must be used, the approach for using them is as follows.

Notes and warnings are generated by bracketing the text of the note or warning in info, warning or danger shortcodes.

Notes

{{< note >}}
This is a note.
{{< /note >}}

What a note looks like after it’s built:

Note

This is a note.

Warnings

Use sparingly so that when the user sees a warning it registers appropriately:

{{< warning >}}
This is a warning.
{{< /warning >}}

What a warning looks like after it’s built:

Warning

This is a warning.

Danger

Danger should be used rarely and only when there are serious consequences for the user:

{{< danger >}}
This is a danger block.
{{< /danger >}}

This is what a danger block looks like after it’s built:

Danger

This is a danger block.

Foundation Tabs Container

There are four shortcodes that can be combined together to create a container that will allow the user 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 could 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 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 unique on the page.

The foundation_tab shortcode has three parameters:

active

Use active="true" to highlight the tab that 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 is 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 unique 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 unique 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 on the page.

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 >}}

Fontawesome

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)" >}}

Was this page helpful?









Search Results