Menu
Open source

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.

Note

The website team maintains shortcode templates in the layouts/shortcodes folder of the website repository which is only accessible to Grafana Labs employees. To request custom shortcodes, create an issue.

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.

ParameterDescriptionRequired
typeThe type of admonition. One of caution, note, tip, or warning.yes

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.

Warning

Reference style links such as [link text][label] or [link text][] don’t work in the inner text of shortcodes if you use reference links defined at the topic level. To use reference links within an admonition, you must use standard inline Markdown links or define the reference links within the admonition shortcode.

For more information, refer to Markdown Reference Links in Shortcodes.

Examples

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

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

Produces:

Note

Kingston is the capital of Jamaica.

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

Produces:

Tip

This also applies to headings that contain a forward slash or parentheses or square brackets.

Card grid

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

Grid parameters

ParameterDescriptionRequired
keyFront matter parameter name of hero fields. Default: hero.Yes
itemsFront matter array of card parametersYes
typeThe type of card to use. Only current option is: simple. Default: simple.No
minSets the minimum card width. This affects the number of cards in each row, as well as the breakpoints at which the cards wrap. Options: xs, sm, md, lg. These correspond to minimum card widths of 100px, 250px, 350px, 500px. Default: sm.No
wrapper_classOptional CSS class for the wrapper element.No
grid_classOptional CSS class for the grid element.No
card_classOptional CSS class for the cards.No

Card parameters (type=“simple”)

ParameterDescriptionRequired
titleCard title text.No
hrefURL of card target. Use relative path for links within “grafana.com” domain (e.g. /docs/grafana/latest/)Yes
descriptionDescription text. Accepts Markdown.No
logoLogo image URL.No
widthFor raster images (png, jpg, webp), this is the image’s natural width. For vector images (svg), this is the desired display width. Accepts a number (pixels) or a percentage. Pixel values must not include px. Default: auto.No
heightFor raster images (png, jpg, webp), this is the image’s natural height. For vector images (svg), this is the desired display height. Accepts a number (pixels) or a percentage. Pixel values must not include px. Default: auto.No

Examples

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

markdown
---
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

Note

