diff options
Diffstat (limited to 'docs/content/en/functions/urls/Ref.md')
| -rw-r--r-- | docs/content/en/functions/urls/Ref.md | 48 |
1 files changed, 31 insertions, 17 deletions
diff --git a/docs/content/en/functions/urls/Ref.md b/docs/content/en/functions/urls/Ref.md index 908fd6ca8..6cd97f030 100644 --- a/docs/content/en/functions/urls/Ref.md +++ b/docs/content/en/functions/urls/Ref.md @@ -1,26 +1,24 @@ --- title: urls.Ref -linkTitle: ref -description: Returns the absolute permalink to a page. -categories: [functions] +description: Returns the absolute permalink to a page at the given path. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [ref] - returnType: template.HTML - signatures: [urls.Ref . PAGE] -relatedFunctions: - - urls.Ref - - urls.RelRef + related: + - functions/urls/RelRef + - methods/page/Ref + - methods/page/RelRef + returnType: string + signatures: + - urls.Ref PAGE PATH + - urls.Ref PAGE OPTIONS aliases: [/functions/ref] --- -This function takes two arguments: +The first argument is the context of the page from which to resolve relative paths, typically the current page. -- 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. +The second argument is a 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. Alternatively, provide an [options map](#options) instead of a path. ```go-html-template {{ ref . "about" }} @@ -32,6 +30,19 @@ This function takes two arguments: {{ ref . "/blog/my-post.md" }} ``` +## Options + +Instead of specifying a path, you can also provide an options map: + +path +: (`string`) The path to the page, relative to the content directory. Required. + +lang +: (`string`) The language (site) to search for the page. Default is the current language. Optional. + +outputFormat +: (`string`) The output format to search for the page. Default is the current output format. Optional. + To return the absolute permalink to another language version of a page: ```go-html-template @@ -44,6 +55,9 @@ To return the absolute permalink to another Output Format of a page: {{ 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). +By default, Hugo will throw an error and fail the build if it cannot resolve the path. You can change this to a warning in your site configuration, and specify a URL to return when the path cannot be resolved. -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/). +{{< code-toggle file=hugo >}} +refLinksErrorLevel = 'warning' +refLinksNotFoundURL = '/some/other/url' +{{< /code-toggle >}} |