docs: Update permalinks documentation

See #8523
See #10847

diff --git a/docs/content/en/content-management/urls.md b/docs/content/en/content-management/urls.md
index 48de64966ab13eb03dc383faf450e0ef9f3d39ec..25f6f19edeb1aee5a7ee685dbd2f9a88066af761 100644 (file)
--- a/docs/content/en/content-management/urls.md
+++ b/docs/content/en/content-management/urls.md
@@ -89,67 +89,149 @@ If you set both `slug` and `url` in front matter, the `url` value takes preceden
 
 ### Permalinks
 
-In your site configuration, set a URL pattern for regular pages within a top-level section. This is recursive, affecting descendant regular pages.
+In your site configuration, define a URL pattern for each top-level section. Each URL pattern can target a given language and/or [page kind].
 
-{{% note %}}
-The  `permalinks` defined in your site configuration do not apply to section pages. To adjust the URL for section pages, set `url` in front matter.
-{{% /note %}}
+Front matter `url` values override the URL patterns defined in the `permalinks` section of your site configuration.
 
-#### Examples {#permalinks-examples}
+[page kind]: https://gohugo.io/templates/section-templates/#page-kinds
+
+#### Monolingual examples {#permalinks-monolingual-examples}
 
 With this content structure:
 
 ```text
 content/
 ├── posts/
-│   ├── _index.md
-│   ├── post-1.md
-│   └── post-2.md
+│   ├── bash-in-slow-motion.md
+│   └── tls-in-a-nutshell.md
+├── tutorials/
+│   ├── git-for-beginners.md
+│   └── javascript-bundling-with-hugo.md
 └── _index.md
 ```
 
-Create a date-based hierarchy, recursively, for regular pages within the `posts` section:
+Render tutorials under "training", and render the posts under "articles" with a date-base hierarchy:
 
 {{< code-toggle file="hugo" copy=false >}}
-[permalinks]
-  posts = '/posts/:year/:month/:title/'
+[permalinks.page]
+posts = '/articles/:year/:month/:slug/'
+tutorials = '/training/:slug/'
+[permalinks.section]
+posts = '/articles/'
+tutorials = '/training/'
 {{< /code-toggle >}}
 
 The structure of the published site will be:
 
 ```text
 public/
-├── posts/
-│   ├── 2023/
-│   │   └── 03/
-│   │       ├── post-1/
-│   │       │   └── index.html
-│   │       └── post-2/
-│   │           └── index.html
-│   └── index.html
-├── favicon.ico
+├── articles/
+│   ├── 2023/
+│   │   ├── 04/
+│   │   │   └── bash-in-slow-motion/
+│   │   │       └── index.html
+│   │   └── 06/
+│   │       └── tls-in-a-nutshell/
+│   │           └── index.html
+│   └── index.html
+├── training/
+│   ├── git-for-beginners/
+│   │   └── index.html
+│   ├── javascript-bundling-with-hugo/
+│   │   └── index.html
+│   └── index.html
 └── index.html
 ```
 
 To create a date-based hierarchy for regular pages in the content root:
 
 {{< code-toggle file="hugo" copy=false >}}
-[permalinks]
-  '/' = '/:year/:month/:title/'
+[permalinks.page]
+"/" = "/:year/:month/:slug/"
 {{< /code-toggle >}}
 
-{{% note %}}
-A URL pattern defined for the content root is not recursive.
-{{% /note %}}
+Use the same approach with taxonomy terms. For example, to omit the taxonomy segment of the URL:
+
+{{< code-toggle file="hugo" copy=false >}}
+[permalinks.term]
+'tags' = '/:slug/'
+{{< /code-toggle >}}
+
+#### Multilingual example {#permalinks-multilingual-example}
 
-Use the same approach with taxonomies. For example, to omit the taxonomy segment of the URL:
+Use the `permalinks` configuration as a component of your localization strategy.
+
+With this content structure:
+
+```text
+content/
+├── de/
+│   ├── books/
+│   │   ├── les-miserables.md
+│   │   └── the-hunchback-of-notre-dame.md
+│   └── _index.md
+└── en/
+    ├── books/
+    │   ├── les-miserables.md
+    │   └── the-hunchback-of-notre-dame.md
+    └── _index.md
+```
+
+And this site configuration:
 
 {{< code-toggle file="hugo" copy=false >}}
-[permalinks]
-  'tags' = '/:title/'
+defaultContentLanguage = 'en'
+defaultContentLanguageInSubdir = true
+
+[languages.en]
+contentDir = 'content/en'
+languageCode = 'en-US'
+languageDirection = 'ltr'
+languageName = 'English'
+weight = 1
+
+[languages.en.permalinks.page]
+books = "/books/:slug/"
+
+[languages.en.permalinks.section]
+books = "/books/"
+
+[languages.es]
+contentDir = 'content/de'
+languageCode = 'es-ES'
+languageDirection = 'ltr'
+languageName = 'Español'
+weight = 2
+
+[languages.es.permalinks.page]
+books = "/libros/:slug/"
+
+[languages.es.permalinks.section]
+books = "/libros/"
 {{< /code-toggle >}}
 
-Front matter `url` values take precedence over URL patterns defined in `permalinks`.
+The structure of the published site will be:
+
+```text
+public/
+├── en/
+│   ├── books/
+│   │   ├── les-miserables/
+│   │   │   └── index.html
+│   │   ├── the-hunchback-of-notre-dame/
+│   │   │   └── index.html
+│   │   └── index.html
+│   └── index.html
+├── es/
+│   ├── libros/
+│   │   ├── les-miserables/
+│   │   │   └── index.html
+│   │   ├── the-hunchback-of-notre-dame/
+│   │   │   └── index.html
+│   │   └── index.html
+│   └── index.html
+└── index.html
+````
 
 #### Tokens