diff options
author | Joe Mooring <joe.mooring@veriphor.com> | 2023-06-26 12:22:55 -0700 |
---|---|---|
committer | Bjørn Erik Pedersen <bjorn.erik.pedersen@gmail.com> | 2023-06-27 11:04:49 +0200 |
commit | 12e4c4d5dc7cdb700a6b4f341171a8361e2faa7b (patch) | |
tree | 9677ca3d48705340107e2df79e52be68627d6996 | |
parent | bac03f40763e8b506d577e825d51df6b9a4c3f06 (diff) |
docs: Update permalinks documentation
See #8523
See #10847
-rw-r--r-- | docs/content/en/content-management/urls.md | 140 |
1 files changed, 111 insertions, 29 deletions
diff --git a/docs/content/en/content-management/urls.md b/docs/content/en/content-management/urls.md index 48de64966..25f6f19ed 100644 --- 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 |