hugo/docs/content/en/content-management/cross-references.md

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 shortcodes display the absolute and relative permalinks to a document, respectively.

Use ref and relref

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

To generate a hyperlink using ref or relref in markdown:

[About]({{</* ref "/page/about" */>}} "About Us")

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.

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 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.