Merge commit '8b9803425e63e1b1801f8d5d676e96368d706722'

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

@@ -20,48 +20,44 @@ Use this function with both monolingual and multilingual configurations. The URL
 - The `baseURL` in site configuration
 - The language prefix, if any
 
-In examples that follow, the project is multilingual with content in both Español (`es`) and English (`en`). The default language is Español. The returned values are from the English site.
+In examples that follow, the project is multilingual with content in both English (`en`) and Spanish (`es`). The returned values are from the English site.
 
 ### Input does not begin with a slash
 
-If the input does not begin with a slash, the resulting URL will be correct regardless of the `baseURL`.
+If the input does not begin with a slash, the path in the resulting URL will be relative to the `baseURL` in your site configuration.
 
 With `baseURL = https://example.org/`
 
 ```go-html-template
-{{ absLangURL "" }}           →   https://example.org/en/
-{{ absLangURL "articles" }}   →   https://example.org/en/articles
-{{ absLangURL "style.css" }}  →   https://example.org/en/style.css
+{{ absLangURL "" }}          → https://example.org/en/
+{{ absLangURL "articles" }}  → https://example.org/en/articles
+{{ absLangURL "style.css" }} → https://example.org/en/style.css
 ```
 
 With `baseURL = https://example.org/docs/`
 
 ```go-html-template
-{{ absLangURL "" }}           →   https://example.org/docs/en/
-{{ absLangURL "articles" }}   →   https://example.org/docs/en/articles
-{{ absLangURL "style.css" }}  →   https://example.org/docs/en/style.css
+{{ absLangURL "" }}          → https://example.org/docs/en/
+{{ absLangURL "articles" }}  → https://example.org/docs/en/articles
+{{ absLangURL "style.css" }} → https://example.org/docs/en/style.css
 ```
 
 ### Input begins with a slash
 
-If the input begins with a slash, the resulting URL will be incorrect when the `baseURL` includes a subdirectory. With a leading slash, the function returns a URL relative to the protocol+host section of the `baseURL`.
+If the input begins with a slash, the path in the resulting URL will be relative to the protocol+host of the `baseURL` in your site configuration.
 
 With `baseURL = https://example.org/`
 
 ```go-html-template
-{{ absLangURL "/" }}          →   https://example.org/en/
-{{ absLangURL "/articles" }}  →   https://example.org/en/articles
-{{ absLangURL "/style.css" }} →   https://example.org/en/style.css
+{{ absLangURL "/" }}          → https://example.org/en/
+{{ absLangURL "/articles" }}  → https://example.org/en/articles
+{{ absLangURL "/style.css" }} → https://example.org/en/style.css
 ```
 
 With `baseURL = https://example.org/docs/`
 
 ```go-html-template
-{{ absLangURL "/" }}          →   https://example.org/en/
-{{ absLangURL "/articles" }}  →   https://example.org/en/articles
-{{ absLangURL "/style.css" }} →   https://example.org/en/style.css
+{{ absLangURL "/" }}          → https://example.org/en/
+{{ absLangURL "/articles" }}  → https://example.org/en/articles
+{{ absLangURL "/style.css" }} → https://example.org/en/style.css
 ```
-
-{{% note %}}
-The last three examples are not desirable in most situations. As a best practice, never include a leading slash when using this function.
-{{% /note %}}

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

@@ -14,53 +14,49 @@ action:
 aliases: [/functions/absurl]
 ---
 
-With multilingual configurations, use the [`absLangURL`] function instead. The URL returned by this function depends on:
+With multilingual configurations, use the [`urls.AbsLangURL`] function instead. The URL returned by this function depends on:
 
 - Whether the input begins with a slash
 - The `baseURL` in site configuration
 
 ### Input does not begin with a slash
 
-If the input does not begin with a slash, the resulting URL will be correct regardless of the `baseURL`.
+If the input does not begin with a slash, the path in the resulting URL will be relative to the `baseURL` in your site configuration.
 
 With `baseURL = https://example.org/`
 
 ```go-html-template
-{{ absURL "" }}           →   https://example.org/
-{{ absURL "articles" }}   →   https://example.org/articles
-{{ absURL "style.css" }}  →   https://example.org/style.css
+{{ absURL "" }}          → https://example.org/
+{{ absURL "articles" }}  → https://example.org/articles
+{{ absURL "style.css" }} → https://example.org/style.css
 ```
 
 With `baseURL = https://example.org/docs/`
 
 ```go-html-template
-{{ absURL "" }}           →   https://example.org/docs/
-{{ absURL "articles" }}   →   https://example.org/docs/articles
-{{ absURL "style.css" }}  →   https://example.org/docs/style.css
+{{ absURL "" }}          → https://example.org/docs/
+{{ absURL "articles" }}  → https://example.org/docs/articles
+{{ absURL "style.css" }} → https://example.org/docs/style.css
 ```
 
 #### Input begins with a slash
 
