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/ordering
title: Aliases
weight: 10
---

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.
Adding support for aliases (redirects) 2013-08-10 15:35:34 +01: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 23:45:19 +01: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`
Converting front matter to YAML 2014-05-29 18:42:05 -04:00			`prev: /taxonomies/ordering`
			`title: Aliases`
			`weight: 10`
Adding support for aliases (redirects) 2013-08-10 15:35:34 +01: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 15:56:56 +09: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 15:35:34 +01: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 15:56:56 +09:00			`Luckily, redirects can be handled easily with _aliases_ in Hugo.`
Adding support for aliases (redirects) 2013-08-10 15:35:34 +01: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 15:56:56 +09: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 12:00:08 -06: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 15:56:56 +09: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 12:00:08 -06: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 15:56:56 +09:00
			`### TOML frontmatter`

Docs: Add nohighlight shortcode and improve formatting And some random formatting and copyediting fixes. See also #1708 2015-12-23 09:31:07 -07: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 15:56:56 +09: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 00:45:53 -07: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 15:56:56 +09: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 00:45:53 -07: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 15:56:56 +09: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 00:45:53 -07:00			`+++`
Docs: Add nohighlight shortcode and improve formatting And some random formatting and copyediting fixes. See also #1708 2015-12-23 09:31:07 -07: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 15:56:56 +09:00
			`### YAML frontmatter`

Docs: Add nohighlight shortcode and improve formatting And some random formatting and copyediting fixes. See also #1708 2015-12-23 09:31:07 -07: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 15:56:56 +09: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 19:17:09 -07: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 15:56:56 +09: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 19:17:09 -07:00			`---`
Docs: Add nohighlight shortcode and improve formatting And some random formatting and copyediting fixes. See also #1708 2015-12-23 09:31:07 -07:00			```
Adding support for aliases (redirects) 2013-08-10 15:35:34 +01: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 12:00:08 -06: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 15:35:34 +01: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 09:31:07 -07: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 15:35:34 +01: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 15:56:56 +09: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 15:56:56 +09: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 12:00:08 -06: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 15:56:56 +09: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 12:00:08 -06: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 15:56:56 +09:00
Docs: Add nohighlight shortcode and improve formatting And some random formatting and copyediting fixes. See also #1708 2015-12-23 09:31:07 -07: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 15:56:56 +09: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 15:56:56 +09: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 15:56:56 +09:00			`</head>`
			`</html>`
Docs: Add nohighlight shortcode and improve formatting And some random formatting and copyediting fixes. See also #1708 2015-12-23 09:31:07 -07: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 15:56:56 +09:00
			The `http-equiv="refresh"` line is what performs the redirect, in 0 seconds in this case.