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
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
|
---
title: Links and cross references
description: Shortcodes for creating links to documents.
categories: [content management]
keywords: ["cross references","references", "anchors", "urls"]
menu:
docs:
parent: content-management
weight: 170
toc: true
weight: 170
aliases: [/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.
```text
.
└── 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:
```text
{{</* 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:
```text
{{</* 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:
```text
[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
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 `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.
[lists]: /templates/lists/
[output formats]: /templates/output-formats/
[shortcode]: /content-management/shortcodes/
|
