URL management

Overview

By default, when Hugo renders a page, the resulting URL matches the file path within the content directory. For example:

content/posts/post-1.md → https://example.org/posts/post-1/

You can change the structure and appearance of URLs with front matter values and site configuration options.

Front matter

slug

Set the slug in front matter to override the last segment of the path. This front matter field is not applicable to home, section, taxonomy, or term pages.

---
slug: my-first-post
title: My First Post
---

+++
slug = 'my-first-post'
title = 'My First Post'
+++

{
   "slug": "my-first-post",
   "title": "My First Post"
}

The resulting URL will be:

https://example.org/posts/my-first-post/

url

Set the url in front matter to override the entire path. Use this with either regular pages or section pages.

If you set both slug and url in front matter, the url value takes precedence.

Include a colon

If you need to include a colon in the url front matter field, escape it with backslash characters. Use one backslash if you wrap the string within single quotes, or use two backslashes if you wrap the string within double quotes. With YAML front matter, use a single backslash if you omit quotation marks.

For example, with this front matter:

---
title: Example
url: 'my\:example'
---

+++
title = 'Example'
url = 'my\:example'
+++

{
   "title": "Example",
   "url": "my\\:example"
}

The resulting URL will be:

https://example.org/my:example/

As described above, this will fail on Windows because the colon (:) is a reserved character.

File extensions

With this front matter:

---
title: My First Article
url: articles/my-first-article
---

+++
title = 'My First Article'
url = 'articles/my-first-article'
+++

{
   "title": "My First Article",
   "url": "articles/my-first-article"
}

The resulting URL will be:

https://example.org/articles/my-first-article/

If you include a file extension:

---
title: My First Article
url: articles/my-first-article.html
---

+++
title = 'My First Article'
url = 'articles/my-first-article.html'
+++

{
   "title": "My First Article",
   "url": "articles/my-first-article.html"
}

The resulting URL will be:

https://example.org/articles/my-first-article.html

Leading slashes

With monolingual sites, url values with or without a leading slash are relative to the baseURL. With multilingual sites, url values with a leading slash are relative to the baseURL, and url values without a leading slash are relative to the baseURL plus the language prefix.

Permalinks tokens in front matter

You can also use tokens when setting the url value. This is typically used in cascade sections:

---
cascade:
- url: /:sections[last]/:slug
title: Bar
---

+++
title = 'Bar'
[[cascade]]
  url = '/:sections[last]/:slug'
+++

{
   "cascade": [
      {
         "url": "/:sections[last]/:slug"
      }
   ],
   "title": "Bar"
}

Use any of these tokens:

:year

The 4-digit year as defined in the front matter date field.

:month

The 2-digit month as defined in the front matter date field.

:monthname

The name of the month as defined in the front matter date field.

:day

The 2-digit day as defined in the front matter date field.

:weekday

The 1-digit day of the week as defined in the front matter date field (Sunday = 0).

:weekdayname

The name of the day of the week as defined in the front matter date field.

:yearday

The 1- to 3-digit day of the year as defined in the front matter date field.

:section

The content’s section.

:sectionslug

New in v0.149.0

The content’s section using slugified section name. The slugified section name is the slug as defined in front matter, else the title as defined in front matter, else the automatic title.

:sections

The content’s sections hierarchy. 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.

:sectionslugs

New in v0.149.0

