13 files changed, 245 insertions, 183 deletions
diff --git a/docs/content/en/functions/urls/AbsLangURL.md b/docs/content/en/functions/urls/AbsLangURL.md
index ad73bbff0..876552bb7 100644
--- a/docs/content/en/functions/urls/AbsLangURL.md
+++ b/docs/content/en/functions/urls/AbsLangURL.md
@@ -1,21 +1,16 @@
 ---
 title: urls.AbsLangURL
-linkTitle: absLangURL
 description: Returns an absolute URL with a language prefix, if any.
-categories: [functions]
+categories: []
 keywords: []
-menu:
-  docs:
-    parent: functions
-function:
+action:
   aliases: [absLangURL]
-  returnType: template.HTML
+  related:
+    - functions/urls/AbsURL 
+    - functions/urls/RelLangURL
+    - functions/urls/RelURL
+  returnType: string
   signatures: [urls.AbsLangURL INPUT]
-relatedFunctions:
-  - urls.AbsLangURL
-  - urls.AbsURL 
-  - urls.RelLangURL
-  - urls.RelURL
 aliases: [/functions/abslangurl]
 ---
 
diff --git a/docs/content/en/functions/urls/AbsURL.md b/docs/content/en/functions/urls/AbsURL.md
index bb6816f57..5b027ae84 100644
--- a/docs/content/en/functions/urls/AbsURL.md
+++ b/docs/content/en/functions/urls/AbsURL.md
@@ -1,25 +1,20 @@
 ---
 title: urls.AbsURL 
-linkTitle: absURL
 description: Returns an absolute URL.
-categories: [functions]
+categories: []
 keywords: []
-menu:
-  docs:
-    parent: functions
-function:
+action:
   aliases: [absURL]
-  returnType: template.html
+  related:
+    - functions/urls/AbsLangURL
+    - functions/urls/RelLangURL
+    - functions/urls/RelURL
+  returnType: string
   signatures: [urls.AbsURL INPUT]
-relatedFunctions:
-  - urls.AbsLangURL
-  - urls.AbsURL 
-  - urls.RelLangURL
-  - urls.RelURL
 aliases: [/functions/absurl]
 ---
 
-With multilingual configurations, use the [`absLangURL`] function instead.  The URL returned by this function depends on:
+With multilingual configurations, use the [`absLangURL`] function instead. The URL returned by this function depends on:
 
 - Whether the input begins with a slash
 - The `baseURL` in site configuration
diff --git a/docs/content/en/functions/urls/Anchorize.md b/docs/content/en/functions/urls/Anchorize.md
index 15efe9a5e..72b3d54a9 100644
--- a/docs/content/en/functions/urls/Anchorize.md
+++ b/docs/content/en/functions/urls/Anchorize.md
@@ -1,31 +1,37 @@
 ---
 title: urls.Anchorize