If your repository uses prettier to format the files, use the HTML comments <!-- prettier-ignore-start --> and <!-- prettier-ignore-end --> around the shortcode tags to ensure correct rendering.
markdown
{{< 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:

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...

Collapse

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

ParameterDescriptionRequired
titleText explaining the hidden content.yes

Example

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

Produces:

Use this shortcode for:

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
#### 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
#### `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.

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
{{< docs/experimental-deployment >}}

Produces:

Note

This deployment is provided only as an example; engineering and on-call support is not available. Documentation is either limited or not provided outside of code comments. No SLA is provided. This example is primarily intended for open source engineers. Because this is provided as an example, it is not meant to be used in production environments, and the risks are unknown/high.

Docs/experimental

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

ParameterDescriptionRequired
productThe name of the product or feature.yes
featureFlagThe name of the feature flag users use to enable the product or feature.yes

Example

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

Produces:

Note

experimental-feature is an experimental feature. Engineering and on-call support is not available. Documentation is either limited or not provided outside of code comments. No SLA is provided. Enable the its-feature-flag feature toggle in Grafana to use this feature. Contact Grafana Support to enable this feature in Grafana Cloud.

Docs/play

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

ParameterDescriptionRequired
titleThe title of the Grafana Play dashboard.yes
urlThe URL of the Grafana Play dashboard.yes

Example

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

Produces:

Give it a try using Grafana Play

With Grafana Play, you can explore and see how it works, learning from practical examples to accelerate your development. This feature can be seen on Time Series Visualizations.

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.

ParameterDescriptionRequired
productThe name of the product or feature.yes
markdown
{{< docs/private-preview product="private-preview-feature" >}}

Produces:

Note

private-preview-feature is currently in private preview. Grafana Labs offers support on a best-effort basis, and breaking changes might occur prior to the feature being made generally available.

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.

ParameterDescriptionRequired
productThe name of the product or feature.yes
featureFlagThe name of the feature flag users use to enable the product or feature.no
markdown
{{< docs/public-preview product="public-preview-feature" >}}

Produces:

Note

public-preview-feature is currently in public preview. Grafana Labs offers limited support, and breaking changes might occur prior to the feature being made generally available.
markdown
{{< docs/public-preview product="public-preview-feature" featureFlag="its-feature-flag" >}}

Produces:

Note

public-preview-feature is currently in public preview. Grafana Labs offers limited support, and breaking changes might occur prior to the feature being made generally available. Enable the its-feature-flag feature toggle in Grafana to use this feature. Contact Grafana Support to enable this feature in Grafana Cloud.

Docs/reference

Warning

This shortcode is present in the documentation, but you should prefer ref URIs. Don’t use it when creating new or updating existing documentation.

For more information, refer to Links.

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
{{% 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
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
[Grafana website]: www.grafana.com

Body text:

markdown
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.

ParameterDescriptionRequired
lookupPath to the included content relative to the root of the shared directory.yes
sourceName of the source content as shown on the website. For example, for https://grafana.com/docs/enterprise-metrics/ content, the source is enterprise-metrics.yes
versionVersion of the source content to include. For source content that doesn’t have a version, use the empty string "" as the value. This shortcode supports version substitution using values like <GRAFANA_VERSION>. To learn about version substitution, refer to About version substitution.yes
leveloffsetManipulates source content headings up to a maximum level of h6. Only positive offsets are currently supported. leveloffset="+5" ensures an h1 in the source content is an h6 in the destination content.no

Note

Hugo doesn’t rebuild the destination file when a source file changes on disk. To trigger a rebuild after changes to a source file, perform a trivial change to the destination file and save that, too.

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
{{< 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
{{< 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:

ParameterDescriptionRequired
altIf set, alt specifies the alt text for the image.no
animated-gifIf set, the HTML contains a div with an image link instead of a <figure> element. It’s typically used for animated screenshots. When you set this parameter, the shortcode ignores other parameters except caption and maxWidth.no
captionDescribes the figure using a <figcaption> element. If you don’t set alt, the shortcode uses caption as the alt text.no
caption-alignChange the alignment of the caption property. Accepted values are left, center, and right.no
classOverride the HTML class for the <figure> element.no
link-classOverride the HTML class for the <a> element.no
lazyIf set to "false", an additional lazyload class is not applied to the image. The lazyload class lets a browser render a page before the figure image loads. After the image loads, the placeholder box transitions to the loaded image. Defaults to "true".no
lightboxIf set to "true", the shortcode applies an additional figure-wrapper__lightbox class to the <figure>.no
linkIf set the value overrides the src shortcode parameter as the value to the href in the <a> element in the <figure>.no
heightIf set, _height_ controls the height of the <img> element using the height CSS property. When specifying a value, it should be an integer representing pixels without a "px" string at the end, for example "500".no
widthIf set, _width_ controls the width of the <img> element using the width CSS property. When specifying a value, it should be an integer representing pixels without a "px" string at the end, for example "500".no
max-widthIf set, _max-width_ controls the maximum width of the <figure> element using the max-width CSS property. When specifying a length or percentage, value should include unit of measurement, for example "75px" or "25%".no
show-captionIf set to "true", the rendered <figure> includes a <figcaption> element with the caption set in caption. Defaults to "true".no
srcSets the source of the image.yes

Note

Including the original image dimensions as the ‘width’ and ‘height’ properties is highly recommended, as it improves page performance and SEO.

These values are only used for determining the image aspect ratio and don’t equate to the final displayed size.

Center an image example

You can center an image using the figure shortcode by adding the following properties:

  • Add the class="w-100p" property.

  • Add the link-class="w-fit mx-auto d-flex flex-direction-column" property.

  • Add the max-width="WIDTHpx" property, replacing WIDTH with the maximum width value you want to display your image. This property only affects raster images, such as PNG or JPG files, whose original width is greater than the property value.

  • Optionally, you can add the width and height properties as a best practice to help with image and page optimization.

    For raster images, such as a PNG or JPG file, you can set the properties with the original image values, without pixels or percentages. For example, for a PNG file whose original dimensions are 800x600 pixels, you can add width="800" height="600".

    For a vector image, calculate the values based on the desired image width by using the formula: (new_width / full_width) * full_height = new_height. For a detailed explanation about this step, refer to the later Center image properties section.

The following example shows how to center a PNG file whose original dimensions are 1275x738 pixels:

markdown
{{< 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" >}}

For more details about what each parameter does, refer to the following section.

Example

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

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

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:

ParameterDescriptionRequired
keyFront matter parameter name of hero fields. Default: hero.No
titleHeading title text.No
levelHeading level. Default: 3.No
imageImage URL.No
widthFor raster images (png, jpg, webp), this is the image’s natural width. For vector images (svg), this is the desired display width. Accepts a number (pixels) or a percentage. Pixel values must not include px. Default: auto.No
heightFor raster images (png, jpg, webp), this is the image’s natural height. For vector images (svg), this is the desired display height. Accepts a number (pixels) or a percentage. Pixel values must not include px. Default: auto.No
descriptionDescription text. Accepts Markdown.No
wrapper_classOptional CSS class for the wrapper element.No
hero_classOptional CSS class for the hero element.No
img_classOptional CSS class for the image container element.No
title_classOptional CSS class for the heading element.No
description_classOptional CSS class for the description element.No

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
---
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
{{< 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.

Note

If you use the param shortcode in headings, you must use % in place of < and >.

For example: {{% param VARIABLE %}}.

Example

The front matter definition for a product version:

yaml
cascade:
  PRODUCT_VERSION: 10.2

The param shortcode in the topic body text:

markdown
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
## What's new in Grafana {{% param PRODUCT_VERSION %}}.

Relref

Warning

This shortcode is present in the documentation, but you should prefer full URLs. Don’t use it when creating new or updating existing documentation.

For more information, refer to Links.

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

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

ParameterDescriptionRequired
position 0The file lookup.yes

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:

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:

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:

ParameterDescriptionRequired
menuTitleIf set to "true", the menuTitle parameter modifies the template to use the child page’s menuTitle front matter instead of the page title as the text in the link. If the child page doesn’t have a menuTitle parameter, the shortcode uses the title instead.no
orderedIf set to "true", the ordered parameter modifies the template to use an ordered list instead of an unordered list, displaying each item with a number markerno
withDescriptionsIf set to "true", the withDescriptions parameter modifies the template to include the front matter descriptions for child pages that have them.no
depthControls how many levels of child pages to include in the output. The default depth is "1" which only shows the immediate children.no

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
{{< 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
{{< 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
{{< table-of-contents >}}

Term

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

ParameterDescriptionRequired
position 0Glossary lookup keyyes

Examples

markdown
{{< term "data source" >}}data sources{{< /term >}}
markdown
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.

ParameterDescriptionRequired
position 0Video IDyes

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.

{{< vimeo 773194063 >}}

YouTube

The youtube shortcode embed videos hosted on YouTube.

ParameterDescriptionRequired
idVideo IDyes
startStart time in secondsno
endEnd time in secondsno
autoplaySet to "true" to automatically play the videono

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
{{< youtube id="g97CjKOZqT4" >}}

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

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

You can configure automatic playback with:

markdown
{{< 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:

Escaped shortcode

Produces:

markdown
{{< 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.