HUGO

  • News
  • Docs
  • Themes
  • Showcase
  • Community
  • GitHub
Star

What's on this Page

  • Overview
  • Front matter
  • Site configuration
  • Aliases
CONTENT MANAGEMENT

URL Management

Control the structure and appearance of URLs through front matter entries and settings in your site configuration.

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. The slug value does not affect section pages.

content/posts/post-1.md
     
---
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.

With this front matter:

content/posts/post-1.md
     
---
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:

content/posts/post-1.md
     
---
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

In a monolingual site, a url value with or without a leading slash is relative to the baseURL.

In a multilingual site:

  • A url value with a leading slash is relative to the baseURL.
  • A url value without a leading slash is relative to the baseURL plus the language prefix.
Site typeFront matter urlResulting URL
monolingual/abouthttps://example.org/about/
monolingualabouthttps://example.org/about/
multilingual/abouthttps://example.org/about/
multilingualabouthttps://example.org/de/about/

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

Site configuration

Permalinks

In your site configuration, set a URL pattern for regular pages within a top-level section. This is recursive, affecting descendant regular pages.

The permalinks defined in your site configuration do not apply to section pages. To adjust the URL for section pages, set url in front matter.

Examples

With this content structure:

content/
├── posts/
│   ├── _index.md
│   ├── post-1.md
│   └── post-2.md
└── _index.md

Create a date-based hierarchy, recursively, for regular pages within the posts section:

config.
     
posts: /posts/:year/:month/:title/
posts = '/posts/:year/:month/:title/'
{
   "posts": "/posts/:year/:month/:title/"
}

The structure of the published site will be:

public/
├── posts/
│   ├── 2023/
│   │   └── 03/
│   │       ├── post-1/
│   │       │   └── index.html
│   │       └── post-2/
│   │           └── index.html
│   └── index.html
├── favicon.ico
└── index.html

To create a date-based hierarchy for regular pages in the content root:

config.
     
/: /:year/:month/:title/
'/' = '/:year/:month/:title/'
{
   "/": "/:year/:month/:title/"
}

A URL pattern defined for the content root is not recursive.

Use the same approach with taxonomies. For example, to omit the taxonomy segment of the URL:

config.
     
tags: /:title/
tags = '/:title/'
{
   "tags": "/:title/"
}

Front matter url values take precedence over URL patterns defined in permalinks.

Tokens

Use these tokens when defining the URL pattern. The date field in front matter determines the value of time-related tokens.

: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
: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.
:title
the content’s title
:slug
the content’s slug (or title if no slug is provided in the front matter)
:slugorfilename
the content’s slug (or filename if no slug is provided in the front matter)
:filename
the content’s filename (without extension)

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

config.
     
permalinks:
  posts: /:06/:1/:2/:title/
[permalinks]
  posts = '/:06/:1/:2/:title/'
{
   "permalinks": {
      "posts": "/:06/:1/:2/:title/"
   }
}

Appearance

The appearance of a URL is either ugly or pretty.

TypePathURL
uglycontent/about.mdhttps://example.org/about.html
prettycontent/about.mdhttps://example.org/about/

By default, Hugo produces pretty URLs. To generate ugly URLs, change your site configuration:

config.
     
uglyURLs: true
uglyURLs = true
{
   "uglyURLs": true
}

Post-processing

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

Canonical URLs

This is a legacy configuration option, superseded by template functions and markdown render hooks, and will likely be removed in a future release.

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:

config.
     
canonifyURLs: true
canonifyURLs = true
{
   "canonifyURLs": true
}

Relative URLs

Do not enable this option unless you are creating a serverless site, navigable via the file system.

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:

config.
     
relativeURLs: true
relativeURLs = true
{
   "relativeURLs": true
}

Aliases

Create redirects from old URLs to new URLs with aliases:

  • An alias with a leading slash is relative to the baseURL
  • An alias without a leading slash is relative to the current directory

Examples

Change the file name of an existing page, and create an alias from the previous URL to the new URL:

content/posts/new-file-name.md.
     
aliases:
- /posts/previous-file-name
aliases = ['/posts/previous-file-name']
{
   "aliases": [
      "/posts/previous-file-name"
   ]
}

