Skip to content

Latest commit

 

History

History
383 lines (255 loc) · 12.8 KB

shortcodes.md

File metadata and controls

383 lines (255 loc) · 12.8 KB

+++ title = "Hugo Shortcodes" draft = false gh_repo = "chef-web-docs"

[menu] [menu.overview] title = "Shortcodes" identifier = "overview/style/hugo/shortcodes" parent = "overview/style/hugo" weight = 30 +++

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.

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]({{< relref "notices" >}}) 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 */>}}

fontawesome shortcode

{{< readfile file="content/style/reusable/md/fontawesome_shortcode.md" >}}

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 a unique HTML ID 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 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 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.

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

puts 'Hello, world!'

{{< /foundation_tabs_panel >}}

{{< foundation_tabs_panel panel-id="python-panel" >}}

print('Hello, world!')

{{< /foundation_tabs_panel >}} {{< foundation_tabs_panel panel-id="golang-panel" >}}

package main

import "fmt"

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

{{< /foundation_tabs_panel >}} {{< /foundation_tabs_panels >}}

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

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.

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 does not 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 checkout your headings when adding or updating heading links.

{{< /note >}}

svg shortcode

The svg shortcode will add an inline SVG icon to a string of text.

The svg shortcode takes one parameter, file, which is the file path to the SVG file.

For example:

Click on the web asset icon ({{</* svg file="themes/docs-new/static/images/web-asset.svg" */>}}).

produces:

Click on the web asset icon ({{< svg file="themes/docs-new/static/images/web-asset.svg" >}}).

Create a new shortcode

Shortcode files are written in Markdown or HTML and are stored in layouts/shortcodes or themes/docs-new/layouts/shortcodes in the chef/chef-web-docs repository.

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

Add a shortcode to a page

There are two types of shortcodes, Markdown and HTML. The type of shortcode determines how it is 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 will not run the shortcode file through its Markdown processor, leaving the bare Markdown in the HTML page output. {{< /note >}}

Markdown shortcodes

A Markdown shortcode must be processed into HTML by Hugo when the site is built.

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 wanted 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: {{< example_fqdn "HOSTNAME" >}}.

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

We have some shortcodes that nest around Markdown content that is included in the text of a page. Those shortcodes are all written in HTML. Note the slash / before the name of the closing shortcode.

{{</* shortcode_name */>}}

Some Markdown text.

{{</* /shortcode_name */>}}

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