github.com/shohhei1126/hugo@v0.42.2-0.20180623210752-3d5928889ad7/docs/content/en/content-management/cross-references.md (about) 1 --- 2 title: Links and Cross References 3 description: Hugo makes it easy to link documents together. 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 19 The `ref` and `relref` shortcodes link documents together, both of which are [built-in Hugo shortcodes][]. These shortcodes are also used to provide links to headings inside of your content, whether across documents or within a document. The only difference between `ref` and `relref` is whether the resulting URL is absolute (`http://1.com/about/`) or relative (`/about/`), respectively. 20 21 ## Use `ref` and `relref` 22 23 ``` 24 {{</* ref "document.md" */>}} 25 {{</* ref "#anchor" */>}} 26 {{</* ref "document.md#anchor" */>}} 27 {{</* relref "document.md" */>}} 28 {{</* relref "#anchor" */>}} 29 {{</* relref "document.md#anchor" */>}} 30 ``` 31 32 The single parameter to `ref` is a string with a content `documentname` (e.g., `about.md`) with or without an appended in-document `anchor` (`#who`) without spaces. 33 34 ### Document Names 35 36 The `documentname` is the name of a document, including the format extension; this may be just the filename, or the relative path from the `content/` directory. With a document `content/blog/post.md`, either format will produce the same result: 37 38 ``` 39 {{</* relref "blog/post.md" */>}} => `/blog/post/` 40 {{</* relref "post.md" */>}} => `/blog/post/` 41 ``` 42 43 If you have the same filename used across multiple sections, you should only use the relative path format; otherwise, the behavior will be `undefined`. This is best illustrated with an example `content` directory: 44 45 ``` 46 . 47 └── content 48 ├── events 49 │ └── my-birthday.md 50 ├── galleries 51 │ └── my-birthday.md 52 ├── meta 53 │ └── my-article.md 54 └── posts 55 └── my-birthday.md 56 ``` 57 58 To be sure to get the correct reference in this case, use the full path: 59 60 {{< code file="content/meta/my-article.md" copy="false" >}} 61 {{</* relref "events/my-birthday.md" */>}} => /events/my-birthday/ 62 {{< /code >}} 63 64 ### With Multiple Output Formats 65 66 If the page exists in multiple [output formats][], `ref` or `relref` can be used with a output format name: 67 68 ``` 69 [Neat]({{</* ref "blog/neat.md" "amp" */>}}) 70 ``` 71 72 ### Anchors 73 74 When an `anchor` is provided by itself, the current page’s unique identifier will be appended; when an `anchor` is provided appended to `documentname`, the found page's unique identifier will be appended: 75 76 ``` 77 {{</* relref "#anchors" */>}} => #anchors:9decaf7 78 {{</* relref "about-hugo/hugo-features.md#content" */>}} => /blog/post/#who:badcafe 79 ``` 80 81 The above examples render as follows for this very page as well as a reference to the "Content" heading in the Hugo docs features pageyoursite 82 83 ``` 84 {{</* relref "#who" */>}} => #who:9decaf7 85 {{</* relref "blog/post.md#who" */>}} => /blog/post/#who:badcafe 86 ``` 87 88 More information about document unique identifiers and headings can be found [below]({{< ref "#hugo-heading-anchors" >}}). 89 90 ### Examples 91 92 * `{{</* ref "blog/post.md" */>}}` => `https://example.com/blog/post/` 93 * `{{</* ref "post.md#tldr" */>}}` => `https://example.com/blog/post/#tldr:caffebad` 94 * `{{</* relref "post.md" */>}}` => `/blog/post/` 95 * `{{</* relref "blog/post.md#tldr" */>}}` => `/blog/post/#tldr:caffebad` 96 * `{{</* ref "#tldr" */>}}` => `#tldr:badcaffe` 97 * `{{</* relref "#tldr" */>}}` => `#tldr:badcaffe` 98 99 ## Hugo Heading Anchors 100 101 When using Markdown document types, Hugo generates heading anchors automatically. The generated anchor for this section is `hugo-heading-anchors`. Because the heading anchors are generated automatically, Hugo takes some effort to ensure that heading anchors are unique both inside a document and across the entire site. 102 103 Ensuring heading uniqueness across the site is accomplished with a unique identifier for each document based on its path. Unless a document is renamed or moved between sections *in the filesystem*, the unique identifier for the document will not change: `blog/post.md` will always have a unique identifier of `81df004c333b392d34a49fd3a91ba720`. 104 105 `ref` and `relref` were added so you can make these reference links without having to know the document’s unique identifier. (The links in document tables of contents are automatically up-to-date with this value.) 106 107 ``` 108 {{</* relref "content-management/cross-references.md#hugo-heading-anchors" */>}} 109 /content-management/cross-references/#hugo-heading-anchors:77cd9ea530577debf4ce0f28c8dca242 110 ``` 111 112 ### Manually Specifying Anchors 113 114 For Markdown content files, if the `headerIds` [Blackfriday extension][bfext] is 115 enabled (which it is by default), user can manually specify the anchor for any 116 heading. 117 118 Few examples: 119 120 ``` 121 ## Alpha 101 {#alpha} 122 123 ## Version 1.0 {#version-1-dot-0} 124 ``` 125 126 [built-in Hugo shortcodes]: /content-management/shortcodes/#using-the-built-in-shortcodes 127 [lists]: /templates/lists/ 128 [output formats]: /templates/output-formats/ 129 [shortcode]: /content-management/shortcodes/ 130 [bfext]: /content-management/formats/#blackfriday-extensions