Shortcodes

Shortcodes are pre-defined ways to display content in Markdown files. If something looks somewhat like a shortcode, but starts with “partial”, then it’s a partial.

The shortcodes are listed alphabetically after the shortcode explanatory sections.

Shortcodes are easy to make, so many have been created without documentation. If you encounter a shortcode that is not listed, please look for the merge request that introduced it to ask the creator to document it, or ask in the #handbook Slack channel.

Using shortcodes

There are two ways to call shortcodes:

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

More information can be found in the Hugo shortcodes documentation.

Limitations

At times, shortcode rendering may conflict with Markdown rendering. As a result, it is recommended to avoid mixing the two, such as having an alert in a list.

Shortcode colors

Theme colors:

primary secondary success

info danger warning

light dark

Named colors:

blue indigo purple

pink red orange

yellow green teal

cyan gray black

More named colors are available in Bootstrap 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. Highlight
3. YouTube and Vimeo embed

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

Available shortcodes include:

1. Card pane
2. Tabbed panes
3. iframe
4. Include content from another file (see also Includes)

Alerts

The color can be specified, commonly with warning (orange), or danger (red). See the theme colors for available options.

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

For a banner at the top of the page, use pageinfo instead.

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.

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

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

Group pages by category

This custom shortcode can be used on any page to generate a list of other pages in the same page bundle grouped by category, then optionally subcategory.

For any page within the bundle that does not have either attribute, it uses a default:

1. category: Uncategorized
2. subcategory: General

For information on usage, please look at the frontmatter section.

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

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.

This is a regular paragraph.

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

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.

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

The available colors are listed in the shortcodes colors section.

Performance Indicator Embeds

Examples

KPI Summary

{{< performance-indicators/summary org="example" is_key=true />}}

Regular PI Summary

{{< performance-indicators/summary org="example" is_key=false />}}

Key Performance Indicators

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

Regular Performance Indicators

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

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>

Team Embeds

team-by-manager-role

Renders a table containing a team and their manager. These are parsed and built from team.yml entries. This can be used in one of two ways:

• Single Positional Argument
• Named Arguments

The output renders a table element that renders the member/with-team-link partial (from the docsy-gitlab project):

<table>
    <thead>
        <th>Name</th>
        <th>Role</th>
    </thead>
    <tbody>
        <tr>
          <td><member/with-team-link partial for manager></td>
          <td><manager's role></td>
        </tr>
          <tr>
              <td><member/with-team-link partial for team member></td>
              <td><team member's role></td>
          </tr>
    </tbody>
</table>

If no manager is found, this shortcode will return an empty table.

Single Positional Argument

{{< team-by-manager-role "Engineering Manager(.*)Plan:Product Planning" >}}

This would search team.yml entries for a matching entry of the regex, to return a single manager entry. All other entries that have a reports_to field pointing to the manager are then rendered.

Named Arguments

{{< team-by-manager-role role="Engineering Manager(.*)Create:Source Code" team="[,&] (Create:Source Code)" >}}

This searches for a team.yml entry matching the regex given in role for the manager. All entries with a role matching team are then returned as team members.

team-by-manager-slug

Renders a table containing a team and their manager. These are parsed and built from team.yml entries. This can be used in one of two ways:

• Single Positional Argument
• Named Arguments

The output renders a table element that renders the member/with-team-link partial (from the docsy-gitlab project):

<table>
    <thead>
        <th>Name</th>
        <th>Role</th>
    </thead>
    <tbody>
        <tr>
          <td><member/with-team-link partial for manager></td>
          <td><manager's role></td>
        </tr>
          <tr>
              <td><member/with-team-link partial for team member></td>
              <td><team member's role></td>
          </tr>
    </tbody>
</table>

Single Positional Argument

{{< team-by-manager-slug "manager.name" >}}

This would search team.yml entries for a matching slug of manager.name, to return a single manager entry. All other entries that have a reports_to field pointing to the manager are then rendered.

Named Arguments

{{< team-by-manager-slug manager="nmccorrison" team="Engineer(.*)Govern:Threat Insights" >}}

This would search team.yml entries for a matching slug of manager.name, to return a single manager entry. All entries with a role matching the regex in team and a reports_to matching that manager slug are then returned as team members.

View page source - Edit this page - please contribute.