hugo/docs/content/extras/aliases.md

---
aliases:
- /doc/redirects/
- /doc/alias/
- /doc/aliases/
lastmod: 2015-12-23
date: 2013-07-09
menu:
  main:
    parent: extras
next: /extras/analytics
prev: /taxonomies/methods
title: Aliases
---

For people migrating existing published content to Hugo, there's a good chance you need a mechanism to handle redirecting old URLs.

Luckily, redirects can be handled easily with _aliases_ in Hugo.

## Example

Given a post on your current Hugo site, with a path of:

``content/posts/my-awesome-blog-post.md``

... you create an "aliases" section in the frontmatter of your post, and add previous paths to that.

### TOML frontmatter

```toml
+++
        ...
aliases = [
    "/posts/my-original-url/",
    "/2010/01/01/even-earlier-url.html"
]
        ...
+++
```

### YAML frontmatter

```yaml
---
        ...
aliases:
    - /posts/my-original-url/
    - /2010/01/01/even-earlier-url.html
        ...
---
```

Now when you visit any of the locations specified in aliases, _assuming the same site domain_, you'll be redirected to the page they are specified on.

## Important Behaviors

1. *Hugo makes no assumptions about aliases. They also don't change based
on your UglyURLs setting. You need to provide absolute path to your webroot
and the complete filename or directory.*

2. *Aliases are rendered prior to any content and will be overwritten by
any content with the same location.*

## Multilingual example

On [multilingual sites]({{< relref "content/multilingual.md" >}}), each translation of a post can have unique aliases. To use the same alias across multiple languages, prefix it with the language code.

In `/posts/my-new-post.es.md`:

```yaml
---
aliases:
    - /es/posts/my-original-post/
---
```

## How Hugo Aliases Work

When aliases are specified, Hugo creates a physical folder structure to match the alias entry, and, an html file specifying the canonical URL for the page, and a redirect target.

Assuming a baseURL of `mysite.tld`, the contents of the html file will look something like:

```html
<!DOCTYPE html>
<html>
  <head>
    <title>http://mysite.tld/posts/my-original-url</title>
    <link rel="canonical" href="http://mysite.tld/posts/my-original-url"/>
    <meta http-equiv="content-type" content="text/html; charset=utf-8"/>
    <meta http-equiv="refresh" content="0; url=http://mysite.tld/posts/my-original-url"/>
  </head>
</html>
```

The `http-equiv="refresh"` line is what performs the redirect, in 0 seconds in this case.

## Customizing

You may customize this alias page by creating an alias.html template in the
layouts folder of your site.  In this case, the data passed to the template is

* Permalink - the link to the page being aliased
* Page - the Page data for the page being aliased
Adding support for aliases (redirects) 2013-08-10 10:35:34 -04:00			`---`
Complete overhaul of the docs 2013-08-17 08:34:25 -04:00			`aliases:`
Converting front matter to YAML 2014-05-29 18:42:05 -04:00			`- /doc/redirects/`
			`- /doc/alias/`
			`- /doc/aliases/`
docs: Add lastmod to content files Based on last commit in Git. 2016-01-06 17:45:19 -05:00			`lastmod: 2015-12-23`
Converting front matter to YAML 2014-05-29 18:42:05 -04:00			`date: 2013-07-09`
Implementing new menu system in the docs site 2014-04-23 03:00:11 -04:00			`menu:`
			`main:`
Converting front matter to YAML 2014-05-29 18:42:05 -04:00			`parent: extras`
Add documentation for Google Analytics internal template Fixes #1654 2016-02-06 10:09:47 -05:00			`next: /extras/analytics`
docs: Cleanup Extras menu ordering 2016-12-11 19:55:36 -05:00			`prev: /taxonomies/methods`
Converting front matter to YAML 2014-05-29 18:42:05 -04:00			`title: Aliases`
Adding support for aliases (redirects) 2013-08-10 10:35:34 -04:00			`---`

Edits on aliases, comments, theme customizing Fleshed out aliases section, loading the "redirect" keyword so that it's easier to find. Specifically added a "how aliases work" section. Added Discourse to comments section. Fleshed out themes/customizing, because it seems to be the source of a lot of questions on the forum. 2015-05-12 02:56:56 -04:00			`For people migrating existing published content to Hugo, there's a good chance you need a mechanism to handle redirecting old URLs.`
Adding support for aliases (redirects) 2013-08-10 10:35:34 -04:00
Edits on aliases, comments, theme customizing Fleshed out aliases section, loading the "redirect" keyword so that it's easier to find. Specifically added a "how aliases work" section. Added Discourse to comments section. Fleshed out themes/customizing, because it seems to be the source of a lot of questions on the forum. 2015-05-12 02:56:56 -04:00			`Luckily, redirects can be handled easily with _aliases_ in Hugo.`
Adding support for aliases (redirects) 2013-08-10 10:35:34 -04:00
			`## Example`
