aboutsummaryrefslogtreecommitdiffhomepage
path: root/docs/content/en/content-management/urls.md
diff options
context:
space:
mode:
Diffstat (limited to 'docs/content/en/content-management/urls.md')
-rw-r--r--docs/content/en/content-management/urls.md61
1 files changed, 49 insertions, 12 deletions
diff --git a/docs/content/en/content-management/urls.md b/docs/content/en/content-management/urls.md
index e3370f956..0f1d93c63 100644
--- a/docs/content/en/content-management/urls.md
+++ b/docs/content/en/content-management/urls.md
@@ -43,11 +43,45 @@ https://example.org/posts/my-first-post/
Set the `url` in front matter to override the entire path. Use this with either regular pages or section pages.
+{{% note %}}
+Hugo does not sanitize the `url` front matter field, allowing you to generate:
+
+- File paths that contain characters reserved by the operating system. For example, file paths on Windows may not contain any of these [reserved characters]. Hugo throws an error if a file path includes a character reserved by the current operating system.
+- URLs that contain disallowed characters. For example, the less than sign (`<`) is not allowed in a URL.
+
+[reserved characters]: https://learn.microsoft.com/en-us/windows/win32/fileio/naming-a-file#naming-conventions
+{{% /note %}}
+
+If you set both `slug` and `url` in front matter, the `url` value takes precedence.
+
+#### Include a colon
+
+{{< new-in 0.136.0 >}}
+
+If you need to include a colon in the `url` front matter field, escape it with backslash characters. Use one backslash if you wrap the string within single quotes, or use two backslashes if you wrap the string within double quotes. With YAML front matter, use a single backslash if you omit quotation marks.
+
+For example, with this front matter:
+
+{{< code-toggle file=content/example.md fm=true >}}
+title: Example
+url: "my\\:example"
+{{< /code-toggle >}}
+
+The resulting URL will be:
+
+```text
+https://example.org/my:example/
+```
+
+As described above, this will fail on Windows because the colon (`:`) is a reserved character.
+
+#### File extensions
+
With this front matter:
{{< code-toggle file=content/posts/post-1.md fm=true >}}
title = 'My First Article'
-url = '/articles/my-first-article'
+url = 'articles/my-first-article'
{{< /code-toggle >}}
The resulting URL will be:
@@ -60,7 +94,7 @@ If you include a file extension:
{{< code-toggle file=content/posts/post-1.md fm=true >}}
title = 'My First Article'
-url = '/articles/my-first-article.html'
+url = 'articles/my-first-article.html'
{{< /code-toggle >}}
The resulting URL will be:
@@ -69,12 +103,11 @@ The resulting URL will be:
https://example.org/articles/my-first-article.html
```
-In a monolingual site, a `url` value with or without a leading slash is relative to the `baseURL`.
+#### Leading slashes
-In a multilingual site:
+With monolingual sites, `url` values with or without a leading slash are relative to the [`baseURL`]. With multilingual sites, `url` values with a leading slash are relative to the `baseURL`, and `url` values without a leading slash are relative to the `baseURL` plus the language prefix.
-- A `url` value with a leading slash is relative to the `baseURL`.
-- A `url` value without a leading slash is relative to the `baseURL` plus the language prefix.
+[`baseURL`]: /getting-started/configuration/#baseurl
Site type|Front matter `url`|Resulting URL
:--|:--|:--
@@ -83,13 +116,11 @@ monolingual|`about`|`https://example.org/about/`
multilingual|`/about`|`https://example.org/about/`
multilingual|`about`|`https://example.org/de/about/`
-If you set both `slug` and `url` in front matter, the `url` value takes precedence.
-
#### Permalinks tokens in front matter
{{< new-in "0.131.0" >}}
-You can also use [Permalinks tokens](#tokens) in the `url` front matter. This is typically used in `cascade` sections:
+You can also use [tokens](#tokens) when setting the `url` value. This is typically used in `cascade` sections:
{{< code-toggle file=content/foo/bar/_index.md fm=true >}}
title ="Bar"
@@ -246,9 +277,7 @@ public/
#### Tokens
-Use these tokens when defining the URL pattern. These can both be used in the `permalinks` configuration and in the front matter [url](#permalinks-tokens-in-front-matter).
-
-`:filename`
+Use these tokens when defining the URL pattern. You can also use these tokens when setting the [`url`](#permalinks-tokens-in-front-matter) value in front matter.
`:year`
: The 4-digit year as defined in the front matter `date` field.
@@ -313,6 +342,14 @@ By default, Hugo produces pretty URLs. To generate ugly URLs, change your site c
uglyURLs = true
{{< /code-toggle >}}
+You can also enable uglyURLs by section. For example, with a site that contains sections for books and films:
+
+{{< code-toggle file=hugo >}}
+[uglyURLs]
+books = true
+films = false
+{{< /code-toggle >}}
+
### Post-processing
Hugo provides two mutually exclusive configuration options to alter URLs _after_ it renders a page.