hugo/docs/content/en/content-management/cross-references.md
2019-03-26 18:41:36 +01:00

2.9 KiB
Raw Blame History

title description date publishdate lastmod categories keywords menu weight aliases toc
Links and Cross References Shortcodes for creating links to documents. 2017-02-01 2017-02-01 2017-03-31
content management
cross references
references
anchors
urls
docs
parent weight
content-management 100
100
/extras/crossreferences/
true

The ref and relref shortcode resolves the absolute or relative permalink given a path to a document.

Use ref and relref

{{</* ref "document.md" */>}}
{{</* ref "#anchor" */>}}
{{</* ref "document.md#anchor" */>}}
{{</* ref "/blog/my-post" */>}}
{{</* ref "/blog/my-post.md" */>}}
{{</* relref "document.md" */>}}
{{</* relref "#anchor" */>}}
{{</* relref "document.md#anchor" */>}}

The single parameter to ref is a string with a content documentname (e.g., about.md) with or without an appended in-document anchor (#who) without spaces. Hugo is flexible in how we search for documents, so the file suffix may be omitted.

Paths without a leading / will first be tried resolved relative to the current page.

You will get an error if your document could not be uniquely resolved. The error behaviour can be configured, see below.

Link to another language version of a document, you need to use this syntax:

{{</* relref path="document.md" lang="ja" */>}}

Get another Output Format

To link to a given Output Format of a document, you can use this syntax:

{{</* relref path="document.md" outputFormat="rss" */>}}

Anchors

When an anchor is provided by itself, the current pages unique identifier will be appended; when an anchor is provided appended to documentname, the found page's unique identifier will be appended:

{{</* relref "#anchors" */>}} => #anchors:9decaf7

The above examples render as follows for this very page as well as a reference to the "Content" heading in the Hugo docs features pageyoursite

{{</* relref "#who" */>}} => #who:9decaf7
{{</* relref "/blog/post.md#who" */>}} => /blog/post/#who:badcafe

More information about document unique identifiers and headings can be found [below]({{< ref "#hugo-heading-anchors" >}}).

Ref and RelRef Configuration

The behaviour can, since Hugo 0.45, be configured in config.toml:

refLinksErrorLevel ("ERROR")
When using ref or relref to resolve page links and a link cannot resolved, it will be logged with this log level. Valid values are ERROR (default) or WARNING. Any ERROR will fail the build (exit -1).
refLinksNotFoundURL
URL to be used as a placeholder when a page reference cannot be found in ref or relref. Is used as-is.