1--- 2title: URL Management 3linktitle: URL Management 4description: Hugo supports permalinks, aliases, link canonicalization, and multiple options for handling relative vs absolute URLs. 5date: 2017-02-01 6publishdate: 2017-02-01 7lastmod: 2017-03-09 8keywords: [aliases,redirects,permalinks,urls] 9categories: [content management] 10menu: 11 docs: 12 parent: "content-management" 13 weight: 110 14weight: 110 #rem 15draft: false 16aliases: [/extras/permalinks/,/extras/aliases/,/extras/urls/,/doc/redirects/,/doc/alias/,/doc/aliases/] 17toc: true 18--- 19 20## Permalinks 21 22The 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. 23 24The `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. 25 26{{% note "Default Publish and Content Folders" %}} 27These 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/). 28{{% /note %}} 29 30For 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. 31 32### Permalinks Configuration Example 33 34{{< code-toggle file="config" copy="false" >}} 35permalinks: 36 posts: /:year/:month/:title/ 37{{< /code-toggle >}} 38 39Only 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/`. 40 41To configure the `permalinks` option for pages in the "root" section, use **/** as the key: 42 43{{< code-toggle file="config" copy="false" >}} 44permalinks: 45 /: /:year/:month/:filename/ 46{{< /code-toggle >}} 47 48If the standard date-based permalink configuration does not meet your needs, you can also format URL segments using [Go time formatting directives](https://golang.org/pkg/time/#Time.Format). For example, a URL structure with two digit years and month and day digits without zero padding can be accomplished with: 49 50{{< code-toggle file="config" copy="false" >}} 51permalinks: 52 posts: /:06/:1/:2/:title/ 53{{< /code-toggle >}} 54 55You 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`. 56 57### Permalink Configuration Values 58 59The 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. 60 61`:year` 62: the 4-digit year 63 64`:month` 65: the 2-digit month 66 67`:monthname` 68: the name of the month 69 70`:day` 71: the 2-digit day 72 73`:weekday` 74: the 1-digit day of the week (Sunday = 0) 75 76`:weekdayname` 77: the name of the day of the week 78 79`:yearday` 80: the 1- to 3-digit day of the year 81 82`:section` 83: the content's section 84 85`:sections` 86: the content's sections hierarchy. {{< new-in "0.83.0" >}} Since Hugo 0.83 you can use a selection of the sections using _slice syntax_: `:sections[1:]` includes all but the first, `:sections[:last]` includes all but the last, `:sections[last]` includes only the last, `:sections[1:2]` includes section 2 and 3. Note that this slice access will not throw any out-of-bounds errors, so you don't have to be exact. 87 88`:title` 89: the content's title 90 91`:slug` 92: the content's slug (or title if no slug is provided in the front matter) 93 94`:filename` 95: the content's filename (without extension) 96 97Additionally, a Go time format string prefixed with `:` may be used. 98 99## Aliases 100 101Aliases can be used to create redirects to your page from other URLs. 102 103Aliases comes in two forms: 104 1051. Starting with a `/` meaning they are relative to the `BaseURL`, e.g. `/posts/my-blogpost/` 1062. 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). 107 108### Example: Aliases 109 110Let'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. 111 112#### TOML Front Matter 113 114{{< code file="content/posts/my-awesome-post.md" copy="false" >}} 115+++ 116aliases = [ 117 "/posts/my-original-url/", 118 "/2010/01/01/even-earlier-url.html" 119] 120+++ 121{{< /code >}} 122 123#### YAML Front Matter 124 125{{< code file="content/posts/my-awesome-post.md" copy="false" >}} 126--- 127aliases: 128 - /posts/my-original-url/ 129 - /2010/01/01/even-earlier-url.html 130--- 131{{< /code >}} 132 133Now 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/`. 134 135### Example: Aliases in Multilingual 136 137On [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. 138 139In `/posts/my-new-post.es.md`: 140 141``` 142--- 143aliases: 144 - /es/posts/my-original-post/ 145--- 146``` 147 148From 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/` 149 150### How Hugo Aliases Work 151 152When 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. 153 154For example, a content file at `posts/my-intended-url.md` with the following in the front matter: 155 156``` 157--- 158title: My New post 159aliases: [/posts/my-old-url/] 160--- 161``` 162 163Assuming 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: 164 165``` 166<!DOCTYPE html> 167<html> 168 <head> 169 <title>https://example.com/posts/my-intended-url</title> 170 <link rel="canonical" href="https://example.com/posts/my-intended-url"/> 171 <meta name="robots" content="noindex"> 172 <meta http-equiv="content-type" content="text/html; charset=utf-8"/> 173 <meta http-equiv="refresh" content="0; url=https://example.com/posts/my-intended-url"/> 174 </head> 175</html> 176``` 177 178The `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 crawl and index your new alias page. 179 180### Customize 181You may customize this alias page by creating an `alias.html` template in the 182layouts folder of your site (i.e., `layouts/alias.html`). In this case, the data passed to the template is 183 184`Permalink` 185: the link to the page being aliased 186 187`Page` 188: the Page data for the page being aliased 189 190### Important Behaviors of Aliases 191 1921. Hugo makes no assumptions about aliases. They also do not change based 193on your UglyURLs setting. You need to provide absolute paths to your web root 194and the complete filename or directory. 1952. Aliases are rendered *before* any content are rendered and therefore will be overwritten by any content with the same location. 196 197## Pretty URLs 198 199Hugo'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. 200 201The following demonstrates the concept: 202 203``` 204content/posts/_index.md 205=> example.com/posts/ 206content/posts/post-1.md 207=> example.com/posts/post-1/ 208``` 209 210## Ugly URLs 211 212If 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`. 213 214If 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. 215 216See [Content Organization][contentorg] for more details on paths. 217 218``` 219. 220└── content 221 └── about 222 | └── _index.md // <- https://example.com/about/ 223 ├── posts 224 | ├── firstpost.md // <- https://example.com/posts/firstpost/ 225 | ├── happy 226 | | └── ness.md // <- https://example.com/posts/happy/ness/ 227 | └── secondpost.md // <- https://example.com/posts/secondpost/ 228 └── quote 229 ├── first.md // <- https://example.com/quote/first/ 230 └── second.md // <- https://example.com/quote/second/ 231``` 232 233Here's the same organization run with `hugo --uglyURLs`: 234 235``` 236. 237└── content 238 └── about 239 | └── _index.md // <- https://example.com/about.html 240 ├── posts 241 | ├── firstpost.md // <- https://example.com/posts/firstpost.html 242 | ├── happy 243 | | └── ness.md // <- https://example.com/posts/happy/ness.html 244 | └── secondpost.md // <- https://example.com/posts/secondpost.html 245 └── quote 246 ├── first.md // <- https://example.com/quote/first.html 247 └── second.md // <- https://example.com/quote/second.html 248``` 249 250 251## Canonicalization 252 253By 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`. 254 255By 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`. 256 257Benefits 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. 258 259Benefits 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. 260 261{{% note "`canonifyURLs` default change" %}} 262In 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. 263{{% /note %}} 264 265To find out the current value of `canonifyURLs` for your website, you may use the handy `hugo config` command added in v0.13. 266 267``` 268hugo config | grep -i canon 269``` 270 271Or, if you are on Windows and do not have `grep` installed: 272 273``` 274hugo config | FINDSTR /I canon 275``` 276 277## Set URL in Front Matter 278 279In addition to specifying permalink values in your site configuration for different content sections, Hugo provides even more granular control for individual pieces of content. 280 281Both `slug` and `url` can be defined in individual front matter. For more information on content destinations at build time, see [Content Organization][contentorg]. 282 283From 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: 284 285```markdown 286--- 287title: "Custom URL!" 288url: "/jp/custom/foo" 289--- 290``` 291 292```markdown 293--- 294title: "Custom URL!" 295url: "custom/foo" 296--- 297``` 298 299 300## Relative URLs 301 302By 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. 303 304Setting `relativeURLs` to `true` in your [site configuration][config] will cause Hugo to rewrite all relative URLs to be relative to the current content. 305 306For example, if your `/posts/first/` page contains a link to `/about/`, Hugo will rewrite the URL to `../../about/`. 307 308[config]: /getting-started/configuration/ 309[contentorg]: /content-management/organization/ 310[front matter]: /content-management/front-matter/ 311[multilingual]: /content-management/multilingual/ 312[sections]: /content-management/sections/ 313[usage]: /getting-started/usage/ 314