Shortcodes and content blocks

For the main style guide page, see Documentation Style Guide.

Shortcodes

Shortcodes are snippets of template code that we can include in our Markdown content to display non-standard elements on a page, such as availability details or tabs.

GitLab documentation uses the following shortcodes:

Guide

Use the guide shortcode to create a stylized ordered list of steps. You can nest other shortcodes (like alerts) in guides. However, do this sparingly as the rendered styling can make the content difficult to scan.

Do not use a guide in a guide.

To create a guide, follow this example:

markdown
{{< guide >}}

1. Guide item with text.

   An item with text only.
1. Guide item with alert.

   This is an item with an alert.

   > [!note]
   > This is a note.

{{< /guide >}}

This code renders on the GitLab documentation site as:

    1. Guide item with text.
    An item with text only.
    1. Guide item with alert.

    An item with an alert.

    This is a note.

Guide styling renders only on the GitLab documentation site (https://docs.gitlab.com). In the GitLab product help, a guide appears as a regular ordered list of items.

Use guides for tutorials only. For most tasks, use an ordered list.

Alert boxes

Use alert boxes to call attention to information. Use them sparingly, and never have an alert box immediately follow another alert box.

Alert boxes are generated by using Markdown alerts:

> [!note]
> The text inside the alert box goes here.

The valid alert types are flag, note, warning, and disclaimer. The alert type is case-insensitive.

Flag

Use this alert type to describe a feature’s availability. For information about how to format flag alerts, see Document features deployed behind feature flags.

Note

Use notes sparingly. Too many notes can make topics difficult to scan.

Instead of adding a note:

  • Re-write the sentence as part of a paragraph.
  • Put the information into its own paragraph.
  • Put the content under a new topic title.

If you must use a note, use this format:

> [!note]
> This is something to note.

It renders on the GitLab documentation site as:

This is something to note.

Warning

Use a warning to indicate deprecated features, or to provide a warning about procedures that have the potential for data loss.

> [!warning]
> This is something to be warned about.

It renders on the GitLab documentation site as:

This is something to be warned about.

Disclaimer

If you must write about features we have not yet delivered, add a disclaimer about forward-looking statements near the content it applies to.

Disclaimer alerts are populated by using a template and should not include any other text.

Add a disclaimer like this:

> [!disclaimer]

It renders on the GitLab documentation site with the disclaimer text:

This page contains information related to upcoming products, features, and functionality. It is important to note that the information presented is for informational purposes only. Please do not rely on this information for purchasing or planning purposes. The development, release, and timing of any products, features, or functionality may be subject to change or delay and remain at the sole discretion of GitLab Inc.

If all of the content on the page is not available, use the disclaimer about forward-looking statements once at the top of the page.

If the content in a topic is not ready, use the disclaimer in the topic.

For more information, see Promising features in future versions.

Blockquotes

Avoid using blockquotes in the product documentation. They can make text difficult to scan. Instead of a blockquote, consider using:

The GitLab Flavored Markdown (GLFM) page is a rare case that uses blockquotes to differentiate between plain text and rendered examples. However, in most cases, you should avoid them.

Tabs

On the documentation site, you can format text to display as tabs.

Do not put version history bullets, topic headings, HTML, or tabs in tabs. Only use paragraphs, lists, alert boxes, and code blocks. Other styles might not render properly. When in doubt, keep things simple.

To create a set of tabs, follow this example:

{{< tabs >}}

{{< tab title="Tab one" >}}

Here's some content in tab one.

{{< /tab >}}

{{< tab title="Tab two" >}}

Here's some other content in tab two.

{{< /tab >}}

{{< /tabs >}}

This code renders on the GitLab documentation site as:

Here’s some content in tab one.

Here’s some other content in tab two.

For tab titles, be brief and consistent. Ensure they are parallel, and start each with a capital letter. For example:

  • Linux package (Omnibus), Helm chart (Kubernetes) (when documenting configuration edits, follow the configuration edits guide)
  • 15.1 and earlier, 15.2 and later

Until we implement automated testing for broken links to tabs, do not link directly to a single tab. For more information, see issue 225.

See Pajamas for more details on tabs.

Collapsible panels

Collapsible panels are closed by default and require a title. In the rendered documentation, you must expand the panel to view the content inside it.

markdown
{{< collapsible title="Collapsible panel example" >}}

This content appears inside the collapsible panel.

{{< /collapsible >}}

Only use collapsible panels on GitLab Duo pages in the availability details section for information about supported LLMs, editors, and self-hosted model availability.

Do not use collapsible panels for other content.

Cards

Use cards to create landing pages with links to sub-pages.

To create a set of cards, follow this example:

markdown
{{< cards >}}

- [The first page](first_page.md)
- [Another page](another/page.md)
- [One more page](one_more.md)

{{< /cards >}}

Additionally, cards support external URLs with optional descriptions. Use the following syntax:

markdown
{{< cards >}}

- [External page title](https://example.com "Optional Description")

{{< /cards >}}

Cards render only on the GitLab documentation site (https://docs.gitlab.com). In the GitLab product help, a set of cards appears as an unordered list of links.

Card descriptions are populated from the description metadata on the Markdown page headers.

Use cards on top-level pages where the cards are the only content on the page.

Maintained versions

Use the maintained versions shortcode to create an unordered list of the currently maintained GitLab versions as specified by the maintenance policy:

markdown
{{< maintained-versions >}}

Maintained versions render only on the pre-release version of the GitLab documentation site (https://docs.gitlab.com). In all other cases and in /help, a link to the documentation site is shown instead.

Glossary tooltip

Use the shortcode for a glossary tooltip to provide a short definition that appears as a tooltip on hover. For example:

markdown
To do this thing, use {{< glossary-tooltip text="the term" >}}.

When the user hovers on ​, a tooltip is displayed.

If a glossary page is configured for the tooltip and the user selects the anchor text, a related glossary page opens.

Usage guidance

Use a glossary tooltip if the definition is a single, concise sentence, and try to use no more than 60 characters. For longer definitions, use a glossary page.

Do not use more than five to ten tooltips on a page. Each tooltip slows down the reader. Be careful not to overload users with definitions.

Use glossary tooltips in these cases:

  • For the first occurrence of a GitLab-specific term on a page.
  • For terms readers might not know, like artifact or analyzer.

Do not use glossary tooltips in these cases:

  • For common terms like repository, branch, or commit.
  • For every instance of a term.
  • As a replacement for acronyms. If you can spell out the acronym on first use, and it’s an industry standard, do not use a glossary tooltip.

Create a glossary term

Add glossary definitions to the glossary.yaml file in the docs-gitlab-com repository. Each definition should be short and not contain links.

Glossary terms are defined in the terms block with the following fields:

term_id

Unique ID for the glossary term. To link to the glossary section, the term_id must match the anchor on the glossary page for that term.

display_name

Text that displays in the documentation. The display_name field is case insensitive. For example, a text parameter in the shortcode of “attack surface” matches the term “Attack Surface” in the glossary.yaml file.

glossary

Optional. Link to the glossary definition for the term. If included, the term_id is appended to the end of the glossary_url. For example, /user/application_security/terminology#attack-surface.

short_description

The text that appears when the user hovers over the tooltip.

Example glossary term definition in glossary.yaml file:

yaml
terms:
  - term_id: attack-surface
    display_name: Attack Surface
    glossary: *security_glossary
    short_description: The different places in an application that are vulnerable to attack

Glossaries are defined at the top of the glossary.yaml file.

The first line consists of two unique IDs:

  1. Short name for the glossary.
  2. Longer identifier of the glossary. For glossary terms that link to this glossary their glossary field must match this value.
glossary_url

Root URL of the glossary page that the term is defined in.

Example glossary definition in glossary.yaml file:

yaml
# Glossary files
security: &security_glossary
  glossary_url: "/user/application_security/terminology"

Combining these examples results in the following:

  • The phrase “Attack Surface” is shown in the documentation as a link.
  • When the user hovers over the link, the content of the short_description field is shown in a tooltip.
  • When the user selects the link, the glossary page opens at the anchor attack-surface.