diff options
Diffstat (limited to 'docs/content/en/content-management/cross-references.md')
-rw-r--r-- | docs/content/en/content-management/cross-references.md | 67 |
1 files changed, 46 insertions, 21 deletions
diff --git a/docs/content/en/content-management/cross-references.md b/docs/content/en/content-management/cross-references.md index b5dd8a4c3..00fb2d973 100644 --- a/docs/content/en/content-management/cross-references.md +++ b/docs/content/en/content-management/cross-references.md @@ -1,31 +1,49 @@ --- title: Links and Cross References +linkTitle: 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/] + parent: content-management + weight: 170 toc: true +weight: 170 +aliases: [/extras/crossreferences/] --- The `ref` and `relref` shortcodes display the absolute and relative permalinks to a document, respectively. -## Use `ref` and `relref` +## Use of `ref` and `relref` -```go-html-template -{{</* ref "document" */>}} -{{</* ref "document#anchor" */>}} -{{</* ref "document.md" */>}} -{{</* ref "document.md#anchor" */>}} -{{</* ref "#anchor" */>}} -{{</* ref "/blog/my-post" */>}} +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. + +``` +. +└── content + ├── about + | ├── _index.md + | └── credits.md + ├── pages + | ├── document1.md + | └── document2.md // has anchor #anchor + ├── products + | └── index.md + └── blog + └── my-post.md +``` + +The pages can be referenced as follows: + + +```text +{{</* ref "document2" */>}} // <- From pages/document1.md, relative path +{{</* ref "document2#anchor" */>}} +{{</* ref "document2.md" */>}} +{{</* ref "document2.md#anchor" */>}} +{{</* ref "#anchor" */>}} // <- From pages/document2.md +{{</* ref "/blog/my-post" */>}} // <- From anywhere, absolute path {{</* ref "/blog/my-post.md" */>}} {{</* relref "document" */>}} {{</* relref "document.md" */>}} @@ -33,15 +51,22 @@ The `ref` and `relref` shortcodes display the absolute and relative permalinks t {{</* relref "/blog/my-post.md" */>}} ``` -To generate a hyperlink using `ref` or `relref` in markdown: +index.md can be reference either by its path or by its containing folder without the ending `/`. \_index.md can be referenced only by its containing folder: -```md -[About]({{</* ref "/page/about" */>}} "About Us") +```text +{{</* ref "/about" */>}} // <- References /about/_index.md +{{</* ref "/about/_index" */>}} // Raises REF_NOT_FOUND error +{{</* ref "/about/credits.md" */>}} // <- References /about/credits.md + +{{</* ref "/products" */>}} // <- References /products/index.md +{{</* ref "/products/index" */>}} // <- References /products/index.md ``` -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. +To generate a hyperlink using `ref` or `relref` in markdown: -**Paths without a leading `/` are first resolved relative to the current page, then to the remainder of the site. +```text +[About]({{</* ref "/about" */>}} "About Us") +``` Hugo emits an error or warning if a document cannot be uniquely resolved. The error behavior is configurable; see below. @@ -116,7 +141,7 @@ produces this HTML: The behavior can, since Hugo 0.45, be configured in `config.toml`: -refLinksErrorLevel ("ERROR") +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 |