mirror of
https://github.com/gohugoio/hugo.git
synced 2024-11-14 20:37:55 -05:00
5e078383a7
49809a03 Merge commit '20a631b4964fc0ab9137cce1e41774cbc17de044' 20a631b4 Squashed 'themes/gohugoioTheme/' changes from b8202f539..dafc91ff1 8b58f565 Re-generate CLI docs 4653a724 Add Netlify deployment badge 2d6246bc Remove some deprecated site variables e6777153 Improve Algolia Search Display Styling 1570999f Add missing "." in front of gitlab-ci.yaml example b922ae7d This adds documentation to the new configDir/Environment logic from .53 (#729) 7cff379f Correctly escape multi-word taxonomy terms in example 2dfeeda4 fix typo by removing stray paren 0870bd9a Fix typo in `paginate` description 91e8be85 Fixes https://github.com/gohugoio/hugo/issues/5609 c1db65ec Make the dummy URL more obvious b4589ff0 Fix a link b73dcb9a Consistently use "posts" as section name in examples 7a56abbc Format definitions a9c6fd9b Minor clarification over the last commit 5c86bdc8 Add alternative instructions for Quick Start for non-git users dafe7ee9 Add Visual Studio Code plug-ins 110ed19e Update HUGO_VERSION 2abd031a Update page.md b332f7b9 Update page.md f5a8c9d4 Update static-files.md 6d0c155c Add note about relative protocol URLs a13751ac Theme Warning: Remove note about unquoted URLs 4c8f7d68 Incorporate feedback 6f2b9cf0 Update Creating Themes Warning 40d88d98 Fix ToC example to use binary true/false 4a11f3f1 Fix typo 2dbfc0a4 Fix a typo in taxonomies d63790ef Do not mark UndocumentedFeature issues as stale d7aff095 Regenerate docs.json 71c0826f Update transform.Unmarshal.md git-subtree-dir: docs git-subtree-split: 49809a038b2691637bab7f3f2e385dde654a88b8
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 your 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="ja" */>}}
|
||
```
|
||
|
||
### 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
|