1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
|
---
title: Links and Cross References
description: Shortcodes for creating links to documents.
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-03-31
categories: [content management]
keywords: ["cross references","references", "anchors", "urls"]
menu:
docs:
parent: "content-management"
weight: 100
weight: 100 #rem
aliases: [/extras/crossreferences/]
toc: true
---
The `ref` and `relref` shortcodes display the absolute and relative permalinks to a document, respectively.
## Use `ref` and `relref`
```go-html-template
{{</* 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:
```md
[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:
```go-html-template
{{</* relref path="document.md" lang="ja" */>}}
```
### Get another Output Format
To link to another Output Format of a document, use this syntax:
```go-html-template
{{</* 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:
```md
## Reference
```
produces this HTML:
```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:
```go-html-template
{{</* ref "document.md#reference" */>}}
{{</* relref "document.md#reference" */>}}
```
Generate a custom heading ID by including an attribute. For example:
```md
## Reference A {#foo}
## Reference B {id="bar"}
```
produces this HTML:
```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:
```md
## Reference
## Reference
## Reference
```
produces this HTML:
```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.
[lists]: /templates/lists/
[output formats]: /templates/output-formats/
[shortcode]: /content-management/shortcodes/
|