-If the input begins with a slash, the resulting URL will be incorrect when the `baseURL` includes a subdirectory. With a leading slash, the function returns a URL relative to the protocol+host section of the `baseURL`.
+If the input begins with a slash, the path in the resulting URL will be relative to the protocol+host of the `baseURL` in your site configuration.
 
 With `baseURL = https://example.org/`
 
 ```go-html-template
-{{ absURL "/" }}          →   https://example.org/
-{{ absURL "/articles" }}  →   https://example.org/articles
-{{ absURL "/style.css" }} →   https://example.org/style.css
+{{ absURL "/" }}          → https://example.org/
+{{ absURL "/articles" }}  → https://example.org/articles
+{{ absURL "/style.css" }} → https://example.org/style.css
 ```
 
 With `baseURL = https://example.org/docs/`
 
 ```go-html-template
-{{ absURL "/" }}          →   https://example.org/
-{{ absURL "/articles" }}  →   https://example.org/articles
-{{ absURL "/style.css" }} →   https://example.org/style.css
+{{ absURL "/" }}          → https://example.org/
+{{ absURL "/articles" }}  → https://example.org/articles
+{{ absURL "/style.css" }} → https://example.org/style.css
 ```
 
-{{% note %}}
-The last three examples are not desirable in most situations. As a best practice, never include a leading slash when using this function.
-{{% /note %}}
-
-[`absLangURL`]: /functions/urls/abslangurl/
+[`urls.AbsLangURL`]: /functions/urls/abslangurl/

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

@@ -16,14 +16,14 @@ aliases: [/functions/anchorize]
 
 ## Sanitizing logic
 
-With the default markdown renderer, Goldmark, the sanitizing logic is controlled by your site configuration:
+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.
+This controls the behavior of the `anchorize` function and the generation of heading IDs when rendering Markdown to HTML.
 
 Set `autoHeadingIDType` to one of:
 

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

@@ -27,4 +27,4 @@ aliases: [/functions/urls.joinpath]
 
 Unlike the [`path.Join`] function, `urls.JoinPath` retains consecutive leading slashes.
 
-[`path.Join`]: /functions/path/join
+[`path.Join`]: /functions/path/join/

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

