Menu
Open source

Links

Choose your link type based on the applicable scenario:

Although these other types of links still function, replace them with full URLs:

Use the docs/reference shortcode.

The source is reused as described in Reuse directories of content with Hugo mounts. For more information and examples, refer to docs/reference shortcode.

Use a full URL.

Note

The doc-validator linter doesn’t check links that use full URLs.

If you are linking to versioned documentation, use a full 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 path. 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, <GRAFANA_VERSION> is substituted with the version inferred from the page’s URL.
  • If you’re linking from other documentation, <GRAFANA_VERSION> is substituted 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, <MIMIR_VERSION> is substituted with the version inferred from the page’s URL.
  • If you’re linking from other documentation, <MIMIR_VERSION> is substituted 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, don’t.

For example:

markdown
https://github.com

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.