Merge commit '5be51ac3db225d5df501ed1fa1499c41d97dbf65'

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

@@ -3,52 +3,66 @@ title: urls.RelLangURL
 description: Returns a relative URL with a language prefix, if any.
 categories: []
 keywords: []
-action:
-  aliases: [relLangURL]
-  related:
-    - functions/urls/AbsLangURL
-    - functions/urls/AbsURL 
-    - functions/urls/RelURL
-  returnType: string
-  signatures: [urls.RelLangURL INPUT]
+params:
+  functions_and_methods:
+    aliases: [relLangURL]
+    returnType: string
+    signatures: [urls.RelLangURL INPUT]
 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
+- Whether the input begins with a slash (`/`)
 - The `baseURL` in your site configuration
 - The language prefix, if any
 
-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.
+This is the site configuration for the examples that follow:
 
-### Input does not begin with a slash
+{{< code-toggle file=hugo >}}
+defaultContentLanguage = 'en'
+defaultContentLanguageInSubdir = true
+[languages.en]
+weight = 1
+[languages.es]
+weight = 2
+{{< /code-toggle >}}
+
+## Input does not begin with a slash
 
 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/`
+When rendering the `en` site with `baseURL = https://example.org/`
 
 ```go-html-template
-{{ relLangURL "" }}                        → /en/
-{{ relLangURL "articles" }}                → /en/articles
-{{ relLangURL "style.css" }}               → /en/style.css
-{{ relLangURL "https://example.org/foo" }} → /en/foo
+{{ relLangURL "" }}                         → /en/
+{{ relLangURL "articles" }}                 → /en/articles
+{{ relLangURL "style.css" }}                → /en/style.css
+{{ relLangURL "https://example.org" }}      → https://example.org
+{{ relLangURL "https://example.org/" }}     → /en
+{{ relLangURL "https://www.example.org" }}  → https://www.example.org
+{{ relLangURL "https://www.example.org/" }} → https://www.example.org/
 ```
 
-With `baseURL = https://example.org/docs/`
+When rendering the `en` site 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 "https://example.org/docs/foo" }} → /docs/en/foo
+{{ relLangURL "" }}                           → /docs/en/
+{{ relLangURL "articles" }}                   → /docs/en/articles
+{{ relLangURL "style.css" }}                  → /docs/en/style.css
+{{ relLangURL "https://example.org" }}        → https://example.org
+{{ relLangURL "https://example.org/" }}       → https://example.org/
+{{ relLangURL "https://example.org/docs" }}   → https://example.org/docs
+{{ relLangURL "https://example.org/docs/" }}  → /docs/en
+{{ relLangURL "https://www.example.org" }}    → https://www.example.org
+{{ relLangURL "https://www.example.org/" }}   → https://www.example.org/
 ```
 
-#### Input begins with a slash
+## Input begins with a slash
 
 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/`
+When rendering the `en` site with `baseURL = https://example.org/`
 
 ```go-html-template
 {{ relLangURL "/" }}          → /en/
@@ -56,10 +70,13 @@ With `baseURL = https://example.org/`
 {{ relLangURL "/style.css" }} → /en/style.css
 ```
 
-With `baseURL = https://example.org/docs/`
+When rendering the `en` site with `baseURL = https://example.org/docs/`
 
 ```go-html-template
 {{ relLangURL "/" }}          → /en/
 {{ relLangURL "/articles" }}  → /en/articles
 {{ relLangURL "/style.css" }} → /en/style.css
 ```
+
+> [!note]
+> As illustrated by the previous example, using a leading slash is rarely desirable and can lead to unexpected outcomes. In nearly all cases, omit the leading slash.