Each of these directory-relative aliases is equivalent to the site-relative alias above:

  • previous-file-name
  • ./previous-file-name
  • ../posts/previous-file-name

You can create more than one alias to the current page:

content/posts/new-file-name.md.
     
aliases:
- previous-file-name
- original-file-name
aliases = ['previous-file-name', 'original-file-name']
{
   "aliases": [
      "previous-file-name",
      "original-file-name"
   ]
}

In a multilingual site, use a directory-relative alias, or include the language prefix with a site-relative alias:

content/posts/new-file-name.de.md.
     
aliases:
- /de/posts/previous-file-name
aliases = ['/de/posts/previous-file-name']
{
   "aliases": [
      "/de/posts/previous-file-name"
   ]
}

How Aliases Work

Using the first example above, Hugo generates the following site structure:

public/
├── posts/
│   ├── new-file-name/
│   │   └── index.html
│   ├── previous-file-name/
│   │   └── index.html
│   └── index.html
└── index.html

The alias from the previous URL to the new URL is a client-side redirect:

posts/previous-file-name/index.html
<!DOCTYPE html>
<html lang="en-us">
  <head>
    <title>https://example.org/posts/new-file-name/</title>
    <link rel="canonical" href="https://example.org/posts/new-file-name/">
    <meta name="robots" content="noindex">
    <meta charset="utf-8">
    <meta http-equiv="refresh" content="0; url=https://example.org/posts/new-file-name/">
  </head>
</html>

Collectively, the elements in the head section:

  • Tell search engines that the new URL is canonical
  • Tell search engines not to index the previous URL
  • Tell the browser to redirect to the new URL

Hugo renders alias files before rendering pages. A new page with the previous file name will overwrite the alias, as expected.

Customize

Create a new template (layouts/alias.html) to customize the content of the alias files. The template receives the following context:

Permalink
the link to the page being aliased
Page
the Page data for the page being aliased

