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

title	description	categories	keywords	menu	weight	toc	aliases
Links and cross references	Shortcodes for creating links to documents.	content management	cross references references anchors urls	docs parent weight content-management 170	170	true	/extras/crossreferences/

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 argument: 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

Using ref or relref without specifying a language, will make the reference resolve to the language of the current content page.

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 be configured in hugo.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.