Documentation Writers' Toolkit Write Shortcodes

Shortcodes

Shortcodes are snippets you use in source files to calling built-in or custom templates. Shortcodes templates avoid the need for HTML in Markdown and ensure consistency across the documentation set.

The following sections describe shortcodes available for use in Grafana Markdown files. To learn about other shortcodes, refer to the Hugo shortcode documentation.

Admonition

The admonition shortcode renders its content in a blockquote or stylized banner. The style depends on the admonition type as defined in Writers’ Toolkit Style conventions.

The content of the admonition must be within opening and closing tags, and the type of admonition must be within quotes.

Use a tip when you want to show the reader how to do something that isn’t necessarily obvious. Tips should be helpful, additional information. You can think of some tips as tricks. Your reader can feel free to skip them if they want because they don’t contribute to core understanding.

Examples

The following example renders an admonition of type note with the message Kingston is the capital of Jamaica.:

markdown Copy

{{< admonition type="note" >}}
Kingston is the capital of Jamaica.
{{< /admonition >}}

Produces:

The following example renders an admonition of type tip with the message This also applies to headings that contain a forward slash or parentheses or square brackets.:

markdown Copy

{{< admonition type="tip" >}}
This also applies to headings that contain a forward slash or parentheses or square brackets.
{{< /admonition >}}

Produces:

Card grid

The card-grid shortcode renders a responsive grid of card elements that fits the width of its container.

Grid parameters

Card parameters (type=“simple”)

Examples

Render a card grid with a minimum card width of sm and a simple card type:

markdown Copy

---
my_card_grid:
  type: simple
  min: sm
  items:
    - title: Grafana Alerting
      href: /docs/grafana-cloud/alerting-and-irm/alerting/
      description: >-
        Allows you to learn about problems in your systems moments after they occur. Monitor your incoming metrics data or log entries and set up your Alerting system to watch for specific events or circumstances and then send notifications when those things are found.
      logo: /media/docs/grafana-cloud/alerting-and-irm/grafana-icon-alerting.svg
      height: 24
    - title: Grafana SLO
      href: /docs/grafana-cloud/alerting-and-irm/slo/
      description: >-
        Provides a framework for measuring the quality of service you provide to users. Use SLOs to collect data on the reliability of your systems over time and as a result, help engineering teams reduce alert fatigue, focus on reliability, and provide better service to your customers.
      logo: /media/docs/grafana-cloud/alerting-and-irm/grafana-icon-slo.svg
      height: 24
---

{{< card-grid key="my_card_grid" >}}

Code

The code shortcode provides the ability to show multiple snippets of code in different languages. When a user selects a language, the website sets other code blocks on the page to that language. The website saves the selected language to browser storage and persists it across navigation.

Example

markdown Copy

{{< code >}}

```bash
curl "https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/ActivityService.AddActivity"
```

```go
package main

import (
  "context"
)

func main() {

  ...
```

```javascript
import { GrafanaIncidentClient, ActivityService } from '@grafana/incident-node';

// https://grafana.com/docs/grafana-cloud/incident/api/auth/#get-a-service-account-token
const serviceAccountToken = process.env.GRAFANA_CLOUD_SERVICE_ACCOUNT_TOKEN;
const client = new GrafanaIncidentClient(
  "https://your-stack.grafana.net",
  serviceAccountToken
);

...
```

```json
POST https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/ActivityService.AddActivity
Content-Type="application/json; charset=utf-8"
Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...
```

{{< /code >}}

Produces:

bashGoJavaScriptjson

Copy

bash Copy

curl "https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/ActivityService.AddActivity"

Go Copy

package main

import (
  "context"
)