See Also

  • Content Organization
  • urlquery
  • Sitemap Templates
  • querify
  • safeURL
  • About Hugo
    • Overview
    • Hugo's Security Model
    • Hugo and GDPR
    • What is Hugo
    • Hugo Features
    • The Benefits of Static
    • License
  • Installation
    • Installation overview
    • macOS
    • Linux
    • Windows
    • BSD
  • Getting Started
    • Get Started Overview
    • Quick Start
    • Basic usage
    • Directory Structure
    • Configuration
    • External Learning Resources
  • Hugo Modules
    • Hugo Modules Overview
    • Configure Modules
    • Use Hugo Modules
    • Theme Components
  • Content Management
    • Content Management Overview
    • Organization
    • Page Bundles
    • Content Formats
    • Diagrams
    • Front Matter
    • Build Options
    • Page Resources
    • Image Processing
    • Shortcodes
    • Related Content
    • Sections
    • Content Types
    • Archetypes
    • Taxonomies
    • Summaries
    • Links and Cross References
    • URL Management
    • Menus
    • Static Files
    • Table of Contents
    • Comments
    • Multilingual
    • Syntax Highlighting
  • Templates
    • Templates Overview
    • Templating
    • Template Lookup Order
    • Custom Output Formats
    • Base Templates and Blocks
    • Render Hooks
    • List Templates
    • Homepage Template
    • Section Templates
    • Taxonomy Templates
    • Single Page Templates
    • Content View Templates
    • Data Templates
    • Partial Templates
    • Shortcode Templates
    • Local File Templates
    • 404 Page
    • Menu Templates
    • Pagination
    • RSS Templates
    • Sitemap Templates
    • Robots.txt
    • Internal Templates
    • Template Debugging
  • Functions
    • Functions Quick Reference
    • .AddDate
    • .Format
    • .Get
    • .GetPage
    • .HasMenuCurrent
    • .IsMenuCurrent
    • .Param
    • .Render
    • .RenderString
    • .Scratch
    • .Store
    • .Unix
    • absLangURL
    • absURL
    • after
    • anchorize
    • append
    • apply
    • base64
    • chomp
    • complement
    • cond
    • countrunes
    • countwords
    • crypto.FNV32a
    • default
    • delimit
    • dict
    • duration
    • echoParam
    • emojify
    • eq
    • errorf and warnf
    • fileExists
    • findRE
    • first
    • float
    • ge
    • getenv
    • group
    • gt
    • hasPrefix
    • highlight
    • hmac
    • htmlEscape
    • htmlUnescape
    • hugo
    • humanize
    • i18n
    • Image Filters
    • in
    • index
    • int
    • intersect
    • isset
    • jsonify
    • lang
    • lang.Merge
    • last
    • le
    • len
    • lower
    • lt
    • markdownify
    • Math
    • md5
    • merge
    • ne
    • now
    • os.Stat
    • partialCached
    • path.Base
    • path.BaseName
    • path.Clean
    • path.Dir
    • path.Ext
    • path.Join
    • path.Split
    • plainify
    • pluralize
    • print
    • printf
    • println
    • querify
    • range
    • readDir
    • readFile
    • ref
    • reflect.IsMap
    • reflect.IsSlice
    • relLangURL
    • relref
    • relURL
    • replace
    • replaceRE
    • safeCSS
    • safeHTML
    • safeHTMLAttr
    • safeJS
    • safeURL
    • seq
    • sha
    • shuffle
    • singularize
    • site
    • slice
    • slicestr
    • sort
    • split
    • string
    • strings.Contains
    • strings.ContainsAny
    • strings.Count
    • strings.FirstUpper
    • strings.HasSuffix
    • strings.Repeat
    • strings.RuneCount
    • strings.TrimLeft
    • strings.TrimPrefix
    • strings.TrimRight
    • strings.TrimSuffix
    • substr
    • symdiff
    • templates.Exists
    • time
    • time.Format
    • time.ParseDuration
    • title
    • transform.Unmarshal
    • trim
    • truncate
    • union
    • uniq
    • upper
    • urlize
    • urlquery
    • urls.Parse
    • where
    • with
  • Variables
    • Variables Overview
    • Site Variables
    • Page Variables
    • Shortcode Variables
    • Pages Methods
    • Taxonomy Variables
    • File Variables
    • Menu Variables
    • Git Variables
    • Sitemap Variables
  • Hugo Pipes
    • Hugo Pipes Overview
    • Hugo Pipes
    • Sass / SCSS
    • PostProcess
    • PostCSS
    • JavaScript Building
    • Babel
    • Asset minification
    • Asset bundling
    • Fingerprinting and SRI
    • Resource from Template
    • Resource from String
  • CLI
  • Troubleshooting
    • Troubleshoot
    • FAQ
    • Build Performance
  • Tools
    • Developer Tools Overview
    • Migrations
    • Starter Kits
    • Frontends
    • Editor Plug-ins
    • Search
    • Other Projects
  • Hosting & Deployment
    • Hosting & Deployment Overview
    • Hugo Deploy
    • Host on 21YunBox
    • Host on AWS Amplify
    • Host on Azure Static Web Apps
    • Host on Netlify
    • Host on Render
    • Host on Firebase
    • Host on GitHub
    • Host on GitLab
    • Host on KeyCDN
    • Host on Cloudflare Pages
    • Deployment with Rsync
    • Deployment with Rclone
    • Hosting on Azure Static Web Apps
  • Contribute
    • Contribute to Hugo
    • Development
    • Documentation
    • Themes
  • Maintenance
Last updated: March 15, 2023: Clarify usage of slug in front matter (#1998) (afb582a8)
Improve this page
By the Hugo Authors
Hugo Logo
  • File an Issue
  • Get Help
  • Discuss Source Code
  • @GoHugoIO
  • @spf13
  • @bepsays

Netlify badge

 

Hugo Sponsors

 

The Hugo logos are copyright © Steve Francia 2013–2023.

The Hugo Gopher is based on an original work by Renée French.

  • News
  • Docs
  • Themes
  • Showcase
  • Community
  • GitHub
  • About Hugo
  • Installation
  • Getting Started
  • Hugo Modules
  • Content Management
  • Templates
  • Functions
  • Variables
  • Hugo Pipes
  • CLI
  • Troubleshooting
  • Tools
  • Hosting & Deployment
  • Contribute
  • Maintenance