hugo/docs/content/en/content-management/cross-references.md
2023-05-27 17:02:23 +02:00

4.2 KiB

title linkTitle description categories keywords menu toc weight aliases
Links and Cross References Links and Cross References Shortcodes for creating links to documents.
content management
cross references
references
anchors
urls
docs
parent weight
content-management 170
true 170
/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 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.

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