Writers' Toolkit Write Links and cross references
Open source

Links and cross references

Links are a mechanism for reusing content. Instead of writing the same information twice, you can link to a definitive source of truth.

Note: When linking to specific versions or across repositories, use standard markdown links. Read the Versions and cross-repository linking section for details.

Links can be written in many forms that are enumerated in : The Anchor element - HTML: HyperText Markup Language | MDN.

This document focuses only on HTTP-based URLs that have the scheme http or https.

Link destinations can be specified in different ways. All of the following destinations link to when followed from the page

To choose the correct link destination type, follow these steps:

  1. If the destination is external to the website, use the fully specified HTTPS URL. For example, [GitHub](

  2. If the source is reused as described in Reuse directories of content with Hugo mounts:

    1. If the destination is also present in the destination mount, use a relative URL path. This keeps reader within the destination project. For example, {{< relref "./path/to/page" >}}.

      Use the Hugo relref shortcode for build time link checking. For more information about the relref shortcode, refer to Build time link checking with Hugo.

    2. Otherwise use a partial URL with an absolute path. This always brings the reader back to the destination page in the source project. For example, /docs/writers-toolkit/write/.

  3. If the destination is internal to the website, but external to the project documentation, use a partial URL with an absolute path. For example, /blog/.

  4. Otherwise, use a relative path. For example, {{< relref "./path/to/page" >}}.

    Use the Hugo relref shortcode for build time link checking. For more information about the relref shortcode, refer to Build time link checking with Hugo.

Hugo has built-in shortcodes for creating links to documents. The ref and relref shortcodes display the absolute and relative permalinks to a document, respectively. They both provide build time link checking to ensure that the destination exists.

Warning: If you do not use a Hugo relref shortcode for build time link checking, your links may be broken without you realizing it.

Relative references are the most common references in Grafana technical documentation. This is the Hugo shortcode: {{< relref "<DESTINATION>" >}}.

Note: Hugo link checking depends on having all the content available during the build. In most projects, the only content available during local builds and CI is the current project documentation. Therefore, the current advice is that relrefs should only be used for links within the current project.

Determine relref shortcode destinations

With the following directory structure:

└── sources
    ├── branch
    │   └──
    │   └──
    └── leaf

Hugo produces the following website pages:


Refer to the following table for the correct relref shortcode to use to link between each of the example pages.

Source pageDestination pagerelref shortcode
/docs/writers-toolkit/branch//docs/writers-toolkit/branch/other/{{< relref "./other" >}}
/docs/writers-toolkit/branch//docs/writers-toolkit/leaf/{{< relref "../leaf" >}}
/docs/writers-toolkit/leaf//docs/writers-toolkit/branch/{{< relref "../branch" >}}
/docs/writers-toolkit/leaf//docs/writers-toolkit/branch/other/{{< relref "../branch/other" >}}
/docs/writers-toolkit/branch/other//docs/writers-toolkit/branch/{{< relref "." >}}
/docs/writers-toolkit/branch/other//docs/writers-toolkit/leaf/{{< relref "../leaf" >}}
Warning: If the destination file or its containing directory has a period (.) in the path, you must link to the source file directly.

Versions and cross-repository linking

For Grafana’s webserver environments, you can’t address other versions of the docs, such as a version-specific archived docs set ( and so forth) or /next/ docs for links in content residing in /latest/, using Hugo references.

Hugo references addressed across different products’ docs, such as from /docs/grafana/ to /docs/loki/ and vice-versa, as well as references from docs addressed to other Hugo-published content on, can also be predictably addressed.

To avoid broken links in these situations on, use regular Markdown link syntax ([link text](/docs/repo/version/folder/file/)) instead of Hugo references (relref). To ensure the links work in local builds, staging environments, and the live website, you shouldn’t use a fully qualified URL with for links to other content on

For cross-repository links, use a standard markdown link, with the link structured like this: /docs/repo/page.

For example:

This is an [example cross-repository link](/docs/grafana/whatsnew) to the Grafana repository.

Using a Hugo relref in a cross-repository link or a link to a specific version can result in a page not found error message when running make docs if the linked content isn’t mounted when using the script.

Unlike references, Hugo does not confirm that these link destinations exist during its build, so manually confirm that the published links in a local build and on the published website point correctly. With partial URIs, you also cannot check these links without the content mounted. For example, /docs/grafana/latest/ from /docs/tempo/latest won’t resolve unless you have both projects mounted in the webserver.


In a reference, you can optionally include an anchor to a heading in the referenced page. Specify and anchor at the end of the reference # followed by the normalized heading.

Hugo normalizes headings to make anchors. To convert a heading to an anchor, Hugo makes 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 (-).

If the anchor is in the current page, you don’t need to use relref syntax. The following Markdown links are equivalent:

  • [link text]({{< relref "#anchor-in-current-page" >}})
  • [link text](#anchor-in-current-page)

Hugo error output

Hugo emits REF_NOT_FOUND warnings indicating the filename and location of such references when building the docs, for example with make docs in grafana/grafana or make server-quick in grafana/website:

WARN 2022/08/04 21:35:37 [en] REF_NOT_FOUND: Ref "../../enterprise": "/hugo/content/docs/grafana/next/administration/roles-and-permissions/access-control/": page not found

In this example,

  • Ref "../../enterprise" is the destination of the reference that Hugo can’t resolve
  • \/hugo/content/docs/grafana/next/administration/roles-and-permissions/access-control/ is the document containing the reference, where the path after /next/ is relative to the documentation root of the component repository
  • :14 represents the line number containing the unresolved reference
  • :47 represents the character in that line where the unresolved reference begins

If the reference’s destination appears to be invalid, for example due to a typo in the reference or the depth of therelref directory, then you should be able to resolve this by correcting the reference target.

For additional information about Hugo error output, refer to Test documentation changes.