From d50aba8f064a48d000e2e7982268bc7b1db17138 Mon Sep 17 00:00:00 2001 From: Joe Mooring Date: Sat, 5 Sep 2020 10:21:10 -0400 Subject: [PATCH] Revise ref and relref function pages Closes #1212 --- content/en/functions/ref.md | 39 +++++++++++++++++----------- content/en/functions/relref.md | 46 +++++++++++++++++++++++----------- 2 files changed, 57 insertions(+), 28 deletions(-) diff --git a/content/en/functions/ref.md b/content/en/functions/ref.md index feac06c97..0ec249c61 100644 --- a/content/en/functions/ref.md +++ b/content/en/functions/ref.md @@ -1,17 +1,17 @@ --- title: ref linktitle: ref -description: Looks up a content page by logical name. +description: Returns the absolute permalink to a page. godocref: date: 2017-02-01 publishdate: 2017-02-01 -lastmod: 2019-12-28 +lastmod: 2020-09-05 categories: [functions] menu: docs: parent: "functions" keywords: [cross references, anchors] -signature: ["ref . CONTENT"] +signature: ["ref . PAGE"] workson: [] hugoversion: relatedfuncs: [relref] @@ -19,22 +19,33 @@ deprecated: false aliases: [] --- -`ref` and `relref` look up a content page by logical name (`ref`) or relative path (`relref`) to return the permalink: +This function takes two parameters: -``` +- The context of the page from which to resolve relative paths, typically the current page (`.`) +- The path to a page, with or without a file extension, with or without an anchor. A path without a leading `/` is first resolved relative to the given context, then to the remainder of the site. + +```go-html-template +{{ ref . "about" }} +{{ ref . "about#anchor" }} {{ ref . "about.md" }} +{{ ref . "about.md#anchor" }} +{{ ref . "#anchor" }} +{{ ref . "/blog/my-post" }} +{{ ref . "/blog/my-post.md" }} ``` -{{% note "Usage Note" %}} -`ref` looks up Hugo "Regular Pages" only. It can't be used for the homepage, section pages, etc. -{{% /note %}} +To return the absolute permalink to another language version of a page: -It is also possible to pass additional arguments to link to another language or an alternative output format. Therefore, pass a map of arguments instead of just the path. - -``` -{{ ref . (dict "path" "about.md" "lang" "ja" "outputFormat" "rss") }} +```go-html-template +{{ ref . (dict "path" "about.md" "lang" "fr") }} ``` -These functions are used in two of Hugo's built-in shortcodes. You can see basic usage examples of both `ref` and `relref` in the [shortcode documentation](/content-management/shortcodes/#ref-and-relref). +To return the absolute permalink to another Output Format of a page: -For an extensive explanation of how to leverage `ref` and `relref` for content management, see [Cross References](/content-management/cross-references/). +```go-html-template +{{ ref . (dict "path" "about.md" "outputFormat" "rss") }} +``` + +Hugo emits an error or warning if the page cannot be uniquely resolved. The error behavior is configurable; see [Ref and RelRef Configuration](/content-management/cross-references/#ref-and-relref-configuration). + +This function is used by Hugo's built-in [`ref`](/content-management/shortcodes/#ref-and-relref) shortcode. For a detailed explanation of how to leverage this shortcode for content management, see [Links and Cross References](/content-management/cross-references/). diff --git a/content/en/functions/relref.md b/content/en/functions/relref.md index fe5699053..18f65f1f8 100644 --- a/content/en/functions/relref.md +++ b/content/en/functions/relref.md @@ -1,17 +1,17 @@ --- title: relref -# linktitle: relref -description: Looks up a content page by relative path. +linktitle: relref +description: Returns the relative permalink to a page. godocref: date: 2017-02-01 publishdate: 2017-02-01 -lastmod: 2019-12-28 +lastmod: 2020-09-05 categories: [functions] menu: docs: parent: "functions" keywords: [cross references, anchors] -signature: ["relref . CONTENT"] +signature: ["relref . PAGE"] workson: [] hugoversion: relatedfuncs: [ref] @@ -19,22 +19,40 @@ deprecated: false aliases: [] --- -`ref` and `relref` look up a content page by logical name (`ref`) or relative path (`relref`) to return the permalink: +This function takes two parameters: -``` +- The context of the page from which to resolve relative paths, typically the current page (`.`) +- The path to a page, with or without a file extension, with or without an anchor. A path without a leading `/` is first resolved relative to the given context, then to the remainder of the site. + +```go-html-template +{{ relref . "about" }} +{{ relref . "about#anchor" }} {{ relref . "about.md" }} +{{ relref . "about.md#anchor" }} +{{ relref . "#anchor" }} +{{ relref . "/blog/my-post" }} +{{ relref . "/blog/my-post.md" }} ``` -{{% note "Usage Note" %}} -`relref` looks up Hugo "Regular Pages" only. It can't be used for the homepage, section pages, etc. -{{% /note %}} +The permalink returned is relative to the protocol+host portion of the baseURL specified in the site configuration. For example: -It is also possible to pass additional arguments to link to another language or an alternative output format. Therefore, pass a map of arguments instead of just the path. +Code|baseURL|Permalink +:--|:--|:-- +`{{ relref . "/about" }}`|`http://example.org/`|`/about/` +`{{ relref . "/about" }}`|`http://example.org/x/`|`/x/about/` -``` -{{ relref . (dict "path" "about.md" "lang" "ja" "outputFormat" "rss") }} +To return the relative permalink to another language version of a page: + +```go-html-template +{{ relref . (dict "path" "about.md" "lang" "fr") }} ``` -These functions are used in two of Hugo's built-in shortcodes. You can see basic usage examples of both `ref` and `relref` in the [shortcode documentation](/content-management/shortcodes/#ref-and-relref). +To return the relative permalink to another Output Format of a page: -For an extensive explanation of how to leverage `ref` and `relref` for content management, see [Cross References](/content-management/cross-references/). +```go-html-template +{{ relref . (dict "path" "about.md" "outputFormat" "rss") }} +``` + +Hugo emits an error or warning if the page cannot be uniquely resolved. The error behavior is configurable; see [Ref and RelRef Configuration](/content-management/cross-references/#ref-and-relref-configuration). + +This function is used by Hugo's built-in [`relref`](/content-management/shortcodes/#ref-and-relref) shortcode. For a detailed explanation of how to leverage this shortcode for content management, see [Links and Cross References](/content-management/cross-references/).