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: The Grafana shortcode templates are defined 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
shortcode
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.
Parameter | Description | Required |
---|---|---|
type | The type of admonition. One of "note" , "caution" , or "warning" . | yes |
Warning: Reference style links such as[link text][label]
or[link text][]
do not work in the inner text of shortcodes. For more information, refer to Markdown Reference Links in Shortcodes.
Example
The following snippet renders an admonition of type "note"
with the message Kingston is the capital of Jamaica
.
{{% admonition type="note" %}}
Kingston is the capital of Jamaica.
{{% /admonition %}}
code
shortcode
The code
shortcode provides the ability to show multiple snippets of code in different languages. When a language is selected, other code blocks on the page are toggled if the language is included. The selected language is saved to browser and persists across navigation.
Example
Note: If your repository usesprettier
to format the files, use the HTML comments<!-- prettier-ignore-start -->
and<!-- prettier-ignore-end -->
around the shortcode tags to ensure correct rendering.
{{< 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 >}}
collapse
shortcode
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
{{< collapse title="Title of hidden content" >}}
Kingston is the capital of Jamaica.
{{< /collapse >}}
Produces:
Kingston is the capital of Jamaica.
docs/experimental-deployment
shortcode
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
{{< 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
shortcode
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
{{< docs/experimental product="experimental-feature" featureFlag="its-feature-flag" >}}
Produces:
Note: This 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 in Grafana to use this feature. Contact Grafana Support to enable this feature in Grafana Cloud.
docs/private-preview
shortcode
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 |
{{< 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
shortcode
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. | yes |
{{< 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.
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:
- 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. - Store the file in a shared folder.
- To include the shared content in a Markdown file, insert the
docs/shared
shortcode with the following named parameters:
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 does not have a version, use the empty string "" as the value. Version inference is supported using values like <GRAFANA VERSION> . To learn about version inference, refer to About version inference. | yes |
leveloffset | Manipulates 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.
{{< docs/shared lookup="flow/reference/components/oauth2-block.md" source="agent" version="<AGENT VERSION>" >}}
The following shortcode inserts the latest version of shared-page.md
from the shared
folder in the enterprise-metrics
project.
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="<GEM VERSION>" leveloffset="+1" >}}
figure
shortcode
The figure
shortcode renders an image with a caption using an HTML <figure>
element. This shortcode allows you more control over how an image is rendered, 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. Shortcode parameters other than the caption and maxWidth parameters are ignored. | no |
caption | Describes the figure using a <figcaption> element. | no |
class | Can be optionally used to override the HTML class for the <figure> 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. Once the image loads, the placeholder box transitions to the loaded image. Defaults to "true" . | no |
lightbox | If set to "true" , an additional figure-wrapper__lightbox class is applied 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 |
max-width | If set, _max-width_ 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, 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 |
Example
In this example, the image has a CSS class that makes the image display floated to the right.
{{< figure class="float-right" src="/static/img/docs/grafana-cloud/k8sPods.png" caption="Pod view in Grafana Kubernetes Monitoring" >}}
In this example, the image’s display size is changed to have a maximum width of 50%. The max-width
value must have a unit of measurement, such as pixels or percentages.
{{< figure max-width="50%" src="/static/img/docs/grafana-cloud/k8sPods.png" caption="Pod view in Grafana Kubernetes Monitoring" >}}
responsive-table
shortcode
The responsive-table
shortcode wraps the table within the shortcode tags with a class that makes the table responsive to the browser window.
This results in a table with horizontal scrolling that is fixed to the width of the containing element.
Without the responsive-table
shortcode, a table can often overflow its containing element and text can be hidden by neighboring elements like the table of contents.
Example
{{% responsive-table %}}
| Heading, column one | Heading, column two |
| ------------------- | ------------------- |
| Row one, column one | Row one, column two |
{{% /responsive-table %}}
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 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 title is used 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 |
Examples
The following shortcode inserts a list of links to child pages.
The links are named using the value of menuTitle
from the front matter of the child page.
{{< 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.
{{< section withDescriptions="true">}}
term
shortcode
The term
shortcode enables a tooltip when a user hovers above text surrounded by the shortcode.
Parameter | Description | Required |
---|---|---|
position 0 | Glossary lookup key | yes |
Examples
Grafana comes with built-in support for many {{< term "data source" >}}data sources{{< /term >}}.
docs/reference
shortcode
The docs/reference
shortcode offers more flexible linking than the Hugo built-in relref
shortcode.
Use this shortcode when content from one repository is published to more than one documentation set, because it lets you specify appropriate links for each doc set in one part of the file (usually at end of the file, like a footer) while using the link label in the body text.
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:
{{% 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
- The label you’ll use in the reference-style links in the file. In the example above, the label isdashboards
. The label can be multiple words (for example, [dashboard docs]) and can include spaces.project path prefix
- Designates the target project. In the example above, the path prefixes are/docs/grafana/
for Grafana and/docs/grafana-cloud/
for Cloud.reference
- The path to the destination file. Version inference is supported using values like<GRAFANA VERSION>
. To learn about version inference, refer to About version inference.
Then add the link in the body of the file in the following format:
For more information about Grafana dashboards, refer to the [Dashboards documentation][dashboards].
- If the page you’re on is
/docs/grafana/latest/alerting/
, the inferred version islatest
, and the returned reference is/docs/grafana/latest/dashboards
. - If the page you’re on is
/docs/grafana/next/alerting/
, the inferred version isnext
, and the returned reference is/docs/grafana/next/dashboards
.
Other use cases
The docs/reference
shortcode is 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:
{{% docs/reference %}}
[Grafana website]: "/ -> www.grafana.com"
{{% /docs/reference %}}
Body text:
Find more information on [Grafana][Grafana website].
Escaping Hugo shortcodes
If you need to display the syntax for a shortcode, you can escape it using this syntax:
This Markdown renders as:
{{< myshortcode >}}
About version inference
Version inference 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, with spaces but no hyphens or underscores, all upper-case.
For example, grafana
becomes GRAFANA
, grafana-cloud
becomes GRAFANA CLOUD.
The special syntax <SOMETHING VERSION>
is substituted by the version that is inferred from the page’s 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
.