Merge commit '5be51ac3db225d5df501ed1fa1499c41d97dbf65'

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

@@ -1,63 +1,46 @@
 ---
 title: urls.Ref
-description: Returns the absolute permalink to a page at the given path.
+description: Returns the absolute URL of the page with the given path, language, and output format.
 categories: []
 keywords: []
-action:
-  aliases: [ref]
-  related:
-    - functions/urls/RelRef
-    - methods/page/Ref
-    - methods/page/RelRef
-  returnType: string
-  signatures:
-    - urls.Ref PAGE PATH
-    - urls.Ref PAGE OPTIONS
+params:
+  functions_and_methods:
+    aliases: [ref]
+    returnType: string
+    signatures:
+      - urls.Ref PAGE PATH
+      - urls.Ref PAGE OPTIONS
 aliases: [/functions/ref]
 ---
 
-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.
+The `ref` function takes two arguments:
 
-```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" }}
-```
+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 absolute 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
-{{ ref . (dict "path" "about.md" "lang" "fr") }}
+{{ ref . "/books/book-1" }} → https://example.org/en/books/book-1/
+
+{{ $opts := dict "path" "/books/book-1" }}
+{{ ref . $opts }} → https://example.org/en/books/book-1/
+
+{{ $opts := dict "path" "/books/book-1" "lang" "de" }}
+{{ ref . $opts }} → https://example.org/de/books/book-1/
+
+{{ $opts := dict "path" "/books/book-1" "lang" "de" "outputFormat" "json" }}
+{{ ref . $opts }} → https://example.org/de/books/book-1/index.json
 ```
 
-To return the absolute permalink to another Output Format of a page:
+## Error handling
 
-```go-html-template
-{{ ref . (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" %}}