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>

GitLab Issues and Epics

You can pull a list of issues or epics using the relevant shortcode:

1. gitlab/epics
2. gitlab/issues

You must specify either a group (by path) or a project (by ID).

Optional attributes:

1. assignee: Filter issues by assignee username
2. author: Filter issues by author username
3. search: Search term to filter
4. scope: Scope to show (defaults to “all”)
5. labels: Comma-separated list of labels
6. milestone: Filter by milestone name
7. sort: Sort direction
8. order_by: Field to sort by

See the Issues API and Epics API for more details on each attribute.

Examples:

gitlab/epics
  group="my-organization/subgroup"
  labels="bug,group::name"

gitlab/issues
  project="12345"
  assignee="developer-username"
  milestone="1.0"

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

KPI List

For a simple numbered list of KPIs, use the kpi shortcode.

For example, kpi "Marketing".

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>

Handbook only

Many shortcodes have been created by divisions or (sub)departments for their own use. These shortcodes are in organized by division. At this time, there is no known documentation for these shortcuts.

Lists from Data Files

Various shortcodes take the relevant data and displays it, typically in a table format.

1. all-tech-stack
2. misused-terms

Product Categories and Priorities

There are different product category shortcodes

1. categories-features gives a list of product categories split by group and with a list of features in each category.
2. categories-index gives a list of product categories with a link to the corresponding teams in on the product categories page.
3. categories-lookup provides the same list, but also includes manager names and slack channels as an easy lookup.

Team Embeds

department-members and count

department-members renders a table containing a list of team members with a matching “department” in a 3-column table: name, group, “departments”.

For example, department-members "Merge Request Coach"

To count the number of team members in the list, use department-member-count.

For example, department-member-count "Merge Request Coach"

group-by-expertise

Displays a table of team members and their role, based on a match to an “expertise”.

For example, group-by-expertise "Diversity, Inclusion & Belonging Advisory Group"

group-by-slugs

Displays a table of team members and their role based on a space separated list of team member slugs.

For example, group-by-slugs firstlast somename

Member(s)

These shortcodes are used to display specified team members, typically used with other shortcodes or partials.

1. member-and-role-by-gitlab accepts one or more GitLab username.
2. member-by-gitlab accepts a single GitLab username.
3. member-by-name accepts a single team member name.
4. members-by-role accepts a single role.

team-by-departments

Renders a table containing a team and optionally, 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-departments "department-name" >}}

This would search team.yml entries for team members where one of the entries in the departments array is department-name.

Named Arguments

Variation 1

{{< team-by-departments department="department-name" >}}

This is identical to using a single positional argument.

Variation 2

{{< team-by-departments departments="department-name-1,department-name-2" >}}

This will search team.yml for a list of team members whose departments array has at least one element in the given departments parameter.

Variation 3

{{< team-by-departments departments="department-name-1,department-name-2" manager-role="manager, department-name" >}}

This will search team.yml for a list of team members whose departments array has at least one element in the given departments parameter.

In addition, the first team member whose role entry matches the regular expression given in the manager-role parameter. The manager’s partial will be displayed at the top of the table and team members will follow.

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.