--- title: "Links | Writers' Toolkit documentation" description: "Understand how to link between pages." --- # Links Choose your link type based on your goal: - [Link from source content that’s reused as multiple pages](#link-from-source-content-thats-reused-as-multiple-pages) - [Link to `grafana.com` pages](#link-to-grafanacom-pages) - [Link to external pages](#link-to-external-pages) - [Link to page headings](#link-to-page-headings) - Use this with one of the preceding options. - [Link to Grafana Cloud resources](#link-to-grafana-cloud-resources) Although these other types of links still function, replace them with one of the preceding options: - [`docs/reference` shortcode](/docs/writers-toolkit/write/shortcodes/#docsreference) ## Link from source content that’s reused as multiple pages Use a URL, including [version substitution syntax](/docs/writers-toolkit/write/shortcodes/#about-version-substitution) if needed. For example: `/docs/grafana//alerting/fundamentals/alert-rules/` During link rendering, Hugo checks if the link destination is a mounted source. If it’s mounted, then Hugo checks if the current page is in the same project as the mount target. If it is in the same project, then Hugo replaces the link destination with the mount target. If it isn’t mounted, or the mount target isn’t in the same project, then Hugo uses the link as normal. > Note > > Automatic mount links requires the Docs Platform team to set `mount_links: true` in the mount target front matter. > > Projects that have automatic mount links include: > > - [Grafana Cloud](/docs/grafana-cloud/) > - [Grafana Enterprise Metrics](/docs/enterprise-metrics/) > - [Grafana Enterprise Traces](/docs/enterprise-traces/) > > Contact the Docs Platform team in the #docs-platform Slack channel if you want another project to use this behavior. ### Mount links example The Grafana Labs website configuration mounts the open source Grafana Alerting documentation into the Grafana Cloud documentation. From the Grafana Alerting introduction page, the link `[alert rule](/docs/grafana//alerting/fundamentals/alert-rules/)` has different destinations in the open source and cloud versions of the page. - In the open source version, the link stays the same. - For Grafana Cloud, Hugo changes the link destination from [`/docs/grafana/next/alerting/fundamentals/alert-rules/`](/docs/grafana/next/alerting/fundamentals/alert-rules/) to [`/docs/grafana-cloud/alerting-and-irm/alerting/fundamentals/alert-rules/`](/docs/grafana-cloud/alerting-and-irm/alerting/fundamentals/alert-rules/). ### `ref` URIs For most links, the automatic mount links behavior is correct but there may be times where you want to explicitly control the multiple destinations for a link. To do this, use `ref` URIs. `ref` URIs have two components: - [Link](#link) - [Front matter](#front-matter) `ref` URIs look up destinations based upon the page’s URL path and the definitions in the page’s front matter. #### Link A link with a `ref` URI looks like: Markdown ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```markdown [LINK TEXT](ref:) ``` For the *``* , enter an alphabetic term. It can include hyphens (`-`). Hugo looks up *``* in the value for the `refs` field in the page’s front matter. If there is no *``* in the `refs` field, or there is no `refs` field in the front matter, Hugo logs a build error. #### Front matter A partial front matter containing the `refs` field looks like: YAML ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```yaml refs: : - pattern: destination: - pattern: destination: ``` - *``* - Enter the part of the page URL that represents the project in which the documentation is published. - `destination` - Enter the full URL of the destination page for that project including trailing slashes. If the page’s URL matches the pattern *``* , then Hugo uses `destination` as the link destination. If no pattern matches the current page, Hugo logs a build error. The *``* destination has the same behavior as described in [Link to `grafana.com` pages](/docs/writers-toolkit/write/links/#link-to-grafanacom-pages) #### Example The following Markdown snippet demonstrates the `refs` front matter and link that uses a `ref` URI. Markdown ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```markdown --- refs: find-plugins: - pattern: /docs/grafana/ destination: /docs/grafana//administration/plugin-management/#browse-plugins - pattern: /docs/grafana-cloud/ destination: /docs/grafana-cloud/introduction/find-and-use-plugins/ --- # Manage plugins ## Before you begin - Find the plugin you want to install. To find a plugin, refer to [Find and use plugins](ref:find-plugins). ``` In the latest version of a Grafana documentation page, the link destination is [https://grafana.com/docs/grafana/latest/administration/plugin-management/#browse-plugins](/docs/grafana/latest/administration/plugin-management/#browse-plugins). Hugo replaces the [version substitution syntax](/docs/writers-toolkit/write/shortcodes/#about-version-substitution) `` with the version inferred from the current page. In a Grafana Cloud page, the link destination is [https://grafana.com/docs/grafana-cloud/introduction/find-and-use-plugins/](/docs/grafana-cloud/introduction/find-and-use-plugins/). ## Link to `grafana.com` pages Use a URL. If you’re linking to versioned documentation within your own documentation, use a URL with version substitution syntax instead of the version path element. For example, instead of the URL `https://grafana.com/docs/grafana/latest/`, use `https://grafana.com/docs/grafana//`. If you’re linking to versioned documentation in another project, use version substitution if you have version compatibility constraints between the projects. Refer to the target project in the version substitution. You only need version substitution if you’re maintaining a specific matrix of version mappings. For example, the Mimir Helm chart for a given release targets supports working only with a specific version of Mimir and Grafana Enterprise Metrics: [`grafana/mimir@mimir-distributed-release-5.7/docs/sources/helm-charts/mimir-distributed/_index.md`](https://github.com/grafana/mimir/blob/mimir-distributed-release-5.7/docs/sources/helm-charts/mimir-distributed/_index.md?plain=1&rgh-link-date=2025-08-05T16%3A16%3A51Z#L11-L12). In this case, when linking to the Mimir documentation from Grafana, use ``. If you don’t have those constraints, use `latest` in the URL. When Hugo renders links with version substitution, it replaces the `` syntax with the version inferred from the current page. To understand the behavior in more detail, refer to [About version substitution](/docs/writers-toolkit/write/shortcodes/#about-version-substitution) For examples of behavior, refer to [Examples](#examples). > Caution > > Using version substitution when you link to other projects requires you to set the cascading front matter that specifies the target project version. If you don’t set this, links in “next” and “latest” versions work but other versions won’t. To override the version inferred by version substitution, set the preferred version in the root `_index.md` file for your documentation. The following YAML snippet sets `GRAFANA_VERSION` to be `latest` for that page and all child pages. You must merge the following YAML example with the front matter in the root `_index.md` file. YAML ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```yaml cascade: GRAFANA_VERSION: latest ``` ### Examples **Link to Grafana documentation**: Start with `https://grafana.com/docs/grafana//`, and add the rest of the URL. Include trailing slashes. For example, to link to the [Developers](/docs/grafana/latest/developers/) page with version substitution, use: Markdown ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```markdown https://grafana.com/docs/grafana//developers/ ``` - If you’re linking from Grafana documentation, Hugo replaces `` with the version inferred from the page’s URL. - If you’re linking from other documentation, Hugo replaces `` with the value of `GRAFANA_VERSION` from the source page’s front matter. **Link to Grafana Cloud documentation**: Grafana Cloud documentation isn’t versioned and doesn’t require version substitution syntax. Use the full URL. For example, to link to the [Author and run tests](/docs/grafana-cloud/k6/author-run/) page, use: Markdown ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```markdown https://grafana.com/docs/grafana-cloud/k6/author-run/ ``` **Link to Mimir documentation**: Start with `https://grafana.com/docs/grafana//`, and add the rest of the URL path. For example, to link to the [Release notes](/docs/mimir/latest/release-notes/) page with version substitution, use: Markdown ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```markdown https://grafana.com/docs/mimir//release-notes/ ``` - If you’re linking from Mimir documentation, Hugo replaces `` with the version inferred from the page’s URL. - If you’re linking from other documentation, Hugo replaces `` with the value of `MIMIR_VERSION` from the source page’s front matter. ## Link to external pages Use the full URL. Copy the URL exactly from the address bar. If it includes a trailing slash, include it. If it doesn’t include a trailing slash, don’t add one. For example: Markdown ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```markdown https://github.com ``` ## Link to page headings Link to a heading on a page in one of two ways. From within the same page: Markdown ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```markdown Read more in the [Configuration section](#configuration) of this page. ``` From a different page: Markdown ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```markdown Read more in the [Grafana Open Source section of the Introduction page](https://grafana.com/docs/grafana//fundamentals/#grafana-open-source). ``` Include the trailing slash before the hash (#) that precedes the page heading. To convert a heading to an anchor, make the following changes: 1. Convert to lower case. 2. Remove any period characters (`.`). 3. Replace any character that’s not a lower cased letter, a number, or an underscore (`_`) with dashes (`-`). 4. Trim any preceding or proceeding dashes (`-`). 5. Prefix with a `#`. The heading *Link to page headings* becomes the anchor `#link-to-page-headings`. ## Link to Grafana Cloud resources Use deep links to direct users to specific pages in their Grafana Cloud instances. Deep links prompt the user to select their organization and stack, and then navigate to the specified page. The link path follows `https://grafana.com/launch/` and appends the target page path. For example: Markdown ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```markdown https://grafana.com/launch/dashboards ``` This link opens the **Dashboards** page in the selected stack: Markdown ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```markdown https://STACK_NAME.grafana.net/dashboards ``` ### Examples The following examples show deep links to Grafana Cloud pages: - `https://grafana.com/launch/a/grafana-irm-app/incidents` Opens the **Alerts & IRM > IRM > [Incidents](/launch/a/grafana-irm-app/incidents)** page. - `https://grafana.com/launch/connections/datasources/new` Opens the **Connections > Data sources > [Add data source](/launch/connections/datasources/new)** page.