Last reviewed: April 15, 2024

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.

Anchorize

The anchorize shortcode inserts the anchor fragment for the provided first argument. You can use the anchor fragment in URLs to link to HTML tags with specific identifiers.

Parameter	Description	Required
position 0	String	yes

Example

The following example inserts the anchor fragment for Writers' Toolkit.

Produces:

writers-toolkit

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.

Parameter	Description	Required
type	The 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.

Examples

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

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

Produces:

Card grid

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

Grid parameters

Parameter	Description	Required
key	Front matter parameter name of hero fields. Default: hero.	Yes
items	Front matter array of card parameters	Yes
type	The type of card to use. Only current option is: simple. Default: simple.	No
min	Sets 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_class	Optional CSS class for the wrapper element.	No
grid_class	Optional CSS class for the grid element.	No
card_class	Optional CSS class for the cards.	No

Card parameters (type="simple")

Parameter	Description	Required
title	Card title text.	No
href	URL of card target. Use relative path for links with the grafana.com domain. For example, /docs/grafana/latest/.)	Yes
description	Description text. Accepts Markdown.	No
logo	Logo image URL.	No
width	For 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
height	For 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:

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

Produces:

Collapse

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

Parameter	Description	Required
title	Text explaining the hidden content.	yes

Example

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

Produces:

BoltDB (deprecated)

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

Configuration options example

Produces:

6-Compactor-Snippet.yaml

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

Column-list

Formats a list with columns. Content is equally divided between columns unless specified with the count argument.

Parameter	Description	Required
count	The number columns in desktop view. You can specify a minimum of two and maximum of four.	no

Example

Produces:

Docs/alias

The docs/alias shortcode determines the relative alias between two pages. It can render as inline code, a table row, or a full table of the output.

Parameter	Description	Required
from	The URL path of the old page.	yes
to	The URL path of the new page.	yes
output	One of "table", "row", or "string". The default is "table".	no

For specific usage instructions, refer to Use the docs/alias shortcode.

Docs/copy

The docs/copy shortcode injects general copy maintained in the website repository data.

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

Parameter	Description	Required
name	The name of a key in the data YAML file.	yes

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

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.

Parameter	Description	Required
product	The name of the product or feature.	yes
featureFlag	The name of the feature flag users use to enable the product or feature.	yes

Example

Produces:

Docs/ignore

The docs/ignore shortcode ignores the content between the start and end markers so it doesn’t appear in the rendered webpage.

Use this shortcode when you want to transform source documentation into Killercoda tutorials and want some content to only exist in the tutorial output. You should only use ordinary Markdown as the inner content of the shortcode.

For more information about Killercoda transformation, refer to About the transformer tool.

Example

Produces:

This is rendered before the ignore.

This is rendered after the ignore.

Docs/openapi/info

Display information about an OpenAPI 3.0+ specification, use either the url or data parameter to specify an OpenAPI specification.

Parameter	Description	Required
url	The URL of the OpenAPI specification to fetch.	no
data	The filename of the OpenAPI specification to use from the website data/docs/openapi/ directory.	no

To fetch a remote specification from a URL:

To use a local specification from the website data/docs/openapi/ directory:

Example

Display the API information for a remote specification at https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/examples/v3.0/petstore-expanded.json:

Display the API information for a local specification named grafana:

Docs/openapi/path

Display API path information, use either the url or data parameter to specify an OpenAPI specification.

Parameter	Description	Required
url	The URL of the OpenAPI specification to fetch.	no
title	The filename of the OpenAPI specification to use from the website data/docs/openapi/ directory.	no
scope	Path tags to scope output to.	no

The Grafana Cloud k6 REST API v6 documentation uses the OpenAPI shortcodes to generate API documentation.

If you would like to collaborate with the Documentation and Technical Writing team to launch your API documentation, reach out in the #docs Slack channel.

Example

Display all paths for the grafana data specification:

Display only paths with the enterprise tag for the grafana data specification:

Docs/play

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

Parameter	Description	Required
title	The title of the Grafana Play dashboard.	yes
url	The URL of the Grafana Play dashboard.	yes

Example

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.

Parameter	Description	Required
product	The name of the product or feature.	yes

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.

Parameter	Description	Required
product	The name of the product or feature.	no
featureFlag	The name of the feature flag users use to enable the product or feature.	no

Produces:

Produces:

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:

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:

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

Body text:

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.

Parameter	Description	Required
lookup	Path to the included content relative to the root of the shared directory.	yes
source	Name 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
version	Version 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
leveloffset	Manipulates source content headings up to a maximum level of h6. Only positive offsets are supported. leveloffset="+5" ensures an h1 in the source content is an h6 in the destination content.	no

Shared files and headings

Hugo renders the shortcode separately to the page. As a result, if the same heading exists in a shared file and the page that includes it, they’ll have the same heading identifier. This duplication of heading identifiers breaks the ability to link to the headings properly.

To work around this, set a heading identifier in the shared file. If there are two shared files with the same heading, you only need to set a heading identifier in one of them. To set a heading identifier, refer to the Markdown guide.

Guidance

When the page with the docs/shared shortcode includes a shared page from the same project, you should use version substitution syntax for the version parameter. This ensures that the docs/shared shortcode includes the page from the same version as the page the shortcode is in.

Otherwise, you should use a version appropriate for your documentation. Use version substitution syntax and set the desired version in cascading front matter in your project’s root _index.md file.

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.

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.

