hugo/content/content-management/urls.md
Bjørn Erik Pedersen 7d63a23b0c Squashed 'docs/' changes from f887bd7b..1d052b16
1d052b16 Update hosting-on-netlify.md
28b96bec Remove double brackets in Netlify hosting tutorial
373ed38b Update deployment instructions from hugo > 0.20 on Netlify
1bbb41ca Generate static assets on deploy in Nanobox tutorial
816d207f Add missing backtick in templates/views.md
bf88e772 Add nanobox as a deployment option
9c37b4cc Change config's syntax order matching description
d3cb05a7 Fix wrongly named default value of publishDir
4be85c54 Add link to showcase a theme setup via config file
46837195 Init and update of submodules in .gitlab-ci.yml
9e7c2827 Add CSS lang argument to code block
85aad56e Abstract the type in the lookup order
4e1e43e9 Fix broken Pygments url
65b4e79b Correct GitLab project pipelines URL
94af72b5 Fix .Data.Terms usage in taxonomy template example
eb371e52 functions: Fix lang.NumFmt docs
a745cd6c Fix layouts' folder name in template primer
e181e637 Correct typo on GitHub pages guide (#151)
28698500 Remove HTML special chars from Windows install example
96b1f5b5 Remove not needed escape slashes in urls.md
2e05043f Add upgrade instructions using homebrew
2a14624d Fix alias in countrunes.md
5e26bb97 Update docker image for build/publish
01424887 List the internal templates
a3ef5be9 Remove string concatenation from add (math) sample
43d12b44 Fix typo
89bafa49 Change to Asciidoc URI
4e14071e Removes an extra bracket (>) in single-page-templates.md
0938e423 Fix typo in http2 server push blog
fac55121 Fix typo in deployment with rsync tutorial

git-subtree-dir: docs
git-subtree-split: 1d052b16a1290ada12f1e28c7c0c373f86741071
2017-09-05 18:09:40 +02:00

277 lines
11 KiB
Markdown
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

---
title: URL Management
linktitle: URL Management
description: Hugo supports permalinks, aliases, link canonicalization, and multiple options for handling relative vs absolute URLs.
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-03-09
#tags: [aliases,redirects,permalinks,urls]
categories: [content management]
menu:
docs:
parent: "content-management"
weight: 110
weight: 110 #rem
draft: false
aliases: [/extras/permalinks/,/extras/aliases/,/extras/urls/,/doc/redirects/,/doc/alias/,/doc/aliases/]
toc: true
---
## Permalinks
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.
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.
{{% 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/).
{{% /note %}}
For example, if one of your [sections][] is called `post` 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.
### YAML Permalinks Configuration Example
{{< code file="config.yml" copy="false" >}}
permalinks:
post: /:year/:month/:title/
{{< /code >}}
### TOML Permalinks Configuration Example
{{< code file="config.toml" copy="false" >}}
[permalinks]
post = "/:year/:month/:title/"
{{< /code >}}
Only the content under `post/` will have the new URL structure. For example, the file `content/post/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/2013/11/sample-entry/`.
### Permalink Configuration Values
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.
`:year`
: the 4-digit year
`:month`
: the 2-digit month
`:monthname`
: the name of the month
`:day`
: the 2-digit day
`:weekday`
: the 1-digit day of the week (Sunday = 0)
`:weekdayname`
: the name of the day of the week
`:yearday`
: the 1- to 3-digit day of the year
`:section`
: the content's section
`:title`
: the content's title
`:slug`
: the content's slug (or title if no slug is provided in the front matter)
`:filename`
: the content's filename (without extension)
## 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: Aliases
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 filed in TOML and YAML front matter, respectively.
#### TOML Front Matter
{{< code file="content/posts/my-awesome-post.md" copy="false" >}}
+++
aliases = [
"/posts/my-original-url/",
"/2010/01/01/even-earlier-url.html"
]
+++
{{< /code >}}
#### YAML Front Matter
{{< code file="content/posts/my-awesome-post.md" copy="false" >}}
---
aliases:
- /posts/my-original-url/
- /2010/01/01/even-earlier-url.html
---
{{< /code >}}
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-blog-post/`.
### Example: Aliases in Multilingual
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.
In `/posts/my-new-post.es.md`:
```
---
aliases:
- /es/posts/my-original-post/
---
```
### 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:
```
---
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:`
```
<!DOCTYPE html>
<html>
<head>
<title>https://example.com/posts/my-intended-url</title>
<link rel="canonical" href="https://example.com/posts/my-intended-url"/>
<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"/>
</head>
</html>
```
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 they they should not crawl and index your new alias page.
### 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
`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:
```
content/posts/_index.md
=> example.com/posts/index.html
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 use the `--uglyURLs=true` [flag from the command line][usage] with `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.
```
.
└── content
└── about
| └── _index.md // <- https://example.com/about/
├── post
| ├── firstpost.md // <- https://example.com/post/firstpost/
| ├── happy
| | └── ness.md // <- https://example.com/post/happy/ness/
| └── secondpost.md // <- https://example.com/post/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`:
```
.
└── content
└── about
| └── _index.md // <- https://example.com/about/index.html
├── post
| ├── firstpost.md // <- https://example.com/post/firstpost.html
| ├── happy
| | └── ness.md // <- https://example.com/post/happy/ness.html
| └── secondpost.md // <- https://example.com/post/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.
```
hugo config | grep -i canon
```
Or, if you are on Windows and do not have `grep` installed:
```
hugo config | FINDSTR /I canon
```
## Override URLS with 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].
## 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 `/post/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/