cross-references.md (3315B)
1 ---
2 title: Links and Cross References
3 description: Shortcodes for creating links to documents.
4 date: 2017-02-01
5 publishdate: 2017-02-01
6 lastmod: 2017-03-31
7 categories: [content management]
8 keywords: ["cross references","references", "anchors", "urls"]
9 menu:
10 docs:
11 parent: "content-management"
12 weight: 100
13 weight: 100 #rem
14 aliases: [/extras/crossreferences/]
15 toc: true
16 ---
17
18 The `ref` and `relref` shortcodes display the absolute and relative permalinks to a document, respectively.
19
20 ## Use `ref` and `relref`
21
22 ```go-html-template
23 {{</* ref "document" */>}}
24 {{</* ref "document#anchor" */>}}
25 {{</* ref "document.md" */>}}
26 {{</* ref "document.md#anchor" */>}}
27 {{</* ref "#anchor" */>}}
28 {{</* ref "/blog/my-post" */>}}
29 {{</* ref "/blog/my-post.md" */>}}
30 {{</* relref "document" */>}}
31 {{</* relref "document.md" */>}}
32 {{</* relref "#anchor" */>}}
33 {{</* relref "/blog/my-post.md" */>}}
34 ```
35
36 To generate a hyperlink using `ref` or `relref` in markdown:
37
38 ```md
39 [About]({{</* ref "/page/about" */>}} "About Us")
40 ```
41
42 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.
43
44 **Paths without a leading `/` are first resolved relative to the current page, then to the remainder of the site.
45
46 Hugo emits an error or warning if a document cannot be uniquely resolved. The error behavior is configurable; see below.
47
48 ### Link to another language version
49
50 To link to another language version of a document, use this syntax:
51
52 ```go-html-template
53 {{</* relref path="document.md" lang="ja" */>}}
54 ```
55
56 ### Get another Output Format
57
58 To link to another Output Format of a document, use this syntax:
59
60 ```go-html-template
61 {{</* relref path="document.md" outputFormat="rss" */>}}
62 ```
63
64 ### Heading IDs
65
66 When using Markdown document types, Hugo generates element IDs for every heading on a page. For example:
67
68 ```md
69 ## Reference
70 ```
71
72 produces this HTML:
73
74 ```html
75 <h2 id="reference">Reference</h2>
76 ```
77
78 Get the permalink to a heading by appending the ID to the path when using the `ref` or `relref` shortcodes:
79
80 ```go-html-template
81 {{</* ref "document.md#reference" */>}}
82 {{</* relref "document.md#reference" */>}}
83 ```
84
85 Generate a custom heading ID by including an attribute. For example:
86
87 ```md
88 ## Reference A {#foo}
89 ## Reference B {id="bar"}
90 ```
91
92 produces this HTML:
93
94 ```html
95 <h2 id="foo">Reference A</h2>
96 <h2 id="bar">Reference B</h2>
97 ```
98
99 Hugo will generate unique element IDs if the same heading appears more than once on a page. For example:
100
101 ```md
102 ## Reference
103 ## Reference
104 ## Reference
105 ```
106
107 produces this HTML:
108
109 ```html
110 <h2 id="reference">Reference</h2>
111 <h2 id="reference-1">Reference</h2>
112 <h2 id="reference-2">Reference</h2>
113 ```
114
115 ## Ref and RelRef Configuration
116
117 The behavior can, since Hugo 0.45, be configured in `config.toml`:
118
119 refLinksErrorLevel ("ERROR")
120 : 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`).
121
122 refLinksNotFoundURL
123 : URL to be used as a placeholder when a page reference cannot be found in `ref` or `relref`. Is used as-is.
124
125
126 [lists]: /templates/lists/
127 [output formats]: /templates/output-formats/
128 [shortcode]: /content-management/shortcodes/