--- title: "Shortcodes | Writers' Toolkit documentation" description: "Understand what shortcodes are and how to use them in your Markdown." --- # 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](https://gohugo.io/content-management/shortcodes/). > 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](https://github.com/grafana/writers-toolkit/issues). ## Badge The `badge` shortcode renders a styled badge with configurable styling and optional tooltip annotation. The badge uses the same styling system as the documentation labels. Expand table | Parameter | Description | Required | |-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------|----------| | `text` | The text to display in the badge | yes | | `style` | The style of the badge. One of `stage`, `product-oss`, `product-enterprise`, `product-cloud`, `product-oss-enterprise`, `product-general`, or `support` | no | | `tooltip` | Optional tooltip text that appears when hovering over the badge | no | | `id` | Optional unique identifier for the badge tooltip. If not provided, a unique ID is generated | no | ### Examples The following example renders a basic badge with the default `stage` styling: Markdown ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```markdown {{< badge text="Generally Available" >}} ``` and produces: Generally Available The following example renders a badge with enterprise product styling: Markdown ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```markdown {{< badge text="Enterprise" style="product-enterprise" >}} ``` and produces: Enterprise The following example renders a badge with a tooltip: Markdown ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```markdown {{< badge text="Beta" style="stage" tooltip="This feature is in beta and may change" >}} ``` and produces: Beta The following example renders a badge with OSS-Enterprise combined styling and tooltip: Markdown ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```markdown {{< badge text="Available" style="product-oss-enterprise" tooltip="This feature is available in both open source and enterprise editions" >}} ``` and produces: Available ## Button The `button` shortcode renders a styled link as a button. Use it instead of raw HTML anchor tags to keep Markdown free of presentational markup. Expand table | Parameter | Description | Required | |-----------|---------------------------------------------------------------------------------------|----------| | `link` | The URL the button navigates to. | yes | | `type` | The visual style of the button. | yes | | `size` | The size modifier for the button. | no | | `target` | The value of the HTML `target` attribute. Use `_blank` to open the link in a new tab. | no | | `class` | Additional CSS classes to apply to the button. | no | #### `type` values - `primary`: Solid blue fill, white text. - `secondary`: White background, navy text, blue border. - `white`: White background, navy text. - `outline-white`: Transparent background, white border and text. - `outline-gray`: Transparent background, grey border and text. - `outline-blue`: Transparent background, dark-blue border, white text. - `success`: Green fill, white text. - `empty`: No border or background; underline on hover. - `none`: No border, background, or underline. #### `size` values - `mini`: 32px height. - `small`: 30px height. - `slim`: 40px height, smaller font. - `large`: 50px height, larger font. - `hero`: 40px height, larger font. ### Examples The following example renders a primary button that links to the Grafana documentation: Markdown ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```markdown {{< button link="/docs/grafana/latest/" type="primary" >}} Read the docs {{< /button >}} ``` Produces: [Read the docs](/docs/grafana/latest/) ## 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. Expand table | Parameter | Description | Required | |------------|-------------|----------| | position 0 | String | yes | ### Example The following example inserts the anchor fragment for `Writers' Toolkit`. Markdown ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```markdown {{< anchorize "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](/docs/writers-toolkit/write/style-guide/style-conventions/#admonitions). The content of the admonition must be within opening and closing tags, and the type of admonition must be within quotes. Expand table | 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. > 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](https://discourse.gohugo.io/t/markdown-reference-links-in-shortcodes/5770/3). ### Examples The following example renders an admonition of type `note` with the message `Kingston is the capital of Jamaica.`: Markdown ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```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 ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```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 Expand table | 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"`) Expand table | 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: Markdown ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```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. Expand table | Parameter | Description | Required | |-------------|--------------------------------------------------------------------------------------|----------| | `annotated` | Render the code block in a two-column layout with comments to the right of the code. | no | ### Example > Note > > If your repository uses `prettier` to format the files, use the HTML comments `` and `` around the shortcode tags to ensure correct rendering. Markdown ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ````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 Go JavaScript JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```bash curl "https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/ActivityService.AddActivity" ``` Go ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```go package main import ( "context" ) func main() { ... ``` JavaScript ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```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 ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```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... ``` ### Annotated code block Code annotations clarify full code examples by explaining what the code does and why. They appear beside the code in a two-pane layout, allowing detailed explanations without cluttering the code. Annotations should only be used when necessary and not for short snippets. They help users understand code line by line, as well as help grasp design decisions and adapt code to their needs. The annotate logic only supports line comments with `#` and `//` prefixes and a space after the prefix. > Note > > Only a single code snippet in a single programming language is supported per annotated example. ### Annotated code block example Markdown ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ````markdown {{< code annotated="true" >}} ```alloy // Let's send and process more logs! loki.source.api "listener" { http { listen_address = "127.0.0.1" listen_port = 9999 } labels = { "source" = "api" } forward_to = [loki.process.process_logs.receiver] } loki.process "process_logs" { // Stage 1 stage.json { expressions = { log = "", ts = "timestamp", } } // Stage 2 stage.timestamp { source = "ts" format = "RFC3339" } // Stage 3 stage.json { source = "log" expressions = { is_secret = "", level = "", log_line = "message", } } } ``` {{< /code >}} ```` Produces: Alloy Beside Inline ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```alloy loki.source.api "listener" { http { listen_address = "127.0.0.1" listen_port = 9999 } labels = { "source" = "api" } forward_to = [loki.process.process_logs.receiver] } loki.process "process_logs" {  ``` Let’s send and process more logs! ```alloy stage.json { expressions = { log = "", ts = "timestamp", } }  ``` Stage 1 ```alloy stage.timestamp { source = "ts" format = "RFC3339" }  ``` Stage 2 ```alloy stage.json { source = "log" expressions = { is_secret = "", level = "", log_line = "message", } } }   ``` Stage 3 Alloy ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```alloy // Let's send and process more logs! loki.source.api "listener" { http { listen_address = "127.0.0.1" listen_port = 9999 } labels = { "source" = "api" } forward_to = [loki.process.process_logs.receiver] } loki.process "process_logs" { // Stage 1 stage.json { expressions = { log = "", ts = "timestamp", } } // Stage 2 stage.timestamp { source = "ts" format = "RFC3339" } // Stage 3 stage.json { source = "log" expressions = { is_secret = "", level = "", log_line = "message", } } } ``` ### Editable placeholders Editable placeholders are parts of a code example you can click and edit directly in the docs. They look like this: `@@@PLACEHOLDER@@@`. Users type their value once, and all code blocks with the same placeholder update automatically. This eliminates the user’s need to copy and edit multiple snippets, and reduces mistakes by keeping values consistent across examples. Placeholder values are synced across page navigation. All placeholder variables exist in a global store that spans the entire documentation site. This means that `@@@PROJECT_ID@@@` has the same value across all documentation projects and pages. This global behavior provides flexibility - if multiple projects need to share variables, they can reference the same placeholder name. However, when creating placeholders, consider using a naming convention that includes project-specific prefixes to avoid unintended conflicts. For example: - `@@@LOKI_PROJECT_ID@@@` for Loki-specific project IDs - `@@@TEMPO_ENDPOINT@@@` for Tempo-specific endpoints - `@@@MIMIR_API_KEY@@@` for Mimir-specific API keys Using namespaces helps prevent accidental variable sharing between unrelated documentation while still allowing intentional sharing when needed. ### Editable placeholder example Markdown ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ````markdown {{< code >}} ```go projectID := "@@@YOUR_PROJECT_ID@@@" backupProjectID := "@@@YOUR_PROJECT_ID@@@" region := "@@@YOUR_REGION@@@" ``` ```javascript const projectId = "@@@YOUR_PROJECT_ID@@@"; const region = "@@@YOUR_REGION@@@"; const backupProject = "@@@YOUR_PROJECT_ID@@@"; ``` ```python project_id = "@@@YOUR_PROJECT_ID@@@" region = "@@@YOUR_REGION@@@" backup_project_id = "@@@YOUR_PROJECT_ID@@@" ``` {{< /code >}} ```` Produces: Go JavaScript Python ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy Go ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```go projectID := "@@@YOUR_PROJECT_ID@@@" backupProjectID := "@@@YOUR_PROJECT_ID@@@" region := "@@@YOUR_REGION@@@" ``` JavaScript ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```javascript const projectId = "@@@YOUR_PROJECT_ID@@@"; const region = "@@@YOUR_REGION@@@"; const backupProject = "@@@YOUR_PROJECT_ID@@@"; ``` Python ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```python project_id = "@@@YOUR_PROJECT_ID@@@" region = "@@@YOUR_REGION@@@" backup_project_id = "@@@YOUR_PROJECT_ID@@@" ``` ### Api-tree The `api-tree` code block type renders an interactive, collapsible tree diagram for visualizing API structures. It’s particularly useful for documenting REST APIs or any hierarchical API structure. The code block takes the tree structure as inner content using Unicode box-drawing characters to represent the hierarchy. It supports clickable links, data types, and requirement badges (`required` or `optional`). ### Api-tree structure syntax The tree uses the following format: - **Node name**: The name of the API method, request, response, or field - **Links**: Use Markdown link syntax `[NodeName](url)` to make nodes clickable - **Data types**: Add data types in parentheses `(string)`, `(bool)`, `(int)`, etc. - **Data type links**: Use Markdown link syntax for data types `([CustomType](url))` - **Requirements**: Add `\[required\]` or `\[optional\]` after data types - **Hierarchy**: Use box-drawing characters: - `├──` for branch nodes - `└──` for the last child in a group - `│` for vertical continuation lines ### Api-tree examples The following example renders a visual API tree: Markdown ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ````markdown ```api-tree UserService ├── [GetUser](../api/#getuser) │ ├── Request: [GetUserRequest](../api/#getuserrequest) │ │ ├── id (string) \[required\] │ │ └── fields (list) \[optional\] │ └── Response: [User](../api/#user) │ ├── id (string) │ ├── name (string) │ └── email (string) └── [ListUsers](../api/#listusers) ├── Request: [ListUsersRequest](../api/#listusersrequest) │ ├── page_size (int) \[optional\] │ └── page_token (string) \[optional\] └── Response: [ListUsersResponse](../api/#listusersresponse) └── users (list<[User](../api/#user)\>) ``` ```` Produces: The following example shows an API tree with nested message types: Markdown ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ````markdown ```api-tree ├── [GetConfig](../api/#getconfig) │ ├── Request: [GetConfigRequest](../api/#getconfigrequest) │ │ ├── id (string) \[required\] │ │ └── options ([ConfigOptions](../api/#configoptions)) \[optional\] │ │ ├── verbose (bool) │ │ └── format ([Format](../api/#format)) │ │ ├── JSON │ │ ├── YAML │ │ └── TOML │ └── Response: [GetConfigResponse](../api/#getconfigresponse) │ ├── config (string) │ └── hash (string) └── [UpdateConfig](../api/#updateconfig) ├── Request: [UpdateConfigRequest](../api/#updateconfigrequest) │ ├── id (string) \[required\] │ └── config (string) \[required\] └── Response: [UpdateConfigResponse](../api/#updateconfigresponse) └── success (bool) ``` ```` Produces: By default, all nodes are expanded. To load the tree with all nodes collapsed, add the `collapsed` class to the code fence info block: Markdown ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ````markdown ```api-tree {class="collapsed"} CollectorService ├── [GetConfig](../collector-api/#getconfigrequest) │ ├── Request: [GetConfigRequest](../collector-api/#getconfigrequest) │ │ ├── id (string) \[required\] │ │ ├── local\_attributes (map) \[optional\] │ │ ├── hash (string) \[optional\] │ │ ├── remote\_config\_status ([RemoteConfigStatus](../collector-api/#remoteconfigstatus)) \[optional\] │ │ │ ├── status ([RemoteConfigStatuses](../collector-api/#remoteconfigstatuses)) │ │ │ │ ├── UNSET │ │ │ │ ├── APPLIED │ │ │ │ ├── APPLYING │ │ │ │ └── FAILED │ │ │ └── error\_message (string) \[optional\] │ │ └── effective\_config ([EffectiveConfig](../collector-api/#effectiveconfig)) \[optional\] │ │ └── config\_map ([AgentConfigMap](../collector-api/#agentconfigmap)) │ │ └── config\_map (map) │ │ └── [AgentConfigFile](../collector-api/#agentconfigfile) │ │ ├── body (bytes) │ │ └── content\_type (string) \[optional\] │ └── Response: [GetConfigResponse](../collector-api/#getconfigresponse) │ ├── content (string) │ ├── hash (string) │ └── not\_modified (bool) ``` ```` Produces: ## Collapse The `collapse` shortcode toggles visibility of sections of content, often helpful when hiding and showing large amounts of content. Expand table | Parameter | Description | Required | |-----------|-------------------------------------|----------| | `title` | Text explaining the hidden content. | yes | ### Example Markdown ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```markdown {{< collapse title="Title of hidden content" >}} Kingston is the capital of Jamaica. {{< /collapse >}} ``` Produces: Title of hidden content Kingston is the capital of Jamaica. Use this shortcode for: - [Deprecated content](#deprecation-example): Features that have been deprecated, but still need to be documented for some time. - [Configuration options](#configuration-options-example): 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 code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```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: boltdb-shipper Also known as *boltdb-shipper* during development. The single store configurations for Loki to utilize the chunk store for both chunks and the index, which requires just one store to run Loki. ### Configuration options example Markdown ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ````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. Example YAML ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```yaml compactor: working_directory: /tmp/loki/compactor shared_store: s3 compaction_interval: 5m ``` ## Column-list Formats a list with columns. Content is equally divided between columns unless specified with the `count` argument. Expand table | Parameter | Description | Required | |-----------|-------------------------------------------------------------------------------------------|----------| | `count` | The number columns in desktop view. You can specify a minimum of two and maximum of four. | no | ### Example Markdown ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```markdown {{< column-list >}} - Alertmanager - Amazon CloudWatch - Azure Monitor - Elasticsearch - Google Cloud Monitoring - Graphite - InfluxDB - Jaeger - Loki - Microsoft SQL Server (MSSQL) - MySQL - OpenTSDB - PostgreSQL - Prometheus - Pyroscope - Tempo - Zipkin {{< /column-list >}} ``` Produces: - Alertmanager - Amazon CloudWatch - Azure Monitor - Elasticsearch - Google Cloud Monitoring - Graphite - InfluxDB - Jaeger - Loki - Microsoft SQL Server (MSSQL) - MySQL - OpenTSDB - PostgreSQL - Prometheus - Pyroscope - Tempo - Zipkin ## Datatable The `datatable` shortcode wraps a Markdown table and enables interactive functionality including column sorting, text search filtering, and pagination. The shortcode takes no parameters. Place a standard Markdown table between the opening and closing tags. Click a column header to sort by that column. Click the same header again to reverse the sort direction, and a third time to clear the sort. Use the search field to filter rows by text content. Pagination appears automatically when the table contains more than 25 rows. Tables with 25 or fewer rows display all rows without pagination controls. ### Example Markdown ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```markdown {{< datatable >}} | Plugin | Type | Status | Downloads | | ------------ | ----------- | ---------- | --------- | | Zabbix | Data source | Active | 12500 | | Infinity | Data source | Active | 9800 | | FlowCharting | Panel | Deprecated | 7200 | | Carpet plot | Panel | Active | 3400 | | Clock Panel | Panel | Deprecated | 15600 | | Diagram | Panel | Active | 5100 | | FlowCharting | Panel | Active | 8900 | | Breadcrumb | Panel | Active | 1200 | | Clock | Panel | Active | 22000 | | Boom Table | Panel | Active | 6700 | | Zabbix | Data source | Active | 12500 | | Infinity | Data source | Active | 9800 | | FlowCharting | Panel | Deprecated | 7200 | | Carpet plot | Panel | Active | 3400 | | Clock Panel | Panel | Deprecated | 15600 | | Diagram | Panel | Active | 5100 | | FlowCharting | Panel | Active | 8900 | | Breadcrumb | Panel | Active | 1200 | | Clock | Panel | Active | 22000 | | Boom Table | Panel | Active | 6700 | | Zabbix | Data source | Active | 12500 | | Infinity | Data source | Active | 9800 | | FlowCharting | Panel | Deprecated | 7200 | | Carpet plot | Panel | Active | 3400 | | Clock Panel | Panel | Deprecated | 15600 | | Diagram | Panel | Active | 5100 | | FlowCharting | Panel | Active | 8900 | | Breadcrumb | Panel | Active | 1200 | | Clock | Panel | Active | 22000 | | Boom Table | Panel | Active | 6700 | | Zabbix | Data source | Active | 12500 | | Infinity | Data source | Active | 9800 | | FlowCharting | Panel | Deprecated | 7200 | | Carpet plot | Panel | Active | 3400 | | Clock Panel | Panel | Deprecated | 15600 | | Diagram | Panel | Active | 5100 | | FlowCharting | Panel | Active | 8900 | | Breadcrumb | Panel | Active | 1200 | | Clock | Panel | Active | 22000 | | Boom Table | Panel | Active | 6700 | {{< /datatable >}} ``` Produces: Expand table | Plugin | Type | Status | Downloads | |--------------|-------------|------------|-----------| | Zabbix | Data source | Active | 12500 | | Infinity | Data source | Active | 9800 | | FlowCharting | Panel | Deprecated | 7200 | | Carpet plot | Panel | Active | 3400 | | Clock Panel | Panel | Deprecated | 15600 | | Diagram | Panel | Active | 5100 | | FlowCharting | Panel | Active | 8900 | | Breadcrumb | Panel | Active | 1200 | | Clock | Panel | Active | 22000 | | Boom Table | Panel | Active | 6700 | | Zabbix | Data source | Active | 12500 | | Infinity | Data source | Active | 9800 | | FlowCharting | Panel | Deprecated | 7200 | | Carpet plot | Panel | Active | 3400 | | Clock Panel | Panel | Deprecated | 15600 | | Diagram | Panel | Active | 5100 | | FlowCharting | Panel | Active | 8900 | | Breadcrumb | Panel | Active | 1200 | | Clock | Panel | Active | 22000 | | Boom Table | Panel | Active | 6700 | | Zabbix | Data source | Active | 12500 | | Infinity | Data source | Active | 9800 | | FlowCharting | Panel | Deprecated | 7200 | | Carpet plot | Panel | Active | 3400 | | Clock Panel | Panel | Deprecated | 15600 | | Diagram | Panel | Active | 5100 | | FlowCharting | Panel | Active | 8900 | | Breadcrumb | Panel | Active | 1200 | | Clock | Panel | Active | 22000 | | Boom Table | Panel | Active | 6700 | | Zabbix | Data source | Active | 12500 | | Infinity | Data source | Active | 9800 | | FlowCharting | Panel | Deprecated | 7200 | | Carpet plot | Panel | Active | 3400 | | Clock Panel | Panel | Deprecated | 15600 | | Diagram | Panel | Active | 5100 | | FlowCharting | Panel | Active | 8900 | | Breadcrumb | Panel | Active | 1200 | | Clock | Panel | Active | 22000 | | Boom Table | Panel | Active | 6700 | « Prev Next » ## 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. Expand table | 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/writers-toolkit/write/front-matter/#use-the-docsalias-shortcode). ## Docs/alloy-config The `docs/alloy-config` shortcode renders an interactive, collapsible configuration tree from a Markdown table. ### Docs/alloy-config example Markdown ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```markdown {{< docs/alloy-config >}} | Block | Description | Required | | --------------------------------------------------------- | --------------------------------------------------------------------------------- | -------- | | [`resolver`][resolver] | Configures discovering the endpoints to export to. | yes | | `resolver` > [`aws_cloud_map`][aws_cloud_map] | AWS CloudMap-sourced list of endpoints to export to. | no | | `resolver` > [`dns`][dns] | DNS-sourced list of endpoints to export to. | no | | `resolver` > [`kubernetes`][kubernetes] | Kubernetes-sourced list of endpoints to export to. | no | | `resolver` > [`static`][static] | Static list of endpoints to export to. | no | | [`protocol`][protocol] | Protocol settings. Only OTLP is supported at the moment. | no | | `protocol` > [`otlp`][otlp] | Configures an OTLP exporter. | no | | `protocol` > `otlp` > [`client`][client] | Configures the exporter gRPC client. | no | | `protocol` > `otlp` > `client` > [`keepalive`][keepalive] | Configures keepalive settings for the gRPC client. | no | | `protocol` > `otlp` > `client` > [`tls`][tls] | Configures TLS for the gRPC client. | no | | `protocol` > `otlp` > `client` > `tls` > [`tpm`][tpm] | Configures TPM settings for the TLS `key_file`. | no | | `protocol` > `otlp` > [`queue`][queue] | Configures batching of data before sending. | no | | `protocol` > `otlp` > [`retry`][retry] | Configures retry mechanism for failed requests. | no | | [`sending_queue`][queue] | Configures batching of data before sending to the `otlp > protocol` exporter. | no | | `sending_queue` > [`batch`][batch] | Configures batching requests based on a timeout and a minimum number of items. | no | | [`retry`][retry] | Configures retry mechanism for failed requests to the `otlp > protocol` exporter. | no | | [`debug_metrics`][debug_metrics] | Configures the metrics that this component generates to monitor its state. | no | There are two types of [queue][] and [retry][] blocks: - The queue and retry blocks under `protocol > otlp`. This is useful for temporary problems with a specific backend, like transient network issues. - The top-level queue and retry blocks for `otelcol.exporter.loadbalancing`. Those configuration options provide capability to re-route data into a new set of healthy backends. This is useful for highly elastic environments like Kubernetes, where the list of resolved endpoints changes frequently due to deployments and scaling events. [resolver]: #resolver [static]: #static [dns]: #dns [kubernetes]: #kubernetes [aws_cloud_map]: #aws_cloud_map [protocol]: #protocol [otlp]: #otlp [client]: #client [tls]: #tls [tpm]: #tpm [keepalive]: #keepalive [queue]: #queue [batch]: #batch [retry]: #retry [debug_metrics]: #debug_metrics {{< /docs/alloy-config >}} ``` Produces: No valid configuration blocks found. ## 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`](https://github.com/grafana/website/blob/master/data/docs/copy.yaml). If you aren’t a Grafana Labs employee, request changes by [creating an issue](https://github.com/grafana/writers-toolkit/issues/new). Expand table | 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 Markdown ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```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. Expand table | 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 Markdown ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```markdown {{< docs/experimental product="experimental-feature" featureFlag="its-feature-flag" >}} ``` Produces: > Note > > experimental-feature is an [experimental feature](/docs/release-life-cycle/). 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. Do not enable this feature in production environments. ## 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](https://github.com/grafana/killercoda/blob/staging/docs/transformer.md#about-the-transformer-tool). ### Example Markdown ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```markdown This is rendered before the ignore. {{< docs/ignore >}} This isn't rendered. {{< /docs/ignore >}} This is rendered after the ignore. ``` Produces: This is rendered before the ignore. This is rendered after the ignore. ## Docs/learning-journeys The `docs/learning-journeys` shortcode produces a call to action (CTA) that links to a Grafana Learning Journey. Expand table | Parameter | Description | Required | |-----------|--------------------------------------------|----------| | `title` | The title of the Grafana Learning Journey. | yes | | `url` | The URL of the Grafana Learning Journey. | yes | ### Example Markdown ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```markdown {{< docs/learning-journeys title="Explore data using Metrics Drilldown" url="https://grafana.com/docs/learning-journeys/drilldown-metrics/" >}} ``` Produces: Start your learning experience with Grafana Learning Paths Grafana Learning Paths provide a clear, structured path that leads you from beginner concepts to advanced use cases. Learn about this Grafana feature on [Explore data using Metrics Drilldown](/docs/learning-journeys/drilldown-metrics/). [Start learning](https://grafana.com/docs/learning-journeys/drilldown-metrics/) ## Docs/list The `docs/list` shortcode restarts the numbering of ordered lists that occur after a list from shared content. To restart the list, wrap the shared content and subsequent list items. For example: Markdown ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```markdown To build a dashboard with the Infinity data source, complete the following steps: {{< docs/list >}} {{< shared-snippet path="/path/to/file/index.md" id="unique-identifier" >}} 1. Search for the Infinity data source and select it. {{< /docs/list >}} ``` ## Docs/openapi/info Display information about an OpenAPI 3.0+ specification, use either the `url` or `data` parameter to specify an OpenAPI specification. Expand table | 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: Markdown ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```markdown {{< docs/openapi/info url="" >}} ``` To use a local specification from the website `data/docs/openapi/` directory: Markdown ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```markdown {{< docs/openapi/info data="" >}} ``` ### Example Display the API information for a remote specification at `https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/examples/v3.0/petstore-expanded.json`: Markdown ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```markdown {{< docs/openapi/info url="https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/examples/v3.0/petstore-expanded.json" >}} ``` Display the API information for a local specification named `grafana`: Markdown ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```markdown {{< docs/openapi/info data="grafana" >}} ``` ## Docs/openapi/path Display API path information, use either the `url` or `data` parameter to specify an OpenAPI specification. Expand table | 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](/docs/grafana-cloud/testing/k6/reference/cloud-rest-api/v6/) 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: Markdown ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```markdown {{< docs/openapi/path data="grafana" >}} or {{< docs/openapi/path data="grafana" scope="" >}} ``` Display only paths with the `enterprise` tag for the `grafana` data specification: Markdown ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```markdown {{< docs/openapi/path data="grafana" scope="enterprise" >}} ``` ## Docs/play The `docs/play` shortcode produces a call to action (CTA) that links to a Grafana Play dashboard. Expand table | Parameter | Description | Required | |-----------|------------------------------------------|----------| | `title` | The title of the Grafana Play dashboard. | yes | | `url` | The URL of the Grafana Play dashboard. | yes | ### Example Markdown ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```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](https://play.grafana.org/d/000000016/1-time-series-graphs). [Try it](https://play.grafana.org/d/000000016/1-time-series-graphs) ## 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. Expand table | Parameter | Description | Required | |-----------|-------------------------------------|----------| | `product` | The name of the product or feature. | yes | Markdown ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```markdown {{< docs/private-preview product="private-preview-feature" >}} ``` Produces: > Note > > private-preview-feature is currently in [private preview](/docs/release-life-cycle/). 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. Expand table | 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 | Markdown ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```markdown {{< docs/public-preview product="public-preview-feature" >}} ``` Produces: > Note > > public-preview-feature is currently in [public preview](/docs/release-life-cycle/). Grafana Labs offers limited support, and breaking changes might occur prior to the feature being made generally available. Markdown ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```markdown {{< docs/public-preview product="public-preview-feature" featureFlag="its-feature-flag" >}} ``` Produces: > Note > > public-preview-feature is currently in [public preview](/docs/release-life-cycle/). Grafana Labs offers limited support, and breaking changes might occur prior to the feature being made generally available. > > To use this feature, enable the its-feature-flag feature toggle in your Grafana configuration file or contact Support. Markdown ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```markdown {{< docs/public-preview featureFlag="a-feature-flag" >}} ``` Produces: > Note > > To use this feature, enable the a-feature-flag feature toggle in your Grafana configuration file or contact Support. ## 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](/docs/writers-toolkit/write/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 ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```markdown {{% docs/reference %}} [dashboards]: "/docs/grafana/ -> /docs/grafana//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"` - *`