The content’s sections hierarchy using slugified section names. The slugified section name is the slug as defined in front matter, else the title as defined in front matter, else the automatic title. You can use a selection of the sections using slice syntax: :sectionslugs[1:] includes all but the first, :sectionslugs[:last] includes all but the last, :sectionslugs[last] includes only the last, :sectionslugs[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.

:title

The title as defined in front matter, else the automatic title. Hugo generates titles automatically for section, taxonomy, and term pages that are not backed by a file.

:slug

The slug as defined in front matter, else the title as defined in front matter, else the automatic title. Hugo generates titles automatically for section, taxonomy, and term pages that are not backed by a file.

:filename

The content’s file name without extension, applicable to the page page kind.

Deprecated in v0.144.0

The :filename token has been deprecated. Use :contentbasename instead.

:slugorfilename

The slug as defined in front matter, else the content’s file name without extension, applicable to the page page kind.

Deprecated in v0.144.0

The :slugorfilename token has been deprecated. Use :slugorcontentbasename instead.

:contentbasename

New in v0.144.0

The content base name.

:slugorcontentbasename

New in v0.144.0

The slug as defined in front matter, else the content base name.

For time-related values, you can also use the layout string components defined in Go’s time package. For example:

permalinks:
  posts: /:06/:1/:2/:title/

[permalinks]
  posts = '/:06/:1/:2/:title/'

{
   "permalinks": {
      "posts": "/:06/:1/:2/:title/"
   }
}

Site configuration

Permalinks

See configure permalinks.

Appearance

See configure ugly URLs.

Post-processing

Hugo provides two mutually exclusive configuration options to alter URLs after it renders a page.

Canonical URLs

If enabled, Hugo performs a search and replace after it renders the page. It searches for site-relative URLs (those with a leading slash) associated with action, href, src, srcset, and url attributes. It then prepends the baseURL to create absolute URLs.

<a href="/about"> → <a href="https://example.org/about/">
<img src="/a.gif"> → <img src="https://example.org/a.gif">

This is an imperfect, brute force approach that can affect content as well as HTML attributes. As noted above, this is a legacy configuration option that will likely be removed in a future release.

To enable:

canonifyURLs: true

canonifyURLs = true

{
   "canonifyURLs": true
}

Relative URLs

If enabled, Hugo performs a search and replace after it renders the page. It searches for site-relative URLs (those with a leading slash) associated with action, href, src, srcset, and url attributes. It then transforms the URL to be relative to the current page.

For example, when rendering content/posts/post-1:

<a href="/about"> → <a href="../../about">
<img src="/a.gif"> → <img src="../../a.gif">

This is an imperfect, brute force approach that can affect content as well as HTML attributes. As noted above, do not enable this option unless you are creating a serverless site.

To enable:

relativeURLs: true

relativeURLs = true

{
   "relativeURLs": true
}

Aliases

Aliases allow you to redirect old URLs to new URLs. This is essential for preventing broken links and ensuring that existing bookmarks or external links continue to function when you rename or move content.

Defining aliases

To add redirects to a page, list the previous paths in the aliases field in your front matter. Hugo resolves these to server-relative paths during the build process, accounting for the baseURL and content dimension prefixes such as language, role, or version.

---
aliases:
- /old-url
- old-name
- ../old/path
date: '2025-02-02'
title: Example 1
---

+++
aliases = ['/old-url', 'old-name', '../old/path']
date = 2025-02-02
title = 'Example 1'
+++

{
   "aliases": [
      "/old-url",
      "old-name",
      "../old/path"
   ],
   "date": "2025-02-02",
   "title": "Example 1"
}

As shown in the example above, you can use site-relative paths or page-relative paths. Page-relative paths can also include directory traversal. Using the file content/examples/example-1.en.md as a reference point, here is how Hugo interprets those different path types:

Redirection methods

There are two ways to implement aliases depending on your hosting environment and preferences: client-side redirection and server-side redirection.

Client-side redirection

By default, Hugo uses client-side redirection, generating a small HTML file for every alias. This file contains a meta http-equiv="refresh" tag that instructs the browser to navigate to the new URL. This approach is portable across all hosting providers.

When using this method, Hugo creates a physical directory and an index.html file at each alias location. For example, if a page at content/posts/new.md has a page-relative alias of old-path, a file is generated at public/posts/old-path/index.html.

Unless you provide a custom layout, Hugo uses its embedded alias template to generate the redirect files:

<!DOCTYPE html>
<html lang="{{ site.Language.LanguageCode }}">
  <head>
    <title>{{ .Permalink }}</title>
    {{ with .OutputFormats.Canonical }}<link rel="{{ .Rel }}" href="{{ .Permalink }}">{{ end }}
    <meta charset="utf-8">
    <meta http-equiv="refresh" content="0; url={{ .Permalink }}">
  </head>
</html>

To override this, create a file named alias.html in your layouts directory. This custom template has access to the following context:

Permalink

(string) The absolute URL of the destination page.

Page

(page.Page) The full Page object of the destination.

Server-side redirection

Alternatively, you can implement server-side redirection by using the Aliases method on a Page object to generate a single configuration file that the web server processes. This method is more efficient because the redirect happens at the HTTP header level before any page content is processed, whereas a meta refresh requires the browser to download and parse the HTML body before acting. Additionally, server-side redirection improves build and deployment times because Hugo doesn’t need to write a physical directory and HTML file for every alias.

To implement this, you typically create a single template to generate the necessary rules for your specific host or server. Common examples include:

• A _redirects file for hosting services such as Cloudflare, GitLab Pages, and Netlify.
• An .htaccess file for web servers such as Apache and LiteSpeed.

See the Aliases method page for a complete example of how to iterate through pages to generate these rules.

If you implement server-side redirects, you should disable the generation of individual HTML files by setting disableAliases to true in your site configuration. This setting only prevents the generation of the physical HTML files; the Aliases method on a Page object remains available for use in your configuration templates.