Edits on aliases, comments, theme customizing Fleshed out aliases section, loading the "redirect" keyword so that it's easier to find. Specifically added a "how aliases work" section. Added Discourse to comments section. Fleshed out themes/customizing, because it seems to be the source of a lot of questions on the forum. 2015-05-12 02:56:56 -04:00
doc: Strip trailing whitespace; other revisions Make some random and non-comprehensive changes to the template functions documentation to make them more consistent. 2015-08-04 14:00:08 -04:00			`Given a post on your current Hugo site, with a path of:`
Edits on aliases, comments, theme customizing Fleshed out aliases section, loading the "redirect" keyword so that it's easier to find. Specifically added a "how aliases work" section. Added Discourse to comments section. Fleshed out themes/customizing, because it seems to be the source of a lot of questions on the forum. 2015-05-12 02:56:56 -04:00
			``content/posts/my-awesome-blog-post.md``

doc: Strip trailing whitespace; other revisions Make some random and non-comprehensive changes to the template functions documentation to make them more consistent. 2015-08-04 14:00:08 -04:00			`... you create an "aliases" section in the frontmatter of your post, and add previous paths to that.`
Edits on aliases, comments, theme customizing Fleshed out aliases section, loading the "redirect" keyword so that it's easier to find. Specifically added a "how aliases work" section. Added Discourse to comments section. Fleshed out themes/customizing, because it seems to be the source of a lot of questions on the forum. 2015-05-12 02:56:56 -04:00
			`### TOML frontmatter`

Docs: Add nohighlight shortcode and improve formatting And some random formatting and copyediting fixes. See also #1708 2015-12-23 11:31:07 -05:00			```toml
Edits on aliases, comments, theme customizing Fleshed out aliases section, loading the "redirect" keyword so that it's easier to find. Specifically added a "how aliases work" section. Added Discourse to comments section. Fleshed out themes/customizing, because it seems to be the source of a lot of questions on the forum. 2015-05-12 02:56:56 -04:00			`+++`
			`...`
[Docs] More copyediting * Add link to https://travis-ci.org/spf13/hugo * Correct heading levels in docs/content/community/mailing-list.md * Mention RFC 3339 as the `date` format set by `hugo new` * Mention that `hugo new` does not add `draft = true` when the user provides an archetype * List short examples of TOML and YAML side by side * Compact the Math template functions into a table * Put some notes into a blockquote 2015-01-17 02:45:53 -05:00			`aliases = [`
			`"/posts/my-original-url/",`
Edits on aliases, comments, theme customizing Fleshed out aliases section, loading the "redirect" keyword so that it's easier to find. Specifically added a "how aliases work" section. Added Discourse to comments section. Fleshed out themes/customizing, because it seems to be the source of a lot of questions on the forum. 2015-05-12 02:56:56 -04:00			`"/2010/01/01/even-earlier-url.html"`
[Docs] More copyediting * Add link to https://travis-ci.org/spf13/hugo * Correct heading levels in docs/content/community/mailing-list.md * Mention RFC 3339 as the `date` format set by `hugo new` * Mention that `hugo new` does not add `draft = true` when the user provides an archetype * List short examples of TOML and YAML side by side * Compact the Math template functions into a table * Put some notes into a blockquote 2015-01-17 02:45:53 -05:00			`]`
Edits on aliases, comments, theme customizing Fleshed out aliases section, loading the "redirect" keyword so that it's easier to find. Specifically added a "how aliases work" section. Added Discourse to comments section. Fleshed out themes/customizing, because it seems to be the source of a lot of questions on the forum. 2015-05-12 02:56:56 -04:00			`...`
[Docs] More copyediting * Add link to https://travis-ci.org/spf13/hugo * Correct heading levels in docs/content/community/mailing-list.md * Mention RFC 3339 as the `date` format set by `hugo new` * Mention that `hugo new` does not add `draft = true` when the user provides an archetype * List short examples of TOML and YAML side by side * Compact the Math template functions into a table * Put some notes into a blockquote 2015-01-17 02:45:53 -05:00			`+++`
Docs: Add nohighlight shortcode and improve formatting And some random formatting and copyediting fixes. See also #1708 2015-12-23 11:31:07 -05:00			```
Edits on aliases, comments, theme customizing Fleshed out aliases section, loading the "redirect" keyword so that it's easier to find. Specifically added a "how aliases work" section. Added Discourse to comments section. Fleshed out themes/customizing, because it seems to be the source of a lot of questions on the forum. 2015-05-12 02:56:56 -04:00
			`### YAML frontmatter`

