Writing guideShortcodes

Shortcodes

Shortcodes are predefined templates used for rendering snippets in Hugo.

Why use shortcodes?

Markdown is limited in its ability to render complex elements. Although you might be tempted to insert HTML directly into content to make up for its limitations, you can instead use shortcodes to ensure consistency across the Grafana website.

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

Note for internal Grafana Labs contributors: The Grafana shortcode templates are defined in the layouts/shortcodes folder of the website repo. To request custom shortcodes, create an issue.

docs/shared shortcode

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 source to be shared 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:
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 the grafana.com/docs/enterprise-metrics content, the source is enterprise-metrics.yes
versionVersion of the source content to include. If not provided, the version is implicitly set to match the version of the destination content. If the including destination is at version 1.0.0, then the version of included content is 1.0.0 also.no
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 repo.

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

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

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

figure shortcode

The figure shortcode renders an image with a caption using an HTML <figure> element. To add a figure, insert the figure shortcode with the following named parameters:

ParameterDescriptionRequired
animated-gifIf set, the HTML contains a div with an image link instead of a <figure> element. It’s typically used for animated screenshots. Shortcode parameters other than the caption and maxWidth parameters are ignored.no
captionDescribes the figure using a <figcaption> element.no
classCan be optionally used to override the HTML class for the <figure> element.no
lazyIf set to "false", the lazyload class is not also applied to the image. The lazyload class lets a browser render a page before the figure image loads. Once the image loads, the placeholder box transitions to the loaded image. Defaults to "true".no
lightboxIf set to "true" the figure-wrapper__lightbox class is also applied 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
maxWidthIf set, maxWidth controls the maximum width of the <figure> using the max-width CSS property. When specifying a length or percentage, value should include unit of measurement (e.g. ‘75px’ or ‘25%’).no
showCaptionIf 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

Example

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

section shortcode

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

ParameterDescriptionRequired
menuTitle:If set to "true", the menuTitle parameter modifies the template to use the menuTitle parameter of a child page’s front matter instead of the page title as the text in the link. If the child page doesn’t have a menuTitle parameter, the title is used instead.no

Example

The following shortcode inserts a list of links to the pages’s subpages. The links are named using the value of menuTitle from each subpage’s front matter.

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

Escaping Hugo shortcodes

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

Escaped shortcode

This markdown renders as:

{{< myshortcode >}}