Shortcodes

Note: You can edit this page in the docsy-gitlab theme project. Changes require bumping up the theme version and then pushing it (automation is tracked in an open issue).

Shortcodes are pre-defined ways to display content. The shortcodes are listed alphabetically after the shortcode explanatory sections.

Using shortcodes

There are two ways to call shortcodes:

Markdown

{{% shortcodename parameters %}} with markdown rendering
{{< shortcodename parameters >}} without markdown rendering

More information can be found in the Hugo shortcodes documentation.

Hugo and Docsy shortcodes

The Hugo framework has a few shortcodes included, with a list on the Hugo shortcodes documentation. These include:

  1. Figure (instead of using HTML)
  2. YouTube embed

The base Docsy theme also has a number of shortcodes, which you can find in the Docsy shortcodes documentation.

Available shortcodes include:

  1. Info box
  2. Card pane
  3. Include content from another file

Alerts

Note: This shortcode is part of the Docsy base theme, not a custom shortcode.

The color can be specified, commonly with warning (orange), or danger (red).

Markdown
This is a regular paragraph.

{{% alert title="Note" color="primary" %}}
This is an out of context note that you want to draw a users attention to.
{{% /alert %}}
Output

This is a regular paragraph.

Comments

These comments are turned into markdown comments. They are only viewable when viewing the pages source code and are removed before the page is rendered.

Markdown
This is a paragraph.
{{< comment >}}
This is a comment which is
completely ignored.
{{< /comment >}}
Next paragraph is here.
Output

This is a paragraph. Next paragraph is here.

Output HTML
<p>This is a paragraph.</p>
<p>Next paragraph is here.</p>

Includes

We have a custom shortcode that allows you to include content from another file. Typically, you should use this if you have content that needs to be repeated on more than one page.

While a docsy readfile shortcode also exists, the custom include shortcode is preferred.

Include in the same repository

  1. Create the repeated content in its own file assets/includes/<name-of-snippet>.md.
  2. Insert a copy of the content using code snippet below in the appropriate place on a page.
 {{% include "includes/<name-of-snippet>.md" %}}

Include your GitLab user profile readme

Populate a handbook page with your GitLab user profile readme.

  1. Create your GitLab profile readme.

  2. Create a handbook page with appropriate frontmatter.

  3. For the content of the page, use this code snippet:

    {{% include-readme username="your-gitlab-username" %}}
    

Include from another repository

  1. Create the file in the appropriate repository, such as the public handbook for use in the internal handbook.

  2. Insert a copy of the content using code snippet below with the full URL to the markdown file.

    {{% include-remote "<url>" %}}
    

Trimming unneeded content

If you need to trim some lines from the top of the included file when it’s displayed in the handbook, specify trim=x where x is a number. trim removes the top x + 1 lines from the top of the file. For example, it’s useful to remove an unneeded title because we display the value of Title instead.

By default, trim is 0, and will not trim any lines.

Labels

Attribute Description
name (required) Name for the label. Scoped labels are automatically handled
color (optional) Hex color code for the label, defaults to #428BCA
light (optional) Only required for light colors to make the label text dark

Unscoped labels

{{< label name="Category:Container Registry" >}}
{{< label name="default-priority" color="#FFECDB" light="true" >}}

Category:Container Registry default-priority

Scoped labels

{{< label name="priority::1" color="#cc0000" >}}
{{< label name="Department::Product Security Engineering" color="#69d100" light="true" >}}

priority 1 Department Product Security Engineering

Notes

The classic style notes are smaller and can be used to mention something out of context.

Markdown
This is a regular paragraph.

{{< note >}}
a note is something that needs to be mentioned but is apart from the context.
{{< /note >}}
Output

This is a regular paragraph.

Note: A note is something that needs to be mentioned but is apart from the context.

Panels

To add notes and warning blocks into colorful boxes we have provided a shortcode for a panel. This is similar to the docsy card shortcode but takes up the whole width of the content area and can make use of custom header, body, and footer colors.

Use panels when your description contains more than one paragraph, or a long paragraph. For single and short paragraphs, use alert boxes instead.

Copy paste the following code according to what you want to present to the user and replace only the description.

Markdown
{{< panel header="**Note**" header-bg="blue" >}}
NOTE DESCRIPTION
{{< /panel >}}
Output

Note

NOTE DESCRIPTION

The available colors are any of the named colors below:

blue indigo purple

pink red orange

yellow green teal

cyan gray black

primary secondary success

info danger warning

light dark

Performance Indicator Embeds

Examples

KPI Summary

{{< performance-indicators/summary org="example" is_key=true />}}
Performance Indicator Health
Example KIP

Regular PI Summary

{{< performance-indicators/summary org="example" is_key=false />}}
Performance Indicator Health
Example PI

Key Performance Indicators

{{< performance-indicators/list org="example" is_key=true />}}
Example KIP

KIP Description


Target: 100

URL(s)

Regular Performance Indicators

{{< performance-indicators/list org="example" is_key=false />}}
Example PI

PI example description


Target: 50

Tableau Embeds

tableau

Note: Any other named parameters are added as additional attributes on the <tableau-viz> element.

  • src: URL of visualization to embed
  • height: default: 400px
  • toolbar: visible | hidden, default: hidden
  • hide-tabs: true | false, default: false

Examples

{{< tableau "https://us-west-2b.online.tableau.com/t/gitlabpublic/views/OKR4_7EngKPITest/PastDueSecurityIssues" />}}
{{< tableau height="600px" toolbar="visible" src="https://us-west-2b.online.tableau.com/t/gitlabpublic/views/OKR4_7EngKPITest/PastDueSecurityIssues" >}}
  {{< tableau/filters "Subtype Label"="bug::vulnerability" />}}
  {{< tableau/params "Severity Select"="S2" />}}
{{< /tableau >}}
{{< tableau src="https://10az.online.tableau.com/t/gitlab/views/OKR4_7EngKPITest/PastDueInfraDevIssues" >}}
  {{< tableau/filters "Subtype Label"="bug::vulnerability" />}}
{{< /tableau >}}

tableau/filters

Renders a viz-filter element for each of the key/value pairs passed as parameters.

{{< tableau/filters filter1="value1" filter2="value2" >}}
<viz-filter field="filter1" value="value1"></viz-filter>
<viz-filter field="filter2" value="value2"></viz-filter>

tableau/params

Renders a viz-parameter element for each of the key/value pairs passed as parameters.

{{< tableau/params param1="value1" param2="value2" >}}
<viz-parameter name="param1" value="value1"></viz-parameter>
<viz-parameter name="param2" value="value2"></viz-parameter>