mirror of
https://github.com/gohugoio/hugo.git
synced 2024-11-14 20:37:55 -05:00
9cabb46f68
d1157b687 Fix typo -- missing word in title 34c9a9ff3 Remove Hartwell Insurance subpage broken link d42f6d8eb Fix strings.Repeat documentation 09b49debb Release 0.76.5 149877735 Merge branch 'tempv0.76.5' 72ffeb026 releaser: Add release notes to /docs for release of 0.76.5 4150d8ae8 Fixed typo: update PrevPage to Prev c3e630db1 Update index.md deb7520a8 Release 0.76.4 f58bd7134 Merge branch 'tempv0.76.4' 2581fe4bc releaser: Add release notes to /docs for release of 0.76.4 26d8417fc Release 0.76.3 34c49e06a Merge branch 'tempv0.76.3' 0de2af2ef releaser: Add release notes to /docs for release of 0.76.3 cce12c0f7 Add missing closing quotes and fix code-block lang (#1250) 8c1c80d9f Update AMP link (#1251) 7b1211ffa Fix typos in multilingual.md 29e9d70fd Update index.md 172a5480b Release 0.76.2 93ff424d3 Merge branch 'temp762' 3cad3c23a releaser: Add release notes to /docs for release of 0.76.2 610221964 Update index.md 8a9d31709 Release 0.76.1 64b245aa4 Merge branch 'temp761' f19469ff8 releaser: Add release notes to /docs for release of 0.76.1 97f0ed030 Update front-matter.md cca71f263 Update index.md 23c64f6a3 Fix typo in 0.76.0 release note 5f79e034d Update index.md b66567de2 netlify: Bump to Hugo 0.76.0 a3e30300d Release 0.76.0 3b057e8fe releaser: Add release notes to /docs for release of 0.76.0 7fa1cd912 docs: Regen docshelper 769712aec Merge commit 'e5568488051a571df48401e03f1304b95dbc9028' 70ce6ae33 pagemeta: Make BuildConfig.Render an enum a78d3849f Allow cascade to be a slice with a _target discriminator 705fea656 Add force flag to server redirects config 04e4e1cc1 tpl: Add Do Not Track (dnt) option to Vimeo shortcode 025c19fe1 Fix CLI example for PostCSS 8 0c70c47b2 markup/asciidocext: Add preserveTOC option git-subtree-dir: docs git-subtree-split: d1157b687e25054501c3bcbb735da51229f66b74
129 lines
3.3 KiB
Markdown
129 lines
3.3 KiB
Markdown
---
|
|
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/
|
|
[bfext]: /content-management/formats/#blackfriday-extensions
|