hugo/docs/content/extras/aliases.md

---
aliases:
- /doc/redirects/
- /doc/alias/
- /doc/aliases/
date: 2013-07-09
menu:
  main:
    parent: extras
next: /extras/builders
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

~~~yaml
+++
        ...
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.*

## 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>
    <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 14:35:34 +00:00			`---`
Complete overhaul of the docs 2013-08-17 12:34:25 +00:00			`aliases:`
Converting front matter to YAML 2014-05-29 22:42:05 +00:00			`- /doc/redirects/`
			`- /doc/alias/`
			`- /doc/aliases/`
			`date: 2013-07-09`
Implementing new menu system in the docs site 2014-04-23 07:00:11 +00:00			`menu:`
			`main:`
Converting front matter to YAML 2014-05-29 22:42:05 +00:00			`parent: extras`
			`next: /extras/builders`
			`prev: /taxonomies/ordering`
			`title: Aliases`
			`weight: 10`
Adding support for aliases (redirects) 2013-08-10 14:35:34 +00: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 06:56:56 +00: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 14:35:34 +00: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 06:56:56 +00:00			`Luckily, redirects can be handled easily with _aliases_ in Hugo.`
Adding support for aliases (redirects) 2013-08-10 14:35:34 +00: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 06:56:56 +00: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 18:00:08 +00: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 06:56:56 +00: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 18:00:08 +00: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 06:56:56 +00:00
			`### TOML frontmatter`

			`~~~yaml`
			`+++`
			`...`
[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 07:45:53 +00: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 06:56:56 +00: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 07:45:53 +00: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 06:56:56 +00: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 07:45:53 +00: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 06:56:56 +00:00			`~~~`

			`### YAML frontmatter`

			`~~~yaml`
			`---`
			`...`
[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-28 02:17:09 +00: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 06:56:56 +00: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-28 02:17:09 +00: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 06:56:56 +00:00			`~~~`
Adding support for aliases (redirects) 2013-08-10 14:35:34 +00: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 18:00:08 +00: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 14:35:34 +00:00
			`## Important Behaviors`

			`1. *Hugo makes no assumptions about aliases. They also don't change based`
Complete the Url-to-URL transition in docs See #959 2015-09-09 05:29:04 +00:00			`on your UglyURLs setting. You need to provide absolute path to your webroot and the`
Adding support for aliases (redirects) 2013-08-10 14:35:34 +00:00			`complete filename or directory.*`

			`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 06:56:56 +00: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 18:00:08 +00: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 06:56:56 +00: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 18:00:08 +00: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 06:56:56 +00:00
			`~~~html`
			`<!DOCTYPE html>`
			`<html>`
			`<head>`
			`<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.