mirror of
https://github.com/gohugoio/hugo.git
synced 2024-11-14 20:37:55 -05:00
c2037f0c9a
acf70cdd9 Update CSS after removing Purge 74c0bb7f2 Remove purge from Webpack, temporarily 397b7284f Merge commit 'ccb1e38f3822e9b5e4fb89a296324daf3400f23b' ccb1e38f3 Squashed 'themes/gohugoioTheme/' changes from 042112e2d..b7853ae70 bca84e914 Fix search box text being invisible in Safari 3f21d0957 FAQ: "this feature is not available in your current Hugo version" d8b318f90 Remove Gulp from Victor Hugo description 09d9b4c24 Update contribute/development.md 4d0f6ba47 Theme Components Support on the Hugo Themes Site (#769) f2ec3f2a6 Fix broken link 404 af82c56c5 config: Remove superflous param 8dc14f563 Update theme total on homepage (#765) 7838fd7e2 Update description of Atlas to reflect new changes 6abab23c6 update: total of hugo themes 1dba24fde Clarify: summaryLength uses words not characters 8c54f45d6 Add missing punctuation d17000481 Remove Hugo Frontend caddy-plugin a7094ae62 remove unneeded meta tags f8b0f31c6 Fix typo in cross references 61781bab9 Fix: use gh shortcode correctly 357bfca43 Update files.md d1d2406cc Updated Hugo convert to clarify for and not .. 86850f3c3 Fix typos in multilingual.md b68d0d892 Fix typo 8cba70e28 Document disableAliases 00e440260 Remove extra whitespace 212d63e4c Update with latest Theme Submission Guidelines (#744) c24ea638f Update frontends.md 942bc1972 Add one more video 2e1e1091d Update the rest of the videos a7dc70f2b Add new installation video 1a78f8487 Hosting on AWS amplify 112420c46 Fix typo f723425e4 Add fireship.io bio to showcase 574f43503 Fixed typo 88e0e0cb7 Release 0.54.0 303edf19e Merge branch 'temp54' c38debebd releaser: Prepare repository for 0.55.0-DEV 5c6c56fa1 releaser: Add release notes to /docs for release of 0.54.0 f86e05950 releaser: Bump versions for release of 0.54.0 6a2684fe4 Add the default cache configuration f75c0125a Merge commit 'f27faf9afd0a8db768a21954b8755f1bf1a14f1b' e440dc6a4 Merge commit '5e078383a787e8b5ec3ba73f05ea4130840afbe2' 981bf53f8 Update _index.md b54aea066 tpl: Fix reflect 41f8af5a6 Merge commit '978856e2ad12d2bcaf37bb9e31f806b30a4c42f4' git-subtree-dir: docs git-subtree-split: acf70cdd9fe2a89413e13db29466e45629372343
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 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
|