Menu
Documentationbreadcrumb arrow Writers' Toolkitbreadcrumb arrow Writebreadcrumb arrow Links
Open source RSS
Last reviewed: June 24, 2024

Links

Choose your link type based on your goal:

Although these other types of links still function, replace them with one of the preceding options:

Link from source content that’s reused as multiple pages

Use a URL, including version substitution syntax if needed. For example:

/docs/grafana/<GRAFANA_VERSION>/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:

Contact the Docs Platform team in the #docs-platform Slack channel if you want another project to use this behavior.

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/<GRAFANA_VERSION>/alerting/fundamentals/alert-rules/) has different destinations in the open source and cloud versions of the page.

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:

ref URIs look up destinations based upon the page’s URL path and the definitions in the page’s front matter.

A link with a ref URI looks like:

markdown 
[LINK TEXT](ref:<KEY>)

For the <KEY> , enter an alphabetic term. It can include hyphens (-).

Hugo looks up <KEY> in the value for the refs field in the page’s front matter. If there is no <KEY> 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 
refs:
  <KEY>:
    - pattern: <URL PATH PREFIX>
      destination: <FULL URL>
    - pattern: <URL PATH PREFIX>
      destination: <FULL URL>
  • <URL PATH PREFIX> - 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 <URL PATH PREFIX>, then Hugo uses destination as the link destination. If no pattern matches the current page, Hugo logs a build error.

The <FULL URL> destination has the same behavior as described in Link to grafana.com pages

Example

The following Markdown snippet demonstrates the refs front matter and link that uses a ref URI.

markdown 
---
refs:
  find-plugins:
    - pattern: /docs/grafana/
      destination: /docs/grafana/<GRAFANA_VERSION>/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. Hugo replaces the version substitution syntax <GRAFANA_VERSION> 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/.

Use a URL.

If you are linking to versioned documentation, use a URL with version substitution syntax instead of the version path element. For example, in Grafana, use <GRAFANA_VERSION> instead of latest in the URL https://grafana.com/docs/grafana/latest/.

When Hugo renders links with version substitution, it replaces the <SOMETHING_VERSION> syntax with the version inferred from the current page.

To understand the behavior in more detail, refer to About version substitution You use full URLs with the substitution variable so that links resolve to the correct version of documentation without requiring the writer to update the version for each release. For examples of behavior, refer to Examples.

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 
cascade:
  GRAFANA_VERSION: latest

Examples

Link to Grafana documentation:

Start with https://grafana.com/docs/grafana/<GRAFANA_VERSION>/, and add the rest of the URL. Include trailing slashes.

For example, to link to the Developers page with version substitution, use:

markdown 
https://grafana.com/docs/grafana/<GRAFANA_VERSION>/developers/
  • If you’re linking from Grafana documentation, Hugo replaces <GRAFANA_VERSION> with the version inferred from the page’s URL.
  • If you’re linking from other documentation, Hugo replaces <GRAFANA_VERSION> 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 page, use:

markdown 
https://grafana.com/docs/grafana-cloud/k6/author-run/

Link to Mimir documentation:

Start with https://grafana.com/docs/grafana/<MIMIR_VERSION>/, and add the rest of the URL path.

For example, to link to the Release notes page with version substitution, use:

markdown 
https://grafana.com/docs/mimir/<MIMIR_VERSION>/release-notes/
  • If you’re linking from Mimir documentation, Hugo replaces <MIMIR_VERSION> with the version inferred from the page’s URL.
  • If you’re linking from other documentation, Hugo replaces <MIMIR_VERSION> with the value of MIMIR_VERSION from the source page’s front matter.

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 
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 
Read more in the [Configuration section](#configuration) of this page.

From a different page:

markdown 
Read more in the [Grafana Open Source section of the Introduction page](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/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.