Fixed-table

The fixed-table shortcode prevents column overflow by breaking content to a new line at any character, not just spaces between words.

Example

Produces:

Without the shortcode:

Metric	CloudWatch Metric	Statistics
aws_amazonmq_info
aws_amazonmq_ack_rate	AckRate	Average, Maximum, Minimum, Sum, SampleCount, p50, p75, p90, p95, p99
aws_amazonmq_burst_balance	BurstBalance	Average, Maximum, Minimum, Sum, SampleCount, p50, p75, p90, p95, p99

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:

Parameter	Description	Required
alt	If set, alt specifies the alt text for the image.	no
animated-gif	If 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
caption	Describes the figure using a <figcaption> element. If you don’t set alt, the shortcode uses caption as the alt text.	no
caption-align	Change the alignment of the caption property. Accepted values are left, center, and right.	no
class	Override the HTML class for the <figure> element.	no
link-class	Override the HTML class for the <a> element.	no
lazy	If 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
lightbox	If set to "true", the shortcode applies an additional figure-wrapper__lightbox class to the <figure>.	no
link	If set the value overrides the src shortcode parameter as the value to the href in the <a> element in the <figure>.	no
height	If 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
width	If 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-width	If 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-caption	If set to "true", the rendered <figure> includes a <figcaption> element with the caption set in caption. Defaults to "true".	no
src	Sets the source of the image.	yes

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:

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.

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.

Grot guides

Grot guides are interactive guides embedded in a documentation page that people can follow to get help and guidance on topics and direction to documentation resources.

To learn more about Grot guides, refer to the Grot guides documentation in the Writers’ Toolkit.

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:

Parameter	Description	Required
key	Front matter parameter name of hero fields. Default: hero.	No
title	Heading title text.	No
level	Heading level. Default: 3.	No
image	Image URL.	No
width	For 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
height	For 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
description	Description text. Accepts Markdown.	No
wrapper_class	Optional CSS class for the wrapper element.	No
hero_class	Optional CSS class for the hero element.	No
img_class	Optional CSS class for the image container element.	No
title_class	Optional CSS class for the heading element.	No
description_class	Optional 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:

Insert a simple hero using shortcode arguments:

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.

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

Example

The front matter definition for a product version:

The param shortcode in the topic body text:

The param shortcode in a topic heading:

Pyroscope flame graph

The pyro-flame-graph shortcode embeds Pyroscope flame graphs uploaded to https://flamegraph.com/.

Parameter	Description	Required
id	Flame graph id	yes

The flame graph id value is the path element after /share/ in the flame graph URL.

For example, to embed the flame graph at https://flamegraph.com/share/a8c6e7a9-f360-11ec-bcfa-beb8fdeeb850, use the following shortcode:

Relref

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

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

Parameter	Description	Required
position 0	The 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:

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 you see this error, then the reference’s destination is invalid. This may be due to a typo in the reference or having the incorrect path to the destination directory. Fix the error 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:

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:

Parameter	Description	Required
menuTitle	If 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
ordered	If 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 marker	no
withDescriptions	If set to "true", the withDescriptions parameter modifies the template to include the front matter descriptions for child pages that have them.	no
depth	Controls 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.

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

Shared

The shared shortcode sets up a snippet for sharing. You can reuse that snippet in another page with the shared-snippet shortcode.

Parameter	Description	Required
id	Identifier to give to the snippet that’s unique within the page	yes

Shared snippet

The shared-snippet shortcode includes a section of another page marked between section HTML tags. You should only use the shortcode in learning journeys.

To set up a snippet for sharing, wrap it in the shared shortcode with a meaningful ID. For example:

You can then use that section in another page using the shared-snippet shortcode:

Parameter	Description	Required
path	Path to the page source	yes
id	Identifier that matches the id set on the shared shortcode	yes

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.

Tabs

The tabs shortcode creates generic tabbed content. The website saves the selected tab to browser storage and persists it across navigation.

You create a tab using the tab-content shortcode within the tabs shortcode. The inner of the tab-content can be any Markdown.

Parameter	Description	Required
name	Name of the tab displayed in the tabs header	yes

Example

Produces:

Term

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

Parameter	Description	Required
position 0	Glossary lookup key	yes

Examples

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.

Translate

The translate shortcode looks up a key in the Hugo internationalization tables and returns the word or phrase referenced by that key in the page’s language.

The website uses internationalization tables to translate some words and phrases in page template HTML like the Was this page helpful? heading.

Parameter	Description	Required
position 0	Lookup key	yes

The shortcode requires a single argument which is the lookup key. For example, {{< translate "docs_feedback_heading" >}}. Employees of Grafana Labs can look up the keys in the internationalization directory.

Examples

Produces:

Was this page helpful?

Video-embed

The video-embed shortcode embeds videos on the page. Use .mp4 files of 10 MB or smaller.

The shortcode requires a single parameter, the src, to set the source of the image. For this, use the path to the recording file:

Vimeo

The vimeo shortcode embeds videos hosted on vimeo.com.

Parameter	Description	Required
position 0	Video ID	yes

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.

YouTube

The youtube shortcode embed videos hosted on YouTube.

Parameter	Description	Required
id	Video ID	yes
start	Start time in seconds	no
end	End time in seconds	no

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:

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

You can configure automatic playback with:

Escape Hugo shortcodes

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

Produces:

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.