Skip to content

Commit

Permalink
Update description of url front matter field
Browse files Browse the repository at this point in the history
Advise that the field is not sanitized, and describe how to include a
colon character.

Closes #2737
  • Loading branch information
jmooring committed Oct 16, 2024
1 parent 1ad28e1 commit 0565354
Showing 1 changed file with 16 additions and 10 deletions.
26 changes: 16 additions & 10 deletions content/en/content-management/urls.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,13 +41,24 @@ https://example.org/posts/my-first-post/

### `url`

Set the `url` in front matter to override the entire path. Use this with either regular pages or section pages.
Set the `url` in front matter to override the entire path. Use this with either regular pages or section pages. If you set both `slug` and `url` in front matter, the `url` value takes precedence.

{{% 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 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.

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:
Expand All @@ -60,7 +71,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:
Expand All @@ -69,12 +80,9 @@ 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`.
With a monolingual site, `url` values with or without a leading slash are relative to the [`baseURL`]. With a multilingual site, `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.

In a multilingual site:

- 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
:--|:--|:--
Expand All @@ -83,8 +91,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" >}}
Expand Down

0 comments on commit 0565354

Please sign in to comment.