func main() {

  ...

JavaScript Copy

import { GrafanaIncidentClient, ActivityService } from '@grafana/incident-node';

// https://grafana.com/docs/grafana-cloud/incident/api/auth/#get-a-service-account-token
const serviceAccountToken = process.env.GRAFANA_CLOUD_SERVICE_ACCOUNT_TOKEN;
const client = new GrafanaIncidentClient(
  "https://your-stack.grafana.net",
  serviceAccountToken
);

...

json Copy

POST https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/ActivityService.AddActivity
Content-Type="application/json; charset=utf-8"
Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...

Collapse

The collapse shortcode toggles visibility of sections of content, often helpful when hiding and showing large amounts of content.

Example

markdown Copy

{{< collapse title="Title of hidden content" >}}
Kingston is the capital of Jamaica.
{{< /collapse >}}

Produces:

Use this shortcode for:

• Deprecated content: Features that have been deprecated, but still need to be documented for some time.
• Configuration options: Features that have several ways they can be configured.

Add a lead-in sentence and a title that, taken together, are descriptive enough for the reader to guess what’s included in the collapsed content. Don’t duplicate headings in the title parameter.

You can’t do the following with this shortcode:

• Use them as page headings
• Control the size of the title text
• Add images or videos between the shortcode tags

Deprecation example

markdown Copy

#### BoltDB (deprecated)

The following example is for a deprecated store and you shouldn't use it for new Loki deployments:

{{< collapse title="boltdb-shipper" >}}
Also known as _boltdb-shipper_ during development.
The single store configurations for Loki utilize the chunk store for both chunks and the index, requiring just one store to run Loki.
{{< /collapse >}}

Produces:

BoltDB (deprecated)

The following example is for a deprecated store and you shouldn’t use it for new Loki deployments:

Configuration options example

markdown Copy

#### `6-Compactor-Snippet.yaml`

The following partial configuration sets the compactor to use S3 and run the compaction every five minutes.

{{< collapse title="Example" >}}

```yaml
compactor:
  working_directory: /tmp/loki/compactor
  shared_store: s3
  compaction_interval: 5m
```

{{< /collapse >}}

Produces:

6-Compactor-Snippet.yaml

The following partial configuration sets the compactor to use Amazon S3 and runs the compaction every 5 minutes.

Example

Docs/experimental-deployment

The docs/experimental-deployment shortcode produces a note admonition with the preferred copy for explaining that the described deployment is experimental.

It takes no parameters.

Example

markdown Copy

{{< docs/experimental-deployment >}}

Produces:

Docs/experimental

The docs/experimental shortcode produces a note admonition with the preferred copy for explaining that the described product or feature is experimental.

Example

markdown Copy

{{< docs/experimental product="experimental-feature" featureFlag="its-feature-flag" >}}

Produces:

Docs/play

The docs/play shortcode produces a note admonition with the preferred copy for linking to a Grafana Play dashboard.

Example

markdown Copy

{{< docs/play title="Time Series Visualizations" url="https://play.grafana.org/d/000000016/1-time-series-graphs" >}}

Produces:

Docs/private-preview

The docs/private-preview shortcode produces a note admonition with the preferred copy for explaining that the described product or feature is in private preview.

markdown Copy

{{< docs/private-preview product="private-preview-feature" >}}

Produces:

Docs/public-preview

The docs/public-preview shortcode produces a note admonition with the preferred copy for explaining that the described product or feature is in public preview.

markdown Copy

{{< docs/public-preview product="public-preview-feature" >}}

Produces:

markdown Copy

{{< docs/public-preview product="public-preview-feature" featureFlag="its-feature-flag" >}}

Produces:

Docs/reference

The docs/reference shortcode lets you specify different destinations for the same link that depend on where you publish the source file.

You set all possible destinations in one part of the file, usually at end of the file, like a footer.

For example, a page in versioned Grafana documentation is also mounted in the Grafana Cloud documentation. The page in Grafana should link to the Grafana dashboards page but the page in Grafana Cloud should link to the Grafana Cloud dashboards page.

Set the reference at the end of the page as follows:

markdown Copy

{{% docs/reference %}}
[dashboards]: "/docs/grafana/ -> /docs/grafana/<GRAFANA_VERSION>/dashboards"
[dashboards]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/dashboards"
{{% /docs/reference %}}

The content within the shortcode tags is as follows:

[LABEL]: "PROJECT PATH PREFIX -> REFERENCE"

• LABEL - The label you’ll use in the reference-style links in the file. In the preceding example, the label is dashboards. The label can be multiple words like [dashboard docs] and can include spaces.

• PROJECT PATH PREFIX - Designates the target project. In the preceding example, the path prefixes are /docs/grafana/ for Grafana and /docs/grafana-cloud/ for Cloud.

• REFERENCE - The path to the destination file. This shortcode supports version substitution using values like <GRAFANA_VERSION>. To learn about version substitution, refer to About version substitution. Don’t include trailing slashes in the path.

Then add the link in the body of the file in the following format:

markdown Copy

For more information about Grafana dashboards, refer to [Dashboards][dashboards].

• If the page you’re on is /docs/grafana-cloud/alerting/, the returned link is /docs/grafana-cloud/dashboards/.
• If the page you’re on is /docs/grafana/latest/alerting/, the inferred version is latest, and the returned link is /docs/grafana/latest/dashboards/.
• If the page you’re on is /docs/grafana/next/alerting/, the inferred version is next, and the returned link is /docs/grafana/next/dashboards/.

Other use cases

Markdown reference-style links are also useful when you want to link to the same destination multiple times in one file. It allows you to specify the link destination once while you use the label multiple times. For example:

Reference:

markdown Copy

[Grafana website]: www.grafana.com

Body text:

markdown Copy

Find more information on [Grafana][Grafana website].

Docs/shared

The docs/shared shortcode lets you reuse content across the Grafana website by including shared pages from source content repositories. The source content repository must explicitly share the page by placing it into its shared directory.

To share content, follow these steps:

1. Create a Markdown file containing the shared source and include headless: true in the front matter to prevent the website from publishing the page.
2. Store the file in a shared folder.
3. To include the shared content in a Markdown file, insert the docs/shared shortcode with the following named parameters:

For more detailed instructions, refer to Reuse shared content.

Examples

The following shortcode inserts the content from the oauth2-block.md file. The lookup path is relative to the shared folder in the agent source repository.

markdown Copy

{{< docs/shared lookup="flow/reference/components/oauth2-block.md" source="agent" version="<AGENT VERSION>" >}}

The following shortcode inserts shared-page.md from the shared folder in the enterprise-metrics project. The version used matches the version of the page including the file. Headings are offset by one level, so if the source content contains an h1, the resulting heading is an h2.

markdown Copy

{{< docs/shared lookup="shared-page.md" source="enterprise-metrics" version="<GEM_VERSION>" leveloffset="+1" >}}

Figure

The figure shortcode renders an image with a caption using an HTML <figure> element. This shortcode allows you more control over how to render an image, but if you don’t need these options, you can use basic Markdown to add images.

To add a figure, insert the figure shortcode with the following named parameters:

Example

In this example, the image has a CSS class that makes the image display floated to the right.

markdown Copy

{{< figure class="float-right"  src="/static/img/docs/grafana-cloud/k8sPods.png" caption="Pod view in Grafana Kubernetes Monitoring" >}}

This example sets the image’s display size to have a maximum width of 50%. The max-width value must have a unit of measurement, such as pixels or percentages.

markdown Copy

{{< figure max-width="50%" src="/static/img/docs/grafana-cloud/k8sPods.png" caption="Pod view in Grafana Kubernetes Monitoring" >}}

This examples sets the image’s display size to have a maximum width of 500px, and sets the class and link-class properties to center the image on the page. It sets the original width and height values of the image without any unit of measurement such as pixels or percentages.

markdown Copy

{{< figure src="/static/img/docs/grafana-cloud/k8sPods.png" width="1275" height="738" max-width="500px" class="w-100p" link-class="w-fit mx-auto d-flex flex-direction-column" caption="Pod view in Grafana Kubernetes Monitoring" caption-align="center" >}}

Hero (simple)

A hero section is a large section that contains a title, description, and image, usually placed at the top of a page.

The hero-simple shortcode renders a hero section with an optional title, description, and image. To add a simple hero, insert the hero-simple shortcode using the following named parameters:

You can provide shortcode arguments by:

• Adding front matter and referencing it front matter with the key argument.
• Adding them directly to the shortcode itself.

Shortcode arguments override those in the front matter. If you don’t provide any arguments, the shortcode uses default values.

Examples

Insert a simple hero using front matter:

markdown Copy

---
my_hero:
  title: Alerts and IRM
  level: 1
  image: /media/docs/grafana-cloud/alerting-and-irm/grafana-cloud-docs-hero-alerts-irm.svg
  width: 110
  height: 110
  description: >-
    Alerts & IRM is Grafana Cloud’s Incident Response Management (IRM) solution, which enables you to detect, respond, and learn from incidents in one centralized platform.
---

{{< hero-simple key="my_hero" >}}

Insert a simple hero using shortcode arguments:

markdown Copy

{{< hero-simple title="Alerts and IRM" level="1" image="/media/docs/grafana-cloud/alerting-and-irm/grafana-cloud-docs-hero-alerts-irm.svg" width="110" height="110" description="Alerts & IRM is Grafana Cloud’s Incident Response Management (IRM) solution, which enables you to detect, respond, and learn from incidents in one centralized platform." >}}

Param

The param shortcode provides build-time variable substitution.

To add a new variable definition:

1. Define a cascade variable in the parent topic.
2. Insert the param variable where it’s required in the parent and child topics.

Example

The front matter definition for a product version:

yaml Copy

cascade:
  PRODUCT_VERSION: 10.2

The param shortcode in the topic body text:

markdown Copy

Welcome to Grafana {{< param PRODUCT_VERSION >}}. Read on to learn about changes to dashboards and visualizations, data sources, security and authentication, and more.

The param shortcode in a topic heading:

markdown Copy

## What's new in Grafana {{% param PRODUCT_VERSION %}}.

Relref

The relref shortcode provides build-time link checking to ensure that the destination file exists.

For example: {{< relref "./path/to/file" >}}.

The argument is an absolute or relative file lookup. An absolute lookup begins with a slash (/) and starts from the site root. For example, to link to the Grafana Cloud index page, the relref shortcode argument is {{< relref "/docs/grafana-cloud/_index.md" >}}.

Using the full path to file, including the extension, can break the lookup if the destination file changes from a page to a leaf or branch bundle. To avoid this, omit the file extension and any /_index or /index part of the lookup. Using the previous example of the Grafana Cloud index page, the preferred relref shortcode argument is {{< relref "/docs/grafana-cloud" >}}.

Hugo link checking only applies to the content available during the build. In most projects, the only content available during local builds and CI is the current project documentation.

Hugo emits REF_NOT_FOUND warnings indicating the filename and location of such references when building the docs, for example with make docs in grafana/grafana or make server-quick in grafana/website:

Copy

WARN 2022/08/04 21:35:37 [en] REF_NOT_FOUND: Ref "../../enterprise": "/hugo/content/docs/grafana/next/administration/roles-and-permissions/access-control/assign-rbac-roles.md:14:47": page not found

In this example,

• Ref "../../enterprise" is the destination of the reference that Hugo can’t resolve
• \/hugo/content/docs/grafana/next/administration/roles-and-permissions/access-control/assign-rbac-roles.md is the document containing the reference, where the path after /next/ is relative to the documentation root of the component repository
• :14 represents the line number containing the unresolved reference
• :47 represents the character in that line where the unresolved reference begins

If the reference’s destination appears to be invalid, for example due to a typo in the reference or the depth of therelref directory, then you should be able to resolve this by correcting the reference target.

For additional information about Hugo error output, refer to Test documentation changes.

Determine relref shortcode arguments

To determine the path between the source and destination content, do the following:

Find the directory where the destination content lives. Find the directory that the source and destination directories have in common. Note the relative path from the common directory to the destination directory. Count the number of folders from the source to the common directory and that number equals the number of parent directory path elements (..) you need to add to your relative path. Join all the path elements together with forward slashes (/).

For example, with the following folder structure:

Copy

Vehicles
├── Trucks
│   ├── F150
│   └── 1999 F150
└── Vans

In this case, the source content is in the 1999 F150 directory and the destination content is in the Vans directory. The common folder for the two pieces of content is the Vehicles directory.

The parent directory of 1999 F150 is Trucks, requiring one .. path element. To parent directory of Trucks is Vehicles, requiring another .. path element. Therefore, the relative path from the source directory, 1999 F150, and the common directory, Vehicles, is ../..

The pathway from the common directory Vehicles to destination directory Vans is vans The relative path is ../../vans

If the source directory was Vans and the destination was 1999 F150, the relative path would be ../trucks/F150/1999-F150.

Section

The section shortcode renders an unordered list of links to a page’s child pages. To add a section, insert the section shortcode with the following optional parameters:

Examples

The following shortcode inserts a list of links to child pages. The link text uses the value of menuTitle from the front matter of the child page.

markdown Copy

{{< section menuTitle="true">}}

The following shortcode inserts a lists of links to child pages and includes the description content from the front matter of each child page.

markdown Copy

{{< section withDescriptions="true">}}

Table of contents

The table-of-contents shortcode renders the page’s table of contents in the page body. You should generally avoid using this shortcode because every documentation page already has a table of contents rendered with the page body.

markdown Copy

{{< table-of-contents >}}

Term

The term shortcode enables a tooltip when a user hovers over text surrounded by the shortcode.

Examples

markdown Copy

{{< term "data source" >}}data sources{{< /term >}}

markdown Copy

Grafana comes with built-in support for many {{< term "data source" >}}data sources{{< /term >}}.

Produces:

Grafana comes with built-in support for many data sources .

The Grafana Labs technical documentation team maintains the associated definitions internally. If you are a Grafana Labs employee and want to make changes, edit glossary.yaml. If you aren’t a Grafana Labs employee, request changes by creating an issue.

Guidance

For terms with multiple definitions, follow the common dictionary practice of numbering each alternative. For an example, refer to the definition of graph.

Vimeo

The vimeo shortcode embeds videos hosted on vimeo.com.

The shortcode requires a single argument which is the video ID. For example, {{< vimeo 1111111>}}.

You can find the video ID at the end of the URL. In this example, the video is a Preview of Tempo 2.0 and TraceQL: https://vimeo.com/773194063.

Copy

{{< vimeo 773194063 >}}

YouTube

The youtube shortcode embed videos hosted on YouTube.

The id is the v URL parameter in the YouTube URL. For example, for the YouTube URL https://www.youtube.com/watch?v=g97CjKOZqT4, the shortcode is the following:

markdown Copy

{{< youtube id="g97CjKOZqT4" >}}

You can configure start and end, in seconds, with:

markdown Copy

{{< youtube id="g97CjKOZqT4" start="100" end="200" >}}

You can configure automatic playback with:

markdown Copy

{{< youtube id="g97CjKOZqT4" autoplay="true" >}}

Escaping Hugo shortcodes

If you need to display the syntax for a shortcode, you can escape it using this syntax:

Produces:

markdown Copy

{{< myshortcode >}}

About version substitution

Version substitution enables the use of absolute paths that resolve correctly, irrespective of version. It uses special syntax using angle bracket delimiters like <GRAFANA_VERSION>.

As a convention, use the name of the target project all upper-case. For example, grafana becomes GRAFANA, grafana-cloud becomes GRAFANA_CLOUD.

The shortcode substitutes the special syntax <SOMETHING_VERSION> with the version inferred from the page’s URL. If the page’s URL has the prefix /docs/grafana/latest/, the shortcode replaces the syntax <SOMETHING_VERSION> with latest in the final URL.

You can override version inference by including additional metadata in the front matter of the file. To override the value of <GRAFANA_VERSION>, set the GRAFANA_VERSION parameter in the page’s front matter. For example, to set the version to next irrespective of the source content version, add the following to the front matter: GRAFANA_VERSION: next.