diff --git a/content/en/content-management/urls.md b/content/en/content-management/urls.md index 0d67edb262..c6ecd21ad3 100644 --- a/content/en/content-management/urls.md +++ b/content/en/content-management/urls.md @@ -43,11 +43,30 @@ 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, a file path on Windows may not contain a colon (`:`). Hugo throws an error if you include reserved characters. Learn more about [Windows file naming conventions]. +- URLs that contain disallowed characters. For example, the less than sign (`<`) is not allowed in a URL. + +[Windows file naming conventions]: 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. 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 +79,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 +88,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`. +#### Multilingual istes -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,8 +101,6 @@ 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" >}}