diff options
Diffstat (limited to 'docs/content/en/content-management/urls.md')
| -rw-r--r-- | docs/content/en/content-management/urls.md | 417 |
1 files changed, 228 insertions, 189 deletions
diff --git a/docs/content/en/content-management/urls.md b/docs/content/en/content-management/urls.md index 739c9c390..c65d6c15a 100644 --- a/docs/content/en/content-management/urls.md +++ b/docs/content/en/content-management/urls.md @@ -1,7 +1,6 @@ --- title: URL Management -linkTitle: URL Management -description: Hugo supports permalinks, aliases, link canonicalization, and multiple options for handling relative vs absolute URLs. +description: Control the structure and appearance of URLs through front matter entries and settings in your site configuration. categories: [content management] keywords: [aliases,redirects,permalinks,urls] menu: @@ -13,46 +12,148 @@ weight: 180 aliases: [/extras/permalinks/,/extras/aliases/,/extras/urls/,/doc/redirects/,/doc/alias/,/doc/aliases/] --- -## Permalinks +## Overview -The default Hugo target directory for your built website is `public/`. However, you can change this value by specifying a different `publishDir` in your [site configuration][config]. The directories created at build time for a section reflect the position of the content's directory within the `content` folder and namespace matching its layout within the `contentdir` hierarchy. +By default, when Hugo renders a page, the resulting URL matches the file path within the `content` directory. For example: -The `permalinks` option in your [site configuration][config] allows you to adjust the directory paths (i.e., the URLs) on a per-section basis. This will change where the files are written to and will change the page's internal "canonical" location, such that template references to `.RelPermalink` will honor the adjustments made as a result of the mappings in this option. +```text +content/posts/post-1.md → https://example.org/posts/post-1/ +``` + +You can change the structure and appearance of URLs with front matter values and site configuration options. + +## Front matter + +### `slug` + +Set the `slug` in front matter to override the last segment of the path. The `slug` value does not affect section pages. + +{{< code-toggle file="content/posts/post-1.md" copy=false fm=true >}} +title = 'My First Post' +slug = 'my-first-post' +{{< /code-toggle >}} + +The resulting URL will be: + +```text +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. + +With this front matter: + +{{< code-toggle file="content/posts/post-1.md" copy=false fm=true >}} +title = 'My First Article' +url = '/articles/my-first-article' +{{< /code-toggle >}} + +The resulting URL will be: + +```text +https://example.org/articles/my-first-article/ +``` + +If you include a file extension: + +{{< code-toggle file="content/posts/post-1.md" copy=false fm=true >}} +title = 'My First Article' +url = '/articles/my-first-article.html' +{{< /code-toggle >}} + +The resulting URL will be: + +```text +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`. + +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. + +Site type|Front matter `url`|Resulting URL +:--|:--|:-- +monolingual|`/about`|`https://example.org/about/` +monolingual|`about`|`https://example.org/about/` +multilingual|`/about`|`https://example.org/about/` +multilingual|`about`|`https://example.org/de/about/` -{{% note "Default Publish and Content Folders" %}} -These examples use the default values for `publishDir` and `contentDir`; i.e., `public` and `content`, respectively. You can override the default values in your [site's `config` file](/getting-started/configuration/). +If you set both `slug` and `url` in front matter, the `url` value takes precedence. + +## Site configuration + +### Permalinks + +In your site configuration, set a URL pattern for regular pages within a top-level section. This is recursive, affecting descendant regular pages. + +{{% 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 %}} -For example, if one of your [sections] is called `posts` and you want to adjust the canonical path to be hierarchical based on the year, month, and post title, you could set up the following configurations in YAML and TOML, respectively. +#### Examples {#permalinks-examples} -### Permalinks Configuration Example +With this content structure: -{{< code-toggle file="config" copy="false" >}} -permalinks: - posts: /:year/:month/:title/ +```text +content/ +├── posts/ +│ ├── _index.md +│ ├── post-1.md +│ └── post-2.md +└── _index.md +``` + +Create a date-based hierarchy, recursively, for regular pages within the `posts` section: + +{{< code-toggle file="config" copy=false >}} +[permalinks] + posts = '/posts/:year/:month/:title/' {{< /code-toggle >}} -Only the content under `posts/` will have the new URL structure. For example, the file `content/posts/sample-entry.md` with `date: 2017-02-27T19:20:00-05:00` in its front matter will render to `public/2017/02/sample-entry/index.html` at build time and therefore be reachable at `https://example.com/2017/02/sample-entry/`. +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 +└── index.html +``` -To configure the `permalinks` option for pages in the "root" section, use **/** as the key: +To create a date-based hierarchy for regular pages in the content root: -{{< code-toggle file="config" copy="false" >}} -permalinks: - /: /:year/:month/:filename/ +{{< code-toggle file="config" copy=false >}} +[permalinks] + '/' = '/:year/:month/:title/' {{< /code-toggle >}} -If the standard date-based permalink configuration does not meet your needs, you can also format URL segments using [Go time formatting directives](https://pkg.go.dev/time#Time.Format). For example, a URL structure with two digit years and month and day digits without zero padding can be accomplished with: +{{% note %}} +A URL pattern defined for the content root is not recursive. +{{% /note %}} -{{< code-toggle file="config" copy="false" >}} -permalinks: - posts: /:06/:1/:2/:title/ +Use the same approach with taxonomies. For example, to omit the taxonomy segment of the URL: + +{{< code-toggle file="config" copy=false >}} +[permalinks] + 'tags' = '/:title/' {{< /code-toggle >}} -You can also configure permalinks of taxonomies with the same syntax, by using the plural form of the taxonomy instead of the section. You will probably only want to use the configuration values `:slug` or `:title`. +Front matter `url` values take precedence over URL patterns defined in `permalinks`. -### Permalink Configuration Values +#### Tokens -The following is a list of values that can be used in a `permalink` definition in your site `config` file. All references to time are dependent on the content's date. +Use these tokens when defining the URL pattern. The `date` field in front matter determines the value of time-related tokens. `:year` : the 4-digit year @@ -93,219 +194,157 @@ The following is a list of values that can be used in a `permalink` definition i `:filename` : the content's filename (without extension) -Additionally, a Go time format string prefixed with `:` may be used. +For time-related values, you can also use the layout string components defined in Go's [time package]. For example: -## Aliases - -Aliases can be used to create redirects to your page from other URLs. - -Aliases comes in two forms: - -1. Starting with a `/` meaning they are relative to the `BaseURL`, e.g. `/posts/my-blogpost/` -2. They are relative to the `Page` they're defined in, e.g. `my-blogpost` or even something like `../blog/my-blogpost` (new in Hugo 0.55). - -### Example: Aliases - -Let's assume you create a new piece of content at `content/posts/my-awesome-blog-post.md`. The content is a revision of your previous post at `content/posts/my-original-url.md`. You can create an `aliases` field in the front matter of your new `my-awesome-blog-post.md` where you can add previous paths. The following examples show how to create this field in TOML and YAML front matter, respectively. - -#### TOML Front Matter +[time package]: https://pkg.go.dev/time#pkg-constants -{{< code file="content/posts/my-awesome-post.md" copy="false" >}} -+++ -aliases = [ - "/posts/my-original-url/", - "/2010/01/01/even-earlier-url.html" -] -+++ -{{< /code >}} - -#### YAML Front Matter - -{{< code file="content/posts/my-awesome-post.md" copy="false" >}} ---- -aliases: - - /posts/my-original-url/ - - /2010/01/01/even-earlier-url.html ---- -{{< /code >}} +{{< code-toggle file="config" copy=false >}} +permalinks: + posts: /:06/:1/:2/:title/ +{{< /code-toggle >}} -Now when you visit any of the locations specified in aliases---i.e., _assuming the same site domain_---you'll be redirected to the page they are specified on. For example, a visitor to `example.com/posts/my-original-url/` will be immediately redirected to `example.com/posts/my-awesome-post/`. +### Appearance -### Example: Aliases in Multilingual +The appearance of a URL is either ugly or pretty. -On [multilingual sites][multilingual], each translation of a post can have unique aliases. To use the same alias across multiple languages, prefix it with the language code. +Type|Path|URL +:--|:--|:-- +ugly|content/about.md|`https://example.org/about.html` +pretty|content/about.md|`https://example.org/about/` -In `/posts/my-new-post.es.md`: +By default, Hugo produces pretty URLs. To generate ugly URLs, change your site configuration: -```md ---- -aliases: - - /es/posts/my-original-post/ ---- -``` +{{< code-toggle file="config" copy=false >}} +uglyURLs = true +{{< /code-toggle >}} -From Hugo 0.55 you can also have page-relative aliases, so `/es/posts/my-original-post/` can be simplified to the more portable `my-original-post/` +### Post-processing -### How Hugo Aliases Work +Hugo provides two mutually exclusive configuration options to alter URLs _after_ it renders a page. -When aliases are specified, Hugo creates a directory to match the alias entry. Inside the directory, Hugo creates an `.html` file specifying the canonical URL for the page and the new redirect target. +#### Canonical URLs -For example, a content file at `posts/my-intended-url.md` with the following in the front matter: +{{% note %}} +This is a legacy configuration option, superseded by template functions and markdown render hooks, and will likely be [removed in a future release]. -```yml ---- -title: My New post -aliases: [/posts/my-old-url/] ---- -``` +[removed in a future release]: https://github.com/gohugoio/hugo/issues/4733 +{{% /note %}} -Assuming a `baseURL` of `example.com`, the contents of the auto-generated alias `.html` found at `https://example.com/posts/my-old-url/` will contain the following: +If enabled, Hugo performs a search and replace _after_ it renders the page. It searches for site-relative URLs (those with a leading slash) associated with `action`, `href`, `src`, `srcset`, and `url` attributes. It then prepends the `baseURL` to create absolute URLs. -```html -<!DOCTYPE html> -<html> - <head> - <title>https://example.com/posts/my-intended-url</title> - <link rel="canonical" href="https://example.com/posts/my-intended-url"/> - <meta name="robots" content="noindex"> - <meta http-equiv="content-type" content="text/html; charset=utf-8"/> - <meta http-equiv="refresh" content="0; url=https://example.com/posts/my-intended-url"/> - </head> -</html> +```text +<a href="/about"> → <a href="https://example.org/about/"> +<img src="/a.gif"> → <img src="https://example.org/a.gif"> ``` -The `http-equiv="refresh"` line is what performs the redirect, in 0 seconds in this case. If an end user of your website goes to `https://example.com/posts/my-old-url`, they will now be automatically redirected to the newer, correct URL. The addition of `<meta name="robots" content="noindex">` lets search engine bots know that they should not index your alias page (`https://example.com/posts/my-old-url/`). - -### Customize +This is an imperfect, brute force approach that can affect content as well as HTML attributes. As noted above, this is a legacy configuration option that will likely be removed in a future release. -You may customize this alias page by creating an `alias.html` template in the -layouts folder of your site (i.e., `layouts/alias.html`). In this case, the data passed to the template is - -`Permalink` -: the link to the page being aliased +To enable: -`Page` -: the Page data for the page being aliased - -### Important Behaviors of Aliases +{{< code-toggle file="config" copy=false >}} +canonifyURLs = true +{{< /code-toggle >}} -1. Hugo makes no assumptions about aliases. They also do not change based -on your UglyURLs setting. You need to provide absolute paths to your web root -and the complete filename or directory. -2. Aliases are rendered *before* any content are rendered and therefore will be overwritten by any content with the same location. +#### Relative URLs -## Pretty URLs +{{% note %}} +Do not enable this option unless you are creating a serverless site, navigable via the file system. +{{% /note %}} -Hugo's default behavior is to render your content with "pretty" URLs. No non-standard server-side configuration is required for these pretty URLs to work. +If enabled, Hugo performs a search and replace _after_ it renders the page. It searches for site-relative URLs (those with a leading slash) associated with `action`, `href`, `src`, `srcset`, and `url` attributes. It then transforms the URL to be relative to the current page. -The following demonstrates the concept: +For example, when rendering `content/posts/post-1`: -```txt -content/posts/_index.md -=> example.com/posts/ -content/posts/post-1.md -=> example.com/posts/post-1/ +```text +<a href="/about"> → <a href="../../about"> +<img src="/a.gif"> → <img src="../../a.gif"> ``` -## Ugly URLs +This is an imperfect, brute force approach that can affect content as well as HTML attributes. As noted above, do not enable this option unless you are creating a serverless site. -If you would like to have what are often referred to as "ugly URLs" (e.g., example.com/urls.html), set `uglyurls = true` or `uglyurls: true` in your site's `config.toml` or `config.yaml`, respectively. You can also set the `HUGO_UGLYURLS` environment variable to `true` when running `hugo` or `hugo server`. +To enable: -If you want a specific piece of content to have an exact URL, you can specify this in the [front matter] under the `url` key. The following are examples of the same content directory and what the eventual URL structure will be when Hugo runs with its default behavior. +{{< code-toggle file="config" copy=false >}} +relativeURLs = true +{{< /code-toggle >}} -See [Content Organization][contentorg] for more details on paths. +## Aliases -```txt -. -└── content - └── about - | └── _index.md // <- https://example.com/about/ - ├── posts - | ├── firstpost.md // <- https://example.com/posts/firstpost/ - | ├── happy - | | └── ness.md // <- https://example.com/posts/happy/ness/ - | └── secondpost.md // <- https://example.com/posts/secondpost/ - └── quote - ├── first.md // <- https://example.com/quote/first/ - └── second.md // <- https://example.com/quote/second/ -``` +Create redirects from old URLs to new URLs with aliases: -Here's the same organization run with `hugo --uglyURLs`: - -```txt -. -└── content - └── about - | └── _index.md // <- https://example.com/about.html - ├── posts - | ├── firstpost.md // <- https://example.com/posts/firstpost.html - | ├── happy - | | └── ness.md // <- https://example.com/posts/happy/ness.html - | └── secondpost.md // <- https://example.com/posts/secondpost.html - └── quote - ├── first.md // <- https://example.com/quote/first.html - └── second.md // <- https://example.com/quote/second.html -``` +- An alias with a leading slash is relative to the `baseURL` +- An alias without a leading slash is relative to the current directory -## Canonicalization +### Examples {#alias-examples} -By default, all relative URLs encountered in the input are left unmodified, e.g. `/css/foo.css` would stay as `/css/foo.css`. The `canonifyURLs` field in your site `config` has a default value of `false`. +Change the file name of an existing page, and create an alias from the previous URL to the new URL: -By setting `canonifyURLs` to `true`, all relative URLs would instead be *canonicalized* using `baseURL`. For example, assuming you have `baseURL = https://example.com/`, the relative URL `/css/foo.css` would be turned into the absolute URL `https://example.com/css/foo.css`. +{{< code-toggle file="content/posts/new-file-name.md" copy=false >}} +aliases = ['/posts/previous-file-name'] +{{< /code-toggle >}} -Benefits of canonicalization include fixing all URLs to be absolute, which may aid with some parsing tasks. Note, however, that all modern browsers handle this on the client without issue. +Each of these directory-relative aliases is equivalent to the site-relative alias above: -Benefits of non-canonicalization include being able to have scheme-relative resource inclusion; e.g., so that `http` vs `https` can be decided according to how the page was retrieved. +- `previous-file-name` +- `./previous-file-name` +- `../posts/previous-file-name` -{{% note "`canonifyURLs` default change" %}} -In the May 2014 release of Hugo v0.11, the default value of `canonifyURLs` was switched from `true` to `false`, which we think is the better default and should continue to be the case going forward. Please verify and adjust your website accordingly if you are upgrading from v0.10 or older versions. -{{% /note %}} +You can create more than one alias to the current page: -To find out the current value of `canonifyURLs` for your website, you may use the handy `hugo config` command added in v0.13. +{{< code-toggle file="content/posts/new-file-name.md" copy=false >}} +aliases = ['previous-file-name','original-file-name'] +{{< /code-toggle >}} -```txt -hugo config | grep -i canon -``` +In a multilingual site, use a directory-relative alias, or include the language prefix with a site-relative alias: -Or, if you are on Windows and do not have `grep` installed: +{{< code-toggle file="content/posts/new-file-name.de.md" copy=false >}} +aliases = ['/de/posts/previous-file-name'] +{{< /code-toggle >}} -```txt -hugo config | FINDSTR /I canon -``` +### How Aliases Work -## Set URL in Front Matter +Using the first example above, Hugo generates the following site structure: -In addition to specifying permalink values in your site configuration for different content sections, Hugo provides even more granular control for individual pieces of content. +```text +public/ +├── posts/ +│ ├── new-file-name/ +│ │ └── index.html +│ ├── previous-file-name/ +│ │ └── index.html +│ └── index.html +└── index.html +``` -Both `slug` and `url` can be defined in individual front matter. For more information on content destinations at build time, see [Content Organization][contentorg]. +The alias from the previous URL to the new URL is a client-side redirect: -From Hugo 0.55, you can use URLs relative to the current site context (the language), which makes it simpler to maintain. For a Japanese translation, both of the following examples would get the same URL: +{{< code file="posts/previous-file-name/index.html" copy=false >}} +<!DOCTYPE html> +<html lang="en-us"> + <head> + <title>https://example.org/posts/new-file-name/</title> + <link rel="canonical" href="https://example.org/posts/new-file-name/"> + <meta name="robots" content="noindex"> + <meta charset="utf-8"> + <meta http-equiv="refresh" content="0; url=https://example.org/posts/new-file-name/"> + </head> +</html> +{{< /code >}} -```markdown ---- -title: "Custom URL!" -url: "/jp/custom/foo" ---- -``` +Collectively, the elements in the `head` section: -```markdown ---- -title: "Custom URL!" -url: "custom/foo" ---- -``` +- Tell search engines that the new URL is canonical +- Tell search engines not to index the previous URL +- Tell the browser to redirect to the new URL -## Relative URLs +Hugo renders alias files before rendering pages. A new page with the previous file name will overwrite the alias, as expected. -By default, all relative URLs are left unchanged by Hugo, which can be problematic when you want to make your site browsable from a local file system. +### Customize -Setting `relativeURLs` to `true` in your [site configuration][config] will cause Hugo to rewrite all relative URLs to be relative to the current content. +Create a new template (`layouts/alias.html`) to customize the content of the alias files. The template receives the following context: -For example, if your `/posts/first/` page contains a link to `/about/`, Hugo will rewrite the URL to `../../about/`. +`Permalink` +: the link to the page being aliased -[config]: /getting-started/configuration/ -[contentorg]: /content-management/organization/ -[front matter]: /content-management/front-matter/ -[multilingual]: /content-management/multilingual/ -[sections]: /content-management/sections/ -[usage]: /getting-started/usage/ +`Page` +: the Page data for the page being aliased |