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 fa40e39
Showing 1 changed file with 24 additions and 8 deletions.
32 changes: 24 additions & 8 deletions content/en/content-management/urls.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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:
Expand All @@ -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

Check warning on line 91 in content/en/content-management/urls.md

View workflow job for this annotation

GitHub Actions / spellcheck

Unknown word (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
:--|:--|:--
Expand All @@ -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" >}}
Expand Down

0 comments on commit fa40e39

Please sign in to comment.