mirror of
https://github.com/gohugoio/hugo.git
synced 2024-11-14 20:37:55 -05:00
766085c2dc
81847981f Add notes for installing "extended" Sass/SCSS version 02da3bb58 Include usage of disqus internal template 9b53380c4 Update sitemap-template.md f3417dd52 Update sitemap-template.md aae33d9a8 Update sitemap-template.md 834edc205 Release 0.45.1 fb93ab905 Merge branch 'temp451' 79f350906 releaser: Prepare repository for 0.46-DEV 25cd2352c releaser: Add release notes to /docs for release of 0.45.1 e60377c71 releaser: Bump versions for release of 0.45.1 873f6dce2 Update features.md ecc116642 Update link for Azure cb88c3185 Added .Site.Home to Site Variiables (#541) 975a88791 Document includePaths 56c4e332f Release Hugo 0.45 c22b25210 Merge branch 'temp45' 0ffad3ada releaser: Prepare repository for 0.46-DEV 08d494cc3 releaser: Add release notes to /docs for release of 0.45 ad546ba45 releaser: Bump versions for release of 0.45 971c46bb2 Fixed "Sratch" to become "Scratch" on line 44 a28255bf3 Clarify the meaning of .Pages vs .Site.Pages 127aeee09 docs: Update ref, relref, GetPage docs 350d674ec resources.Concat doesn't have an alias 1fd1219b0 docs: Document refLinksErrorLevel and refLinksNotFoundURL af2252ff6 Merge commit 'a3535c8486b2ce762b1a8a9c30b03985c3e02cee' a11486805 Merge commit 'b6b37a1f00f808f3c0d2715f65ca2d3091f36495' 1c8896cb1 Fix addkit link to account for i18n 468aef3fc releaser: Prepare repository for 0.45-DEV c6f4b97a2 releaser: Add release notes to /docs for release of 0.44 d3985afb7 releaser: Bump versions for release of 0.44 2c59a330c Adjust release notes 83966769a releaser: Prepare repository for 0.44-DEV e539613f7 releaser: Add release notes to /docs for release of 0.43 2bf648944 releaser: Bump versions for release of 0.43 d9d6e4bf7 Fix typos d6798afda Merge commit '98293eaa1570b5aff4452021c8b6d6c8560b3f06' 37cc52261 Add a newScratch template func 1f7f09613 Merge branch 'release-0.42.2' 857b0b26a releaser: Prepare repository for 0.43-DEV git-subtree-dir: docs git-subtree-split: 81847981f1f2cb1ebc83d42d275a2afb2bb22df1
88 lines
2.9 KiB
Markdown
88 lines
2.9 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` shortcode resolves the absolute or relative permalink given a path to a document.
|
||
|
||
## Use `ref` and `relref`
|
||
|
||
```go-html-template
|
||
{{</* ref "document.md" */>}}
|
||
{{</* ref "#anchor" */>}}
|
||
{{</* ref "document.md#anchor" */>}}
|
||
{{</* ref "/blog/my-post" */>}}
|
||
{{</* ref "/blog/my-post.md" */>}}
|
||
{{</* relref "document.md" */>}}
|
||
{{</* relref "#anchor" */>}}
|
||
{{</* relref "document.md#anchor" */>}}
|
||
```
|
||
|
||
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. Hugo is flexible in how we search for documents, so the file suffix may be omitted.
|
||
|
||
**Paths without a leading `/` will first be tried resolved relative to the current page.**
|
||
|
||
You will get an error if you document could not be uniquely resolved. The error behaviour can be configured, see below.
|
||
|
||
### Link to another language version
|
||
|
||
Link to another language version of a document, you need to use this syntax:
|
||
|
||
```go-html-template
|
||
{{</* relref path="document.md" lang="jp" */>}}
|
||
```
|
||
|
||
### Get another Output Format
|
||
|
||
To link to a given Output Format of a document, you can use this syntax:
|
||
|
||
```go-html-template
|
||
{{</* relref path="document.md" outputFormat="rss" */>}}
|
||
```
|
||
|
||
### Anchors
|
||
|
||
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:
|
||
|
||
```go-html-template
|
||
{{</* relref "#anchors" */>}} => #anchors:9decaf7
|
||
```
|
||
|
||
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
|
||
|
||
```go-html-template
|
||
{{</* relref "#who" */>}} => #who:9decaf7
|
||
{{</* relref "/blog/post.md#who" */>}} => /blog/post/#who:badcafe
|
||
```
|
||
|
||
More information about document unique identifiers and headings can be found [below]({{< ref "#hugo-heading-anchors" >}}).
|
||
|
||
|
||
## Ref and RelRef Configuration
|
||
|
||
The behaviour 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 logg 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
|