-linkTitle: anchorize
-description: Takes a string and sanitizes it the same way as the [`defaultMarkdownHandler`](/getting-started/configuration-markup#default-configuration) does for markdown headers.
-categories: [functions]
+description: Returns the given string, sanitized for usage in an HTML id attribute.
+categories: []
 keywords: []
-menu:
-  docs:
-    parent: functions
-function:
+action:
   aliases: [anchorize]
+  related:
+    - functions/urls/URLize
   returnType: string
   signatures: [urls.Anchorize INPUT]
-relatedFunctions:
-  - urls.Anchorize
-  - urls.URLize
 aliases: [/functions/anchorize]
 ---
 
-If [Goldmark](/getting-started/configuration-markup#goldmark) is set as `defaultMarkdownHandler`, the sanitizing logic adheres to the setting [`markup.goldmark.parser.autoHeadingIDType`](/getting-started/configuration-markup#goldmark).
+{{% include "/functions/urls/_common/anchorize-vs-urlize.md" %}}
 
-Since the `defaultMarkdownHandler` and this template function use the same sanitizing logic, you can use the latter to determine the ID of a header for linking with anchor tags.
+## Sanitizing logic
 
-```go-html-template
-{{ anchorize "This is a header" }} → "this-is-a-header"
-{{ anchorize "This is also    a header" }} → "this-is-also----a-header"
-{{ anchorize "main.go" }} → "maingo"
-{{ anchorize "Article 123" }} → "article-123"
-{{ anchorize "<- Let's try this, shall we?" }} → "--lets-try-this-shall-we"
-{{ anchorize "Hello, 世界" }} → "hello-世界"
-```
+With the default markdown renderer, Goldmark, the sanitizing logic is controlled by your site configuration:
+
+{{< code-toggle file=hugo >}}
+[markup.goldmark.parser]
+autoHeadingIDType = 'github'
+{{< /code-toggle >}}
+
+This controls the behavior of the `anchorize` function and the generation of heading IDs when rendering markdown to HTML.
+
+Set `autoHeadingIDType` to one of:
+
+github
+: Compatible with GitHub. This is the default, and strongly recommended.
+
+github-ascii
+: Similar to the "github" setting, but removes non-ASCII characters. 
+
+blackfriday
+: Provided for backwards compatibility with Hugo v0.59.1 and earlier. This option will be removed in a future release.
diff --git a/docs/content/en/functions/urls/JoinPath.md b/docs/content/en/functions/urls/JoinPath.md
index 41adf7ee7..7acecb506 100644
--- a/docs/content/en/functions/urls/JoinPath.md
+++ b/docs/content/en/functions/urls/JoinPath.md
@@ -1,30 +1,28 @@
 ---
 title: urls.JoinPath
 description: Joins the provided elements into a URL string and cleans the result of any ./ or ../ elements. If the argument list is empty, JoinPath returns an empty string.
-categories: [functions]
+categories: []
 keywords: []
-menu:
-  docs:
-    parent: functions
-function:
+action:
   aliases: []
+  related:
+    - functions/path/Join
   returnType: string
   signatures: [urls.JoinPath ELEMENT...]
-relatedFunctions:
-  - path.Join
-  - urls.JoinPath
 aliases: [/functions/urls.joinpath]
 ---
 
+{{< new-in 0.112.0 >}}
+
 ```go-html-template
-{{ urls.JoinPath }} → ""
-{{ urls.JoinPath "" }} → "/"
-{{ urls.JoinPath "a" }} → "a"
-{{ urls.JoinPath "a" "b" }} → "a/b"
-{{ urls.JoinPath "/a" "b" }} → "/a/b"
-{{ urls.JoinPath "https://example.org" "b" }} → "https://example.org/b"
+{{ urls.JoinPath }} → "" (empty string)
+{{ urls.JoinPath "" }} → /
+{{ urls.JoinPath "a" }} → a
+{{ urls.JoinPath "a" "b" }} → a/b
+{{ urls.JoinPath "/a" "b" }} → /a/b
+{{ urls.JoinPath "https://example.org" "b" }} → https://example.org/b
 
-{{ urls.JoinPath (slice "a" "b") }} → "a/b"
+{{ urls.JoinPath (slice "a" "b") }} → a/b
 ```
 
 Unlike the [`path.Join`] function, `urls.JoinPath` retains consecutive leading slashes.
diff --git a/docs/content/en/functions/urls/Parse.md b/docs/content/en/functions/urls/Parse.md
index 17c924d51..2eb4eeadf 100644
--- a/docs/content/en/functions/urls/Parse.md
+++ b/docs/content/en/functions/urls/Parse.md
@@ -1,16 +1,13 @@
 ---
 title: urls.Parse
 description: Parses a URL into a URL structure.
-categories: [functions]
+categories: []
 keywords: []
-menu:
-  docs:
-    parent: functions
-function:
+action:
   aliases: []
-  returnType: URL
+  related: []
+  returnType: url.URL
   signatures: [urls.Parse URL]
-relatedFunctions: []
 aliases: [/functions/urls.parse]
 ---
 
@@ -18,7 +15,6 @@ The `urls.Parse` function parses a URL into a [URL structure](https://godoc.org/
 
 [scheme]: https://www.iana.org/assignments/uri-schemes/uri-schemes.xhtml#uri-schemes-1
 
-
 ```go-html-template
 {{ $url := "https://example.org:123/foo?a=6&b=7#bar" }}
 {{ $u := urls.Parse $url }}
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 >}}
diff --git a/docs/content/en/functions/urls/RelLangURL.md b/docs/content/en/functions/urls/RelLangURL.md
index b8850c71d..2c1037038 100644
--- a/docs/content/en/functions/urls/RelLangURL.md
+++ b/docs/content/en/functions/urls/RelLangURL.md
@@ -1,21 +1,16 @@
 ---
 title: urls.RelLangURL
-linkTitle: relLangURL
 description: Returns a relative URL with a language prefix, if any.
-categories: [functions]
+categories: []
 keywords: []
-menu:
-  docs:
-    parent: functions
-function:
+action:
   aliases: [relLangURL]
-  returnType: template.HTML
+  related:
+    - functions/urls/AbsLangURL
+    - functions/urls/AbsURL 
+    - functions/urls/RelURL
+  returnType: string
   signatures: [urls.RelLangURL INPUT]
-relatedFunctions:
-  - urls.AbsLangURL
-  - urls.AbsURL 
-  - urls.RelLangURL
-  - urls.RelURL
 aliases: [/functions/rellangurl]
 ---
 
@@ -37,7 +32,7 @@ With `baseURL = https://example.org/`
 {{ relLangURL "" }}           →   /en/
 {{ relLangURL "articles" }}   →   /en/articles
 {{ relLangURL "style.css" }}  →   /en/style.css
-``` 
+```
 
 With `baseURL = https://example.org/docs/`
 
@@ -57,7 +52,7 @@ With `baseURL = https://example.org/`
 {{ relLangURL "/" }}          →   /en/
 {{ relLangURL "/articles" }}  →   /en/articles
 {{ relLangURL "/style.css" }} →   /en/style.css
-``` 
+```
 
 With `baseURL = https://example.org/docs/`
 
diff --git a/docs/content/en/functions/urls/RelRef.md b/docs/content/en/functions/urls/RelRef.md
index 1ff213b70..6b45b2131 100644
--- a/docs/content/en/functions/urls/RelRef.md
+++ b/docs/content/en/functions/urls/RelRef.md
@@ -1,27 +1,25 @@
 ---
 title: urls.RelRef
-linkTitle: relref
-description: Returns the relative permalink to a page.
-categories: [functions]
+description: Returns the relative permalink to a page at the given path.
+categories: []
 keywords: []
-menu:
-  docs:
-    parent: functions
-function:
+action:
   aliases: [relref]
-  returnType: template.HTML
-  signatures: [urls.RelRef . PAGE]
-relatedFunctions:
-  - urls.Ref
-  - urls.RelRef
+  related:
+    - functions/urls/Ref
+    - methods/page/Ref
+    - methods/page/RelRef
+  returnType: string
+  signatures:
+    - urls.RelRef PAGE PATH
+    - urls.RelRef PAGE OPTIONS
 aliases: [/functions/relref]
 ---
 
-This function takes two arguments:
-
-- 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 first argument is the context of the page from which to resolve relative paths, typically the current page.
 
+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" }}
@@ -36,8 +34,21 @@ The permalink returned is relative to the protocol+host portion of the baseURL s
 
 Code|baseURL|Permalink
 :--|:--|:--
-`{{ relref . "/about" }}`|`http://example.org/`|`/about/`
-`{{ relref . "/about" }}`|`http://example.org/x/`|`/x/about/`
+`{{ relref . "/about" }}`|`https://example.org/`|`/about/`
+`{{ relref . "/about" }}`|`https://example.org/x/`|`/x/about/`
+
+## 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 relative permalink to another language version of a page:
 
@@ -51,6 +62,9 @@ To return the relative permalink to another Output Format of a page:
 {{ 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).
+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 [`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/).
+{{< code-toggle file=hugo >}}
+refLinksErrorLevel = 'warning'
+refLinksNotFoundURL = '/some/other/url'
+{{< /code-toggle >}}
diff --git a/docs/content/en/functions/urls/RelURL.md b/docs/content/en/functions/urls/RelURL.md
index fa1f9af73..9320c2827 100644
--- a/docs/content/en/functions/urls/RelURL.md
+++ b/docs/content/en/functions/urls/RelURL.md
@@ -1,21 +1,16 @@
 ---
 title: urls.RelURL
-linkTitle: relURL
 description: Returns a relative URL.
-categories: [functions]
+categories: []
 keywords: []
-menu:
-  docs:
-    parent: functions
-function:
+action:
   aliases: [relURL]
-  returnType: template.HTML
+  related:
+    - functions/urls/AbsLangURL
+    - functions/urls/AbsURL 
+    - functions/urls/RelLangURL
+  returnType: string
   signatures: [urls.RelURL INPUT]
-relatedFunctions:
-  - urls.AbsLangURL
-  - urls.AbsURL 
-  - urls.RelLangURL
-  - urls.RelURL
 aliases: [/functions/relurl]
 ---
 
diff --git a/docs/content/en/functions/urls/URLize.md b/docs/content/en/functions/urls/URLize.md
index 3c80a92f8..bf44a82d1 100644
--- a/docs/content/en/functions/urls/URLize.md
+++ b/docs/content/en/functions/urls/URLize.md
@@ -1,69 +1,63 @@
 ---
 title: urls.URLize
-linkTitle: urlize
-description: Takes a string, sanitizes it for usage in URLs, and converts spaces to hyphens.
-categories: [functions]
+description: Returns the given string, sanitized for usage in a URL.
+categories: []
 keywords: []
-menu:
-  docs:
-    parent: functions
-function:
+action:
   aliases: [urlize]
+  related:
+    - functions/urls/Anchorize
   returnType: string
   signatures: [urls.URLize INPUT]
-relatedFunctions:
-  - urls.Anchorize
-  - urls.URLize
 aliases: [/functions/urlize]
 ---
 
-The following examples pull from a content file with the following front matter:
+{{% include "/functions/urls/_common/anchorize-vs-urlize.md" %}}
 
-{{< code-toggle file="content/blog/greatest-city.md" fm=true copy=false >}}
-title = "The World's Greatest City"
-location = "Chicago IL"
-tags = ["pizza","beer","hot dogs"]
+## Example
+
+Use the `urlize` function to create a link to a [term] page.
+
+Consider this site configuration:
+
+{{< code-toggle file=hugo >}}
+[taxonomies]
+author = 'authors'
+{{< /code-toggle >}}
+
+And this front matter:
+
+{{< code-toggle file=content/books/les-miserables.md fm=true >}}
+title = 'Les Misérables'
+authors = ['Victor Hugo']
 {{< /code-toggle >}}
 
-The following might be used as a partial within a [single page template][singletemplate]:
+The published site will have this structure:
 
-{{< code file="layouts/partials/content-header.html" >}}
-<header>
-  <h1>{{ .Title }}</h1>
-  {{ with .Params.location }}
-    <div><a href="/locations/{{ . | urlize }}">{{ . }}</a></div>
-  {{ end }}
-  <!-- Creates a list of tags for the content and links to each of their pages -->
-  {{ with .Params.tags }}
-    <ul>
-      {{ range .}}
-        <li>
-          <a href="/tags/{{ . | urlize }}">{{ . }}</a>
-        </li>
-      {{ end }}
-    </ul>
-  {{ end }}
-</header>
-{{< /code >}}
+```text
+public/
+├── authors/
+│   ├── victor-hugo/
+│   │   └── index.html
+│   └── index.html
+├── books/
+│   ├── les-miserables/
+│   │   └── index.html
+│   └── index.html
+└── index.html
+```
 
-The preceding partial would then output to the rendered page as follows:
+To create a link to the term page:
 
-```html
-<header>
-  <h1>The World&#39;s Greatest City</h1>
-  <div><a href="/locations/chicago-il">Chicago IL</a></div>
-  <ul>
-    <li>
-      <a href="/tags/pizza">pizza</a>
-    </li>
-    <li>
-      <a href="/tags/beer">beer</a>
-    </li>
-    <li>
-      <a href="/tags/hot-dogs">hot dogs</a>
-    </li>
-  </ul>
-</header>
+```go-html-template
+{{ $taxonomy := "authors" }}
+{{ $term := "Victor Hugo" }}
+{{ with index .Site.Taxonomies $taxonomy (urlize $term) }}
+  <a href="{{ .Page.RelPermalink }}">{{ .Page.LinkTitle }}</a>
+{{ end }}
 ```
 
-[singletemplate]: /templates/single-page-templates/
+To generate a list of term pages associated with a given content page, use the [`GetTerms`] method on a `Page` object.
+
+[`GetTerms`]: /methods/page/getterms/
+[term]: /getting-started/glossary/#term
diff --git a/docs/content/en/functions/urls/_common/_index.md b/docs/content/en/functions/urls/_common/_index.md
new file mode 100644
index 000000000..47d5812fb
--- /dev/null
+++ b/docs/content/en/functions/urls/_common/_index.md
@@ -0,0 +1,13 @@
+---
+cascade:
+  _build:
+    list: never
+    publishResources: false
+    render: never
+---
+
+<!--
+Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
+
+Include the rendered content using the "include" shortcode. 
+-->
diff --git a/docs/content/en/functions/urls/_common/anchorize-vs-urlize.md b/docs/content/en/functions/urls/_common/anchorize-vs-urlize.md
new file mode 100644
index 000000000..0f01bcf78
--- /dev/null
+++ b/docs/content/en/functions/urls/_common/anchorize-vs-urlize.md
@@ -0,0 +1,35 @@
+---
+# Do not remove front matter.
+---
+
+The [`anchorize`] and [`urlize`] functions are similar: 
+
+[`anchorize`]: /functions/urls/anchorize
+[`urlize`]: /functions/urls/urlize
+
+- Use the `anchorize` function to generate an HTML `id` attribute value
+- Use the `urlize` function to sanitize a string for usage in a URL
+
+For example:
+
+```go-html-template
+{{ $s := "A B C" }}
+{{ $s | anchorize }} → a-b-c
+{{ $s | urlize }} → a-b-c
+
+{{ $s := "a b   c" }}
+{{ $s | anchorize }} → a-b---c
+{{ $s | urlize }} → a-b-c
+
+{{ $s := "< a, b, & c >" }}
+{{ $s | anchorize }} → -a-b--c-
+{{ $s | urlize }} → a-b-c
+
+{{ $s := "main.go" }}
+{{ $s | anchorize }} → maingo
+{{ $s | urlize }} → main.go
+
+{{ $s := "Hugö" }}
+{{ $s | anchorize }} → hugö
+{{ $s | urlize }} → hug%C3%B6
+```
diff --git a/docs/content/en/functions/urls/_index.md b/docs/content/en/functions/urls/_index.md
new file mode 100644
index 000000000..5f16feeeb
--- /dev/null
+++ b/docs/content/en/functions/urls/_index.md
@@ -0,0 +1,12 @@
+---
+title: URL functions
+linkTitle: urls
+description: Template functions to work with URLs.
+categories: []
+keywords: []
+menu:
+  docs:
+    parent: functions
+---
+
+Use these functions to work with URLs.