mirror of
https://github.com/gohugoio/hugoDocs.git
synced 2025-09-10 15:34:44 -04:00
Joe Mooring
GitHub
parent
f71985315d
commit
afb582a800
@ -56,85 +56,85 @@ slug = "spf13-vim-3-0-release-and-new-website"
|
||||
There are a few predefined variables that Hugo is aware of. See [Page Variables][pagevars] for how to call many of these predefined variables in your templates.
|
||||
|
||||
aliases
|
||||
: an array of one or more aliases (e.g., old published paths of renamed content) that will be created in the output directory structure . See [Aliases][aliases] for details.
|
||||
: An array of one or more aliases (e.g., old published paths of renamed content) that will be created in the output directory structure . See [Aliases][aliases] for details.
|
||||
|
||||
audio
|
||||
: an array of paths to audio files related to the page; used by the `opengraph` [internal template](/templates/internal) to populate `og:audio`.
|
||||
: An array of paths to audio files related to the page; used by the `opengraph` [internal template](/templates/internal) to populate `og:audio`.
|
||||
|
||||
cascade
|
||||
: a map of Front Matter keys whose values are passed down to the page's descendants unless overwritten by self or a closer ancestor's cascade. See [Front Matter Cascade](#front-matter-cascade) for details.
|
||||
: A map of front matter keys whose values are passed down to the page's descendants unless overwritten by self or a closer ancestor's cascade. See [Front Matter Cascade](#front-matter-cascade) for details.
|
||||
|
||||
date
|
||||
: the datetime assigned to this page. This is usually fetched from the `date` field in front matter, but this behavior is configurable.
|
||||
: The datetime assigned to this page. This is usually fetched from the `date` field in front matter, but this behavior is configurable.
|
||||
|
||||
description
|
||||
: the description for the content.
|
||||
: The description for the content.
|
||||
|
||||
draft
|
||||
: if `true`, the content will not be rendered unless the `--buildDrafts` flag is passed to the `hugo` command.
|
||||
: If `true`, the content will not be rendered unless the `--buildDrafts` flag is passed to the `hugo` command.
|
||||
|
||||
expiryDate
|
||||
: the datetime at which the content should no longer be published by Hugo; expired content will not be rendered unless the `--buildExpired` flag is passed to the `hugo` command.
|
||||
: The datetime at which the content should no longer be published by Hugo; expired content will not be rendered unless the `--buildExpired` flag is passed to the `hugo` command.
|
||||
|
||||
headless
|
||||
: if `true`, sets a leaf bundle to be [headless][headless-bundle].
|
||||
: If `true`, sets a leaf bundle to be [headless][headless-bundle].
|
||||
|
||||
images
|
||||
: an array of paths to images related to the page; used by [internal templates](/templates/internal) such as `_internal/twitter_cards.html`.
|
||||
: An array of paths to images related to the page; used by [internal templates](/templates/internal) such as `_internal/twitter_cards.html`.
|
||||
|
||||
isCJKLanguage
|
||||
: if `true`, Hugo will explicitly treat the content as a CJK language; both `.Summary` and `.WordCount` work properly in CJK languages.
|
||||
: If `true`, Hugo will explicitly treat the content as a CJK language; both `.Summary` and `.WordCount` work properly in CJK languages.
|
||||
|
||||
keywords
|
||||
: the meta keywords for the content.
|
||||
: The meta keywords for the content.
|
||||
|
||||
layout
|
||||
: the layout Hugo should select from the [lookup order][lookup] when rendering the content. If a `type` is not specified in the front matter, Hugo will look for the layout of the same name in the layout directory that corresponds with a content's section. See [Content Types][content type].
|
||||
: The layout Hugo should select from the [lookup order][lookup] when rendering the content. If a `type` is not specified in the front matter, Hugo will look for the layout of the same name in the layout directory that corresponds with a content's section. See [Content Types][content type].
|
||||
|
||||
lastmod
|
||||
: the datetime at which the content was last modified.
|
||||
: The datetime at which the content was last modified.
|
||||
|
||||
linkTitle
|
||||
: used for creating links to content; if set, Hugo defaults to using the `linktitle` before the `title`. Hugo can also [order lists of content by `linktitle`][bylinktitle].
|
||||
: Used for creating links to content; if set, Hugo defaults to using the `linktitle` before the `title`. Hugo can also [order lists of content by `linktitle`][bylinktitle].
|
||||
|
||||
markup
|
||||
: **experimental**; specify `"rst"` for reStructuredText (requires`rst2html`) or `"md"` (default) for Markdown.
|
||||
|
||||
outputs
|
||||
: allows you to specify output formats specific to the content. See [output formats][outputs].
|
||||
: Allows you to specify output formats specific to the content. See [output formats][outputs].
|
||||
|
||||
publishDate
|
||||
: if in the future, content will not be rendered unless the `--buildFuture` flag is passed to `hugo`.
|
||||
: If in the future, content will not be rendered unless the `--buildFuture` flag is passed to `hugo`.
|
||||
|
||||
resources
|
||||
: used for configuring page bundle resources. See [Page Resources][page-resources].
|
||||
: Used for configuring page bundle resources. See [Page Resources][page-resources].
|
||||
|
||||
series
|
||||
: an array of series this page belongs to, as a subset of the `series` [taxonomy](/content-management/taxonomies/); used by the `opengraph` [internal template](/templates/internal) to populate `og:see_also`.
|
||||
: An array of series this page belongs to, as a subset of the `series` [taxonomy](/content-management/taxonomies/); used by the `opengraph` [internal template](/templates/internal) to populate `og:see_also`.
|
||||
|
||||
slug
|
||||
: appears as the tail of the output URL. A value specified in front matter will override the segment of the URL based on the filename.
|
||||
: Overrides the last segment of the URL path. Not applicable to section pages. See [URL Management](/content-management/urls/#slug) for details.
|
||||
|
||||
summary
|
||||
: text used when providing a summary of the article in the `.Summary` page variable; details available in the [content-summaries](/content-management/summaries/) section.
|
||||
: Text used when providing a summary of the article in the `.Summary` page variable; details available in the [content-summaries](/content-management/summaries/) section.
|
||||
|
||||
title
|
||||
: the title for the content.
|
||||
: The title for the content.
|
||||
|
||||
type
|
||||
: the type of the content; this value will be automatically derived from the directory (i.e., the [section]) if not specified in front matter.
|
||||
: The type of the content; this value will be automatically derived from the directory (i.e., the [section]) if not specified in front matter.
|
||||
|
||||
url
|
||||
: the full path to the content from the web root. It makes no assumptions about the path of the content file. See [URL Management](/content-management/urls/#set-url-in-front-matter).
|
||||
: Overrides the entire URL path. Applicable to regular pages and section pages. See [URL Management](/content-management/urls/#url) for details.
|
||||
|
||||
videos
|
||||
: an array of paths to videos related to the page; used by the `opengraph` [internal template](/templates/internal) to populate `og:video`.
|
||||
: An array of paths to videos related to the page; used by the `opengraph` [internal template](/templates/internal) to populate `og:video`.
|
||||
|
||||
weight
|
||||
: used for [ordering your content in lists][ordering]. Lower weight gets higher precedence. So content with lower weight will come first. If set, weights should be non-zero, as 0 is interpreted as an *unset* weight.
|
||||
|
||||
\<taxonomies\>
|
||||
: field name of the *plural* form of the index. See `tags` and `categories` in the above front matter examples. *Note that the plural form of user-defined taxonomies cannot be the same as any of the predefined front matter variables.*
|
||||
: Field name of the *plural* form of the index. See `tags` and `categories` in the above front matter examples. *Note that the plural form of user-defined taxonomies cannot be the same as any of the predefined front matter variables.*
|
||||
|
||||
{{% note "Hugo's Default URL Destinations" %}}
|
||||
If neither `slug` nor `url` is present and [permalinks are not configured otherwise in your site `config` file](/content-management/urls/#permalinks), Hugo will use the filename of your content to create the output URL. See [Content Organization](/content-management/organization) for an explanation of paths in Hugo and [URL Management](/content-management/urls/) for ways to customize Hugo's default behaviors.
|
||||
|
||||
@ -155,9 +155,9 @@ Their language is __assigned__ according to the language code added as a __suffi
|
||||
|
||||
By having the same **path and base filename**, the content pieces are __linked__ together as translated pages.
|
||||
|
||||
{{< note >}}
|
||||
{{% note %}}
|
||||
If a file has no language code, it will be assigned the default language.
|
||||
{{</ note >}}
|
||||
{{% /note %}}
|
||||
|
||||
### Translation by content directory
|
||||
|
||||
@ -209,16 +209,22 @@ By setting the `translationKey` front matter param to `about` in all three pages
|
||||
|
||||
Because paths and filenames are used to handle linking, all translated pages will share the same URL (apart from the language subdirectory).
|
||||
|
||||
To localize the URLs, the [`slug`]({{< ref "/content-management/organization/index.md#slug" >}}) or [`url`]({{< ref "/content-management/organization/index.md#url" >}}) front matter param can be set in any of the non-default language file.
|
||||
To localize URLs:
|
||||
|
||||
For example, a French translation (`content/about.fr.md`) can have its own localized slug.
|
||||
- For a regular page, set either [`slug`] or [`url`] in front matter
|
||||
- For a section page, set [`url`] in front matter
|
||||
|
||||
{{< code-toggle >}}
|
||||
Title: A Propos
|
||||
[`slug`]: /content-management/urls/#slug
|
||||
[`url`]: /content-management/urls/#url
|
||||
|
||||
For example, a French translation can have its own localized slug.
|
||||
|
||||
{{< code-toggle file="content/about.fr.md" fm=true copy=false >}}
|
||||
title: A Propos
|
||||
slug: "a-propos"
|
||||
{{< /code-toggle >}}
|
||||
|
||||
At render, Hugo will build both `/about/` and `/fr/a-propos/` while maintaining their translation linking.
|
||||
At render, Hugo will build both `/about/` and `/fr/a-propos/` without affecting the translation link.
|
||||
|
||||
### Page Bundles
|
||||
|
||||
|
||||
@ -131,10 +131,7 @@ A default content type is determined by the section in which a content item is s
|
||||
|
||||
### `slug`
|
||||
|
||||
A content's `slug` is either `name.extension` or `name/`. The value for `slug` is determined by
|
||||
|
||||
* the name of the content file (e.g., `lollapalooza.md`) OR
|
||||
* front matter overrides
|
||||
The `slug` is the last segment of the URL path, defined by the file name and optionally overridden by a `slug` value in front matter. See [URL Management](/content-management/urls/#slug) for details.
|
||||
|
||||
### `path`
|
||||
|
||||
@ -145,78 +142,7 @@ A content's `path` is determined by the section's path to the file. The file `pa
|
||||
|
||||
### `url`
|
||||
|
||||
The `url` is the relative URL for the piece of content. The `url`
|
||||
|
||||
* is based on the content item's location within the directory structure OR
|
||||
* is defined in front matter, in which case it *overrides all the above*
|
||||
|
||||
## Override Destination Paths via Front Matter
|
||||
|
||||
Hugo assumes that your content is organized with a purpose. The same structure that you use to organize your source content is used to organize the rendered site. As displayed above, the organization of the source content will be mirrored at the destination.
|
||||
|
||||
There are times when you may need more fine-grained control over the content organization. In such cases, the front matter field can be used to determine the destination of a specific piece of content.
|
||||
|
||||
The following items are defined in a specific order for a reason: items explained lower down in the list override higher items. Note that not all items can be defined in front matter.
|
||||
|
||||
### `filename`
|
||||
|
||||
`filename` is not a front matter field. It is the actual file name, minus the extension. This will be the name of the file in the destination (e.g., `content/posts/my-post.md` becomes `example.com/posts/my-post/`).
|
||||
|
||||
### `slug`
|
||||
|
||||
When defined in the front matter, the `slug` can take the place of the filename in the destination.
|
||||
|
||||
{{< code file="content/posts/old-post.md" >}}
|
||||
---
|
||||
title: A new post with the filename old-post.md
|
||||
slug: "new-post"
|
||||
---
|
||||
{{< /code >}}
|
||||
|
||||
This will render to the following destination according to Hugo's default behavior:
|
||||
|
||||
```txt
|
||||
example.com/posts/new-post/
|
||||
```
|
||||
|
||||
### `section`
|
||||
|
||||
`section` is determined by a content item's location on disk and *cannot* be specified in the front matter. See [sections] for more information.
|
||||
|
||||
### `type`
|
||||
|
||||
A content item's `type` is also determined by its location on disk but, unlike `section`, it *can* be specified in the front matter. See [types]. This can come in especially handy when you want a piece of content to render using a different layout. In the following example, you can create a layout at `layouts/new/mylayout.html` that Hugo will use to render this piece of content, even in the midst of many other posts.
|
||||
|
||||
{{< code file="content/posts/my-post.md" >}}
|
||||
---
|
||||
title: My Post
|
||||
type: new
|
||||
layout: mylayout
|
||||
---
|
||||
{{< /code >}}
|
||||
<!-- See https://discourse.gohugo.io/t/path-not-works/6387 -->
|
||||
<!-- ### `path`-->
|
||||
|
||||
<!--`path` can be provided in the front matter. This will replace the actual path to the file on disk. Destination will create the destination with the same path, including the section. -->
|
||||
|
||||
### `url`
|
||||
|
||||
A complete URL can be provided. This will override all the above as it pertains to the end destination. This must be the path from the baseURL (starting with a `/`). `url` will be used exactly as it is defined in the front matter, and will ignore the `--uglyURLs` setting in your site configuration:
|
||||
|
||||
{{< code file="content/posts/old-url.md" >}}
|
||||
---
|
||||
title: Old URL
|
||||
url: /blog/new-url/
|
||||
---
|
||||
{{< /code >}}
|
||||
|
||||
Assuming your `baseURL` is [configured][config] to `https://example.com`, the addition of `url` to the front matter will make `old-url.md` render to the following destination:
|
||||
|
||||
```txt
|
||||
https://example.com/blog/new-url/
|
||||
```
|
||||
|
||||
You can see more information on how to control output paths in [URL Management][urls].
|
||||
The `url` is the entire URL path, defined by the file path and optionally overridden by a `url` value in front matter. See [URL Management](/content-management/urls/#slug) for details.
|
||||
|
||||
[config]: /getting-started/configuration/
|
||||
[formats]: /content-management/formats/
|
||||
|
||||
@ -1,7 +1,7 @@
|
||||
---
|
||||
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 +13,145 @@ 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/
|
||||
```
|
||||
|
||||
{{% 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/).
|
||||
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/`
|
||||
|
||||
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:
|
||||
|
||||
```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: /:year/:month/:title/
|
||||
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:
|
||||
|
||||
To configure the `permalinks` option for pages in the "root" section, use **/** as the key:
|
||||
```text
|
||||
public/
|
||||
├── posts/
|
||||
│ ├── 2023/
|
||||
│ │ └── 03/
|
||||
│ │ ├── post-1/
|
||||
│ │ │ └── index.html
|
||||
│ │ └── post-2/
|
||||
│ │ └── index.html
|
||||
│ └── index.html
|
||||
├── favicon.ico
|
||||
└── index.html
|
||||
```
|
||||
|
||||
To create a date-based hierarchy for regular pages in the content root:
|
||||
|
||||
{{< code-toggle file="config" copy="false" >}}
|
||||
permalinks:
|
||||
/: /:year/:month/:filename/
|
||||
'/' = '/: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 %}}
|
||||
|
||||
Use the same approach with taxonomies. For example, to omit the taxonomy segment of the URL:
|
||||
|
||||
{{< code-toggle file="config" copy="false" >}}
|
||||
permalinks:
|
||||
posts: /:06/:1/:2/:title/
|
||||
'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 +192,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:
|
||||
|
||||
[time package]: https://pkg.go.dev/time#pkg-constants
|
||||
|
||||
{{< code-toggle file="config" copy="false" >}}
|
||||
permalinks:
|
||||
posts: /:06/:1/:2/:title/
|
||||
{{< /code-toggle >}}
|
||||
|
||||
### Appearance
|
||||
|
||||
The appearance of a URL is either ugly or pretty.
|
||||
|
||||
Type|Path|URL
|
||||
:--|:--|:--
|
||||
ugly|content/about.md|`https://example.org/about.html`
|
||||
pretty|content/about.md|`https://example.org/about/`
|
||||
|
||||
By default, Hugo produces pretty URLs. To generate ugly URLs, change your site configuration:
|
||||
|
||||
{{< code-toggle file="config" copy="false" >}}
|
||||
uglyURLs = true
|
||||
{{< /code-toggle >}}
|
||||
|
||||
### Post-processing
|
||||
|
||||
Hugo provides two mutually exclusive configuration options to alter URLs _after_ it renders a page.
|
||||
|
||||
#### Canonical URLs
|
||||
|
||||
{{% note %}}
|
||||
This is a legacy configuration option, superseded by template functions and markdown render hooks, and will likely be [removed in a future release].
|
||||
|
||||
[removed in a future release]: https://github.com/gohugoio/hugo/issues/4733
|
||||
{{% /note %}}
|
||||
|
||||
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.
|
||||
|
||||
```text
|
||||
<a href="/about"> → <a href="https://example.org/about/">
|
||||
<img src="/a.gif"> → <img src="https://example.org/a.gif">
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
To enable:
|
||||
|
||||
{{< code-toggle file="config" copy="false" >}}
|
||||
canonifyURLs = true
|
||||
{{< /code-toggle >}}
|
||||
|
||||
#### Relative URLs
|
||||
|
||||
{{% note %}}
|
||||
Do not enable this option unless you are creating a serverless site, navigable via the file system.
|
||||
{{% /note %}}
|
||||
|
||||
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.
|
||||
|
||||
For example, when rendering `content/posts/post-1`:
|
||||
|
||||
```text
|
||||
<a href="/about"> → <a href="../../about">
|
||||
<img src="/a.gif"> → <img src="../../a.gif">
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
To enable:
|
||||
|
||||
{{< code-toggle file="config" copy="false" >}}
|
||||
relativeURLs = true
|
||||
{{< /code-toggle >}}
|
||||
|
||||
## Aliases
|
||||
|
||||
Aliases can be used to create redirects to your page from other URLs.
|
||||
Create redirects from old URLs to new URLs with aliases:
|
||||
|
||||
Aliases comes in two forms:
|
||||
- An alias with a leading slash is relative to the `baseURL`
|
||||
- An alias without a leading slash is relative to the current directory
|
||||
|
||||
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).
|
||||
### Examples {#alias-examples}
|
||||
|
||||
### Example: Aliases
|
||||
Change the file name of an existing page, and create an alias from the previous URL to the new URL:
|
||||
|
||||
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.
|
||||
{{< code-toggle file="content/posts/new-file-name.md" copy="false" >}}
|
||||
aliases = ['/posts/previous-file-name']
|
||||
{{< /code-toggle >}}
|
||||
|
||||
#### TOML Front Matter
|
||||
Each of these directory-relative aliases is equivalent to the site-relative alias above:
|
||||
|
||||
{{< code file="content/posts/my-awesome-post.md" copy="false" >}}
|
||||
+++
|
||||
aliases = [
|
||||
"/posts/my-original-url/",
|
||||
"/2010/01/01/even-earlier-url.html"
|
||||
]
|
||||
+++
|
||||
{{< /code >}}
|
||||
- `previous-file-name`
|
||||
- `./previous-file-name`
|
||||
- `../posts/previous-file-name`
|
||||
|
||||
#### YAML Front Matter
|
||||
You can create more than one alias to the current page:
|
||||
|
||||
{{< 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="content/posts/new-file-name.md" copy="false" >}}
|
||||
aliases = ['previous-file-name','original-file-name']
|
||||
{{< /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/`.
|
||||
In a multilingual site, use a directory-relative alias, or include the language prefix with a site-relative alias:
|
||||
|
||||
### Example: Aliases in Multilingual
|
||||
{{< code-toggle file="content/posts/new-file-name.de.md" copy="false" >}}
|
||||
aliases = ['/de/posts/previous-file-name']
|
||||
{{< /code-toggle >}}
|
||||
|
||||
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.
|
||||
### How Aliases Work
|
||||
|
||||
In `/posts/my-new-post.es.md`:
|
||||
Using the first example above, Hugo generates the following site structure:
|
||||
|
||||
```md
|
||||
---
|
||||
aliases:
|
||||
- /es/posts/my-original-post/
|
||||
---
|
||||
```text
|
||||
public/
|
||||
├── posts/
|
||||
│ ├── new-file-name/
|
||||
│ │ └── index.html
|
||||
│ ├── previous-file-name/
|
||||
│ │ └── index.html
|
||||
│ └── index.html
|
||||
└── index.html
|
||||
```
|
||||
|
||||
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/`
|
||||
The alias from the previous URL to the new URL is a client-side redirect:
|
||||
|
||||
### How Hugo Aliases Work
|
||||
|
||||
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.
|
||||
|
||||
For example, a content file at `posts/my-intended-url.md` with the following in the front matter:
|
||||
|
||||
```yml
|
||||
---
|
||||
title: My New post
|
||||
aliases: [/posts/my-old-url/]
|
||||
---
|
||||
```
|
||||
|
||||
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:
|
||||
|
||||
```html
|
||||
{{< code file="posts/previous-file-name/index.html" copy="false" >}}
|
||||
<!DOCTYPE html>
|
||||
<html>
|
||||
<html lang="en-us">
|
||||
<head>
|
||||
<title>https://example.com/posts/my-intended-url</title>
|
||||
<link rel="canonical" href="https://example.com/posts/my-intended-url"/>
|
||||
<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 http-equiv="content-type" content="text/html; charset=utf-8"/>
|
||||
<meta http-equiv="refresh" content="0; url=https://example.com/posts/my-intended-url"/>
|
||||
<meta charset="utf-8">
|
||||
<meta http-equiv="refresh" content="0; url=https://example.org/posts/new-file-name/">
|
||||
</head>
|
||||
</html>
|
||||
```
|
||||
{{< /code >}}
|
||||
|
||||
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/`).
|
||||
Collectively, the elements in the `head` section:
|
||||
|
||||
- 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
|
||||
|
||||
Hugo renders alias files before rendering pages. A new page with the previous file name will overwrite the alias, as expected.
|
||||
|
||||
### Customize
|
||||
|
||||
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
|
||||
Create a new template (`layouts/alias.html`) to customize the content of the alias files. The template receives the following context:
|
||||
|
||||
`Permalink`
|
||||
: the link to the page being aliased
|
||||
|
||||
`Page`
|
||||
: the Page data for the page being aliased
|
||||
|
||||
### Important Behaviors of Aliases
|
||||
|
||||
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.
|
||||
|
||||
## Pretty URLs
|
||||
|
||||
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.
|
||||
|
||||
The following demonstrates the concept:
|
||||
|
||||
```txt
|
||||
content/posts/_index.md
|
||||
=> example.com/posts/
|
||||
content/posts/post-1.md
|
||||
=> example.com/posts/post-1/
|
||||
```
|
||||
|
||||
## Ugly URLs
|
||||
|
||||
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`.
|
||||
|
||||
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.
|
||||
|
||||
See [Content Organization][contentorg] for more details on paths.
|
||||
|
||||
```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/
|
||||
```
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
## Canonicalization
|
||||
|
||||
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`.
|
||||
|
||||
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`.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
{{% 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 %}}
|
||||
|
||||
To find out the current value of `canonifyURLs` for your website, you may use the handy `hugo config` command added in v0.13.
|
||||
|
||||
```txt
|
||||
hugo config | grep -i canon
|
||||
```
|
||||
|
||||
Or, if you are on Windows and do not have `grep` installed:
|
||||
|
||||
```txt
|
||||
hugo config | FINDSTR /I canon
|
||||
```
|
||||
|
||||
## Set URL in Front Matter
|
||||
|
||||
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.
|
||||
|
||||
Both `slug` and `url` can be defined in individual front matter. For more information on content destinations at build time, see [Content Organization][contentorg].
|
||||
|
||||
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:
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: "Custom URL!"
|
||||
url: "/jp/custom/foo"
|
||||
---
|
||||
```
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: "Custom URL!"
|
||||
url: "custom/foo"
|
||||
---
|
||||
```
|
||||
|
||||
## Relative URLs
|
||||
|
||||
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.
|
||||
|
||||
Setting `relativeURLs` to `true` in your [site configuration][config] will cause Hugo to rewrite all relative URLs to be relative to the current content.
|
||||
|
||||
For example, if your `/posts/first/` page contains a link to `/about/`, Hugo will rewrite the URL to `../../about/`.
|
||||
|
||||
[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/
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user