Links and cross references
The ref
and relref
shortcodes display the absolute and relative permalinks to a document, respectively.
Use of ref
and relref
The ref
and relref
shortcodes require a single parameter: the path to a content document, with or without a file extension, with or without an anchor. Paths without a leading /
are first resolved relative to the current page, then to the remainder of the site.
.
└── content
├── about
| ├── _index.md
| └── credits.md
├── pages
| ├── document1.md
| └── document2.md // has anchor #anchor
├── products
| └── index.md
└── blog
└── my-post.md
The pages can be referenced as follows:
{{< ref "document2" >}} // <- From pages/document1.md, relative path
{{< ref "document2#anchor" >}}
{{< ref "document2.md" >}}
{{< ref "document2.md#anchor" >}}
{{< ref "#anchor" >}} // <- From pages/document2.md
{{< ref "/blog/my-post" >}} // <- From anywhere, absolute path
{{< ref "/blog/my-post.md" >}}
{{< relref "document" >}}
{{< relref "document.md" >}}
{{< relref "#anchor" >}}
{{< relref "/blog/my-post.md" >}}
index.md can be reference either by its path or by its containing folder without the ending /
. _index.md can be referenced only by its containing folder:
{{< ref "/about" >}} // <- References /about/_index.md
{{< ref "/about/_index" >}} // Raises REF_NOT_FOUND error
{{< ref "/about/credits.md" >}} // <- References /about/credits.md
{{< ref "/products" >}} // <- References /products/index.md
{{< ref "/products/index" >}} // <- References /products/index.md
To generate a hyperlink using ref
or relref
in markdown:
[About]({{< ref "/about" >}} "About Us")
Hugo emits an error or warning if a document cannot be uniquely resolved. The error behavior is configurable; see below.
Link to another language version
To link to another language version of a document, use this syntax:
{{< relref path="document.md" lang="ja" >}}
Get another output format
To link to another Output Format of a document, use this syntax:
{{< relref path="document.md" outputFormat="rss" >}}
Heading IDs
When using Markdown document types, Hugo generates element IDs for every heading on a page. For example:
## Reference
produces this HTML:
<h2 id="reference">Reference</h2>
Get the permalink to a heading by appending the ID to the path when using the ref
or relref
shortcodes:
{{< ref "document.md#reference" >}}
{{< relref "document.md#reference" >}}
Generate a custom heading ID by including an attribute. For example:
## Reference A {#foo}
## Reference B {id="bar"}
produces this HTML:
<h2 id="foo">Reference A</h2>
<h2 id="bar">Reference B</h2>
Hugo will generate unique element IDs if the same heading appears more than once on a page. For example:
## Reference
## Reference
## Reference
produces this HTML:
<h2 id="reference">Reference</h2>
<h2 id="reference-1">Reference</h2>
<h2 id="reference-2">Reference</h2>
Ref and RelRef Configuration
The behavior can, since Hugo 0.45, be configured in hugo.toml
:
- refLinksErrorLevel (“ERROR”)
- When using
ref
orrelref
to resolve page links and a link cannot resolved, it will be logged with this log level. Valid values areERROR
(default) orWARNING
. AnyERROR
will fail the build (exit -1
). - refLinksNotFoundURL
- URL to be used as a placeholder when a page reference cannot be found in
ref
orrelref
. Is used as-is.