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:
{{% 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:
- Figure (instead of using HTML)
- Highlight
- 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:
- Card pane
- Tabbed panes
iframe
- 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).
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 %}}
This is a regular paragraph.
Note
This is an out of context note that you want to draw a users attention to.
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.
This is a paragraph. Next paragraph is here.
<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
- Create the repeated content in its own file
assets/includes/<name-of-snippet>.md
. - 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.
-
Create your GitLab profile readme.
-
Create a handbook page with appropriate frontmatter.
-
For the content of the page, use this code snippet:
{{% include-readme username="your-gitlab-username" %}}
Include from another repository
-
Create the file in the appropriate repository, such as the public handbook for use in the internal handbook.
-
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.
This is a regular paragraph.
{{< note >}}
a note is something that needs to be mentioned but is apart from the context.
{{< /note >}}
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.
{{< panel header="**Note**" header-bg="blue" >}}
NOTE DESCRIPTION
{{< /panel >}}
NOTE DESCRIPTION
The available colors are listed in the shortcodes colors section.
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
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 embedheight
: 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
Note: These shortcodes currently exist in the handbook project only.
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.