@@ -19,6 +19,7 @@ The `urls.Parse` function parses a URL into a [URL structure](https://godoc.org/
 {{ $url := "https://example.org:123/foo?a=6&b=7#bar" }}
 {{ $u := urls.Parse $url }}
 
+{{ $u.String }} → https://example.org:123/foo?a=6&b=7#bar
 {{ $u.IsAbs }} → true
 {{ $u.Scheme }} → https
 {{ $u.Host }} → example.org:123

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

@@ -17,51 +17,49 @@ aliases: [/functions/rellangurl]
 Use this function with both monolingual and multilingual configurations. The URL returned by this function depends on:
 
 - Whether the input begins with a slash
-- The `baseURL` in site configuration
+- The `baseURL` in your site configuration
 - The language prefix, if any
 
-In examples that follow, the project is multilingual with content in both Español (`es`) and English (`en`). The default language is Español. The returned values are from the English site.
+In examples that follow, the project is multilingual with content in both English (`en`) and Spanish (`es`). The returned values are from the English site.
 
 ### Input does not begin with a slash
 
-If the input does not begin with a slash, the resulting URL will be correct regardless of the `baseURL`.
+If the input does not begin with a slash, the resulting URL will be relative to the `baseURL` in your site configuration.
 
 With `baseURL = https://example.org/`
 
 ```go-html-template
-{{ relLangURL "" }}           →   /en/
-{{ relLangURL "articles" }}   →   /en/articles
-{{ relLangURL "style.css" }}  →   /en/style.css
+{{ relLangURL "" }}                        → /en/
+{{ relLangURL "articles" }}                → /en/articles
+{{ relLangURL "style.css" }}               → /en/style.css
+{{ relLangURL "https://example.org/foo" }} → /en/foo
 ```
 
 With `baseURL = https://example.org/docs/`
 
 ```go-html-template
-{{ relLangURL "" }}           →   /docs/en/
-{{ relLangURL "articles" }}   →   /docs/en/articles
-{{ relLangURL "style.css" }}  →   /docs/en/style.css
+{{ relLangURL "" }}                             → /docs/en/
+{{ relLangURL "articles" }}                     → /docs/en/articles
+{{ relLangURL "style.css" }}                    → /docs/en/style.css
+{{ relLangURL "https://example.org/docs/foo" }} → /docs/en/foo
 ```
 
 #### Input begins with a slash
 
-If the input begins with a slash, the resulting URL will be incorrect when the `baseURL` includes a subdirectory. With a leading slash, the function returns a URL relative to the protocol+host section of the `baseURL`.
+If the input begins with a slash, the resulting URL will be relative to the protocol+host of the `baseURL` in your site configuration.
 
 With `baseURL = https://example.org/`
 
 ```go-html-template
-{{ relLangURL "/" }}          →   /en/
-{{ relLangURL "/articles" }}  →   /en/articles
-{{ relLangURL "/style.css" }} →   /en/style.css
+{{ relLangURL "/" }}          → /en/
+{{ relLangURL "/articles" }}  → /en/articles
+{{ relLangURL "/style.css" }} → /en/style.css
 ```
 
 With `baseURL = https://example.org/docs/`
 
 ```go-html-template
-{{ relLangURL "/" }}          →   /en/
-{{ relLangURL "/articles" }}  →   /en/articles
-{{ relLangURL "/style.css" }} →   /en/style.css
+{{ relLangURL "/" }}          → /en/
+{{ relLangURL "/articles" }}  → /en/articles
+{{ relLangURL "/style.css" }} → /en/style.css
 ```
-
-{{% note %}}
-The last three examples are not desirable in most situations. As a best practice, never include a leading slash when using this function.
-{{% /note %}}

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

@@ -14,53 +14,51 @@ action:
 aliases: [/functions/relurl]
 ---
 
-With multilingual configurations, use the [`relLangURL`] function instead. The URL returned by this function depends on:
+With multilingual configurations, use the [`urls.RelLangURL`] function instead. The URL returned by this function depends on:
 
 - Whether the input begins with a slash
-- The `baseURL` in site configuration
+- The `baseURL` in your site configuration
 
 ### Input does not begin with a slash
 
-If the input does not begin with a slash, the resulting URL will be correct regardless of the `baseURL`.
+If the input does not begin with a slash, the resulting URL will be relative to the `baseURL` in your site configuration.
 
 With `baseURL = https://example.org/`
 
 ```go-html-template
-{{ relURL "" }}           →   /
-{{ relURL "articles" }}   →   /articles
-{{ relURL "style.css" }}  →   /style.css
+{{ relURL "" }}                        → /
+{{ relURL "articles" }}                → /articles
+{{ relURL "style.css" }}               → /style.css
+{{ relURL "https://example.org/foo" }} → /foo
 ```
 
 With `baseURL = https://example.org/docs/`
 
 ```go-html-template
-{{ relURL "" }}           →   /docs/
-{{ relURL "articles" }}   →   /docs/articles
-{{ relURL "style.css" }}  →   /docs/style.css
+{{ relURL "" }}                             → /docs/
+{{ relURL "articles" }}                     → /docs/articles
+{{ relURL "style.css" }}                    → /docs/style.css
+{{ relURL "https://example.org/docs/foo" }} → /docs/foo
 ```
 
 #### Input begins with a slash
 
-If the input begins with a slash, the resulting URL will be incorrect when the `baseURL` includes a subdirectory. With a leading slash, the function returns a URL relative to the protocol+host section of the `baseURL`.
+If the input begins with a slash, the resulting URL will be relative to the protocol+host of the `baseURL` in your site configuration.
 
 With `baseURL = https://example.org/`
 
 ```go-html-template
-{{ relURL "/" }}          →   /
-{{ relURL "/articles" }}  →   /articles
-{{ relURL "style.css" }}  →   /style.css
+{{ relURL "/" }}          → /
+{{ relURL "/articles" }}  → /articles
+{{ relURL "/style.css" }} → /style.css
 ```
 
 With `baseURL = https://example.org/docs/`
 
 ```go-html-template
-{{ relURL "/" }}          →   /
-{{ relURL "/articles" }}  →   /articles
-{{ relURL "/style.css" }} →   /style.css
+{{ relURL "/" }}          → /
+{{ relURL "/articles" }}  → /articles
+{{ relURL "/style.css" }} → /style.css
 ```
 
-{{% note %}}
-The last three examples are not desirable in most situations. As a best practice, never include a leading slash when using this function.
-{{% /note %}}
-
-[`relLangURL`]: /functions/urls/rellangurl/
+[`urls.RelLangURL`]: /functions/urls/rellangurl/

docs/content/en/functions/urls/_common/_index.md

@@ -7,7 +7,7 @@ cascade:
 ---
 
 <!--
-Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
+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. 
 -->

docs/content/en/functions/urls/_common/anchorize-vs-urlize.md

@@ -4,8 +4,8 @@
 
 The [`anchorize`] and [`urlize`] functions are similar: 
 
-[`anchorize`]: /functions/urls/anchorize
-[`urlize`]: /functions/urls/urlize
+[`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