Merge commit '5be51ac3db225d5df501ed1fa1499c41d97dbf65'

docs/content/en/functions/urls/RelRef.md

@@ -1,70 +1,46 @@
 ---
 title: urls.RelRef
-description: Returns the relative permalink to a page at the given path.
+description: Returns the relative URL of the page with the given path, language, and output format.
 categories: []
 keywords: []
-action:
-  aliases: [relref]
-  related:
-    - functions/urls/Ref
-    - methods/page/Ref
-    - methods/page/RelRef
-  returnType: string
-  signatures:
-    - urls.RelRef PAGE PATH
-    - urls.RelRef PAGE OPTIONS
+params:
+  functions_and_methods:
+    aliases: [relref]
+    returnType: string
+    signatures:
+      - urls.RelRef PAGE PATH
+      - urls.RelRef PAGE OPTIONS
 aliases: [/functions/relref]
 ---
 
-The first argument is the context of the page from which to resolve relative paths, typically the current page.
+## Usage
 
-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
-{{ relref . "about" }}
-{{ relref . "about#anchor" }}
-{{ relref . "about.md" }}
-{{ relref . "about.md#anchor" }}
-{{ relref . "#anchor" }}
-{{ relref . "/blog/my-post" }}
-{{ relref . "/blog/my-post.md" }}
-```
+The `relref` function takes two arguments:
 
-The permalink returned is relative to the protocol+host portion of the baseURL specified in the site configuration. For example:
-
-Code|baseURL|Permalink
-:--|:--|:--
-`{{ relref . "/about" }}`|`https://example.org/`|`/about/`
-`{{ relref . "/about" }}`|`https://example.org/x/`|`/x/about/`
+1. The context for resolving relative paths (typically the current page).
+1. Either the target page's path or an options map (see below).
 
 ## Options
 
-Instead of specifying a path, you can also provide an options map:
+{{% include "_common/ref-and-relref-options.md" %}}
 
-path
-: (`string`) The path to the page, relative to the `content` directory. Required.
+## Examples
 
-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 relative permalink to another language version of a page:
+The following examples show the rendered output for a page on the English version of the site:
 
 ```go-html-template
-{{ relref . (dict "path" "about.md" "lang" "fr") }}
+{{ relref . "/books/book-1" }} → /en/books/book-1/
+
+{{ $opts := dict "path" "/books/book-1" }}
+{{ relref . $opts }} → /en/books/book-1/
+
+{{ $opts := dict "path" "/books/book-1" "lang" "de" }}
+{{ relref . $opts }} → /de/books/book-1/
+
+{{ $opts := dict "path" "/books/book-1" "lang" "de" "outputFormat" "json" }}
+{{ relref . $opts }} → /de/books/book-1/index.json
 ```
 
-To return the relative permalink to another Output Format of a page:
+## Error handling
 
-```go-html-template
-{{ relref . (dict "path" "about.md" "outputFormat" "rss") }}
-```
-
-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.
-
-{{< code-toggle file=hugo >}}
-refLinksErrorLevel = 'warning'
-refLinksNotFoundURL = '/some/other/url'
-{{< /code-toggle >}}
+{{% include "_common/ref-and-relref-error-handling.md" %}}