Docs: Add nohighlight shortcode and improve formatting And some random formatting and copyediting fixes. See also #1708 2015-12-23 11:31:07 -05:00			```yaml
Edits on aliases, comments, theme customizing Fleshed out aliases section, loading the "redirect" keyword so that it's easier to find. Specifically added a "how aliases work" section. Added Discourse to comments section. Fleshed out themes/customizing, because it seems to be the source of a lot of questions on the forum. 2015-05-12 02:56:56 -04:00			`---`
			`...`
[Docs] Copyediting * Add meta author, description and generator tags * Add Hugo version beside the logo and in the footer * Suggest the user to run `go get -u -v` to update dependencies * Requires Go 1.3+ rather than Go 1.1+ * Improve rendering/formatting in some places * Add trailing slash to URLs where appropriate * GitHub redirects all http requests to https, update accordingly 2015-01-27 21:17:09 -05:00			`aliases:`
			`- /posts/my-original-url/`
Edits on aliases, comments, theme customizing Fleshed out aliases section, loading the "redirect" keyword so that it's easier to find. Specifically added a "how aliases work" section. Added Discourse to comments section. Fleshed out themes/customizing, because it seems to be the source of a lot of questions on the forum. 2015-05-12 02:56:56 -04:00			`- /2010/01/01/even-earlier-url.html`
			`...`
[Docs] Copyediting * Add meta author, description and generator tags * Add Hugo version beside the logo and in the footer * Suggest the user to run `go get -u -v` to update dependencies * Requires Go 1.3+ rather than Go 1.1+ * Improve rendering/formatting in some places * Add trailing slash to URLs where appropriate * GitHub redirects all http requests to https, update accordingly 2015-01-27 21:17:09 -05:00			`---`
Docs: Add nohighlight shortcode and improve formatting And some random formatting and copyediting fixes. See also #1708 2015-12-23 11:31:07 -05:00			```
Adding support for aliases (redirects) 2013-08-10 10:35:34 -04:00
doc: Strip trailing whitespace; other revisions Make some random and non-comprehensive changes to the template functions documentation to make them more consistent. 2015-08-04 14:00:08 -04:00			`Now when you visit any of the locations specified in aliases, _assuming the same site domain_, you'll be redirected to the page they are specified on.`
Adding support for aliases (redirects) 2013-08-10 10:35:34 -04:00
			`## Important Behaviors`

			`1. *Hugo makes no assumptions about aliases. They also don't change based`
Docs: Add nohighlight shortcode and improve formatting And some random formatting and copyediting fixes. See also #1708 2015-12-23 11:31:07 -05:00			`on your UglyURLs setting. You need to provide absolute path to your webroot`
			`and the complete filename or directory.*`
Adding support for aliases (redirects) 2013-08-10 10:35:34 -04:00
			`2. *Aliases are rendered prior to any content and will be overwritten by`
			`any content with the same location.*`
Edits on aliases, comments, theme customizing Fleshed out aliases section, loading the "redirect" keyword so that it's easier to find. Specifically added a "how aliases work" section. Added Discourse to comments section. Fleshed out themes/customizing, because it seems to be the source of a lot of questions on the forum. 2015-05-12 02:56:56 -04:00
docs: Add multilingual alias example 2016-09-16 15:48:42 -04:00			`## Multilingual example`

			`On [multilingual sites]({{< relref "content/multilingual.md" >}}), each translation of a post can have unique aliases. To use the same alias across multiple languages, prefix it with the language code.`

			In `/posts/my-new-post.es.md`:

			```yaml
			`---`
			`aliases:`
			`- /es/posts/my-original-post/`
			`---`
			```

Edits on aliases, comments, theme customizing Fleshed out aliases section, loading the "redirect" keyword so that it's easier to find. Specifically added a "how aliases work" section. Added Discourse to comments section. Fleshed out themes/customizing, because it seems to be the source of a lot of questions on the forum. 2015-05-12 02:56:56 -04:00			`## How Hugo Aliases Work`

