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.
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)
- YouTube embed
The base Docsy theme also has a number of shortcodes, which you can find in the Docsy shortcodes documentation.
Available shortcodes include:
- Info box
- Card pane
- 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).
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.
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 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
Regular Performance Indicators
{{< performance-indicators/list org="example" is_key=false />}}
Example PI
PI example description
- PI Reason 1
- PI Reason 2
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 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>