doc: Strip trailing whitespace; other revisions Make some random and non-comprehensive changes to the template functions documentation to make them more consistent. 2015-08-04 14:00:08 -04:00			`When aliases are specified, Hugo creates a physical folder structure to match the alias entry, and, an html file specifying the canonical URL for the page, and a redirect target.`
Edits on aliases, comments, theme customizing Fleshed out aliases section, loading the "redirect" keyword so that it's easier to find. Specifically added a "how aliases work" section. Added Discourse to comments section. Fleshed out themes/customizing, because it seems to be the source of a lot of questions on the forum. 2015-05-12 02:56:56 -04:00
all: Unify case of config variable names All config variables starts with low-case and uses camelCase. If there is abbreviation at the beginning of the name, the whole abbreviation will be written in low-case. If there is abbreviation at the end of the name, the whole abbreviation will be written in upper-case. For example, rssURI. 2016-10-24 14:56:00 -04:00			Assuming a baseURL of `mysite.tld`, the contents of the html file will look something like:
Edits on aliases, comments, theme customizing Fleshed out aliases section, loading the "redirect" keyword so that it's easier to find. Specifically added a "how aliases work" section. Added Discourse to comments section. Fleshed out themes/customizing, because it seems to be the source of a lot of questions on the forum. 2015-05-12 02:56:56 -04:00
Docs: Add nohighlight shortcode and improve formatting And some random formatting and copyediting fixes. See also #1708 2015-12-23 11:31:07 -05:00			```html
Edits on aliases, comments, theme customizing Fleshed out aliases section, loading the "redirect" keyword so that it's easier to find. Specifically added a "how aliases work" section. Added Discourse to comments section. Fleshed out themes/customizing, because it seems to be the source of a lot of questions on the forum. 2015-05-12 02:56:56 -04:00			`<!DOCTYPE html>`
			`<html>`
			`<head>`
Update the alias generated HTML files to conform to the W3C HTML spec - W3C recommends that there be a [whitespace character][1] between the `;` and the `url=` portions. - W3C also recommends that there be a [title][2] child in the `head` element [1]: https://www.w3.org/TR/html-markup/meta.http-equiv.refresh.html [2]: https://www.w3.org/TR/html-markup/head.html Closes #1933 2016-03-07 15:05:51 -05:00			`<title>http://mysite.tld/posts/my-original-url</title>`
Edits on aliases, comments, theme customizing Fleshed out aliases section, loading the "redirect" keyword so that it's easier to find. Specifically added a "how aliases work" section. Added Discourse to comments section. Fleshed out themes/customizing, because it seems to be the source of a lot of questions on the forum. 2015-05-12 02:56:56 -04:00			`<link rel="canonical" href="http://mysite.tld/posts/my-original-url"/>`
			`<meta http-equiv="content-type" content="text/html; charset=utf-8"/>`
Update the alias generated HTML files to conform to the W3C HTML spec - W3C recommends that there be a [whitespace character][1] between the `;` and the `url=` portions. - W3C also recommends that there be a [title][2] child in the `head` element [1]: https://www.w3.org/TR/html-markup/meta.http-equiv.refresh.html [2]: https://www.w3.org/TR/html-markup/head.html Closes #1933 2016-03-07 15:05:51 -05:00			`<meta http-equiv="refresh" content="0; url=http://mysite.tld/posts/my-original-url"/>`
Edits on aliases, comments, theme customizing Fleshed out aliases section, loading the "redirect" keyword so that it's easier to find. Specifically added a "how aliases work" section. Added Discourse to comments section. Fleshed out themes/customizing, because it seems to be the source of a lot of questions on the forum. 2015-05-12 02:56:56 -04:00			`</head>`
			`</html>`
Docs: Add nohighlight shortcode and improve formatting And some random formatting and copyediting fixes. See also #1708 2015-12-23 11:31:07 -05:00			```
Edits on aliases, comments, theme customizing Fleshed out aliases section, loading the "redirect" keyword so that it's easier to find. Specifically added a "how aliases work" section. Added Discourse to comments section. Fleshed out themes/customizing, because it seems to be the source of a lot of questions on the forum. 2015-05-12 02:56:56 -04:00
			The `http-equiv="refresh"` line is what performs the redirect, in 0 seconds in this case.
Implement support for alias templates This change adds a canonical alias.html template that is used for page redirects, and passes the page as data to the template under .Page Fixes #2533 Closes #2576 2016-10-15 07:35:32 -04:00
			`## Customizing`

			`You may customize this alias page by creating an alias.html template in the`
			`layouts folder of your site. In this case, the data passed to the template is`

			`* Permalink - the link to the page being aliased`
docs: Cleanup Extras menu ordering 2016-12-11 19:55:36 -05:00			`* Page - the Page data for the page being aliased`