Hugo PaperMod - Slug and URL

Differences, Functions, and Usage of slug and url in Hugo Markdown Front Matter.

In Hugo, both slug and url control the path and access address of a post, but they serve different purposes.

title: 'Hugo PaperMod - Slug和URL'
date: ''
slug: ''
url: 'hugo-papermod/slug-and-url'
showToc: true
TocOpen: true
enableCopyright: true
comments: true
weight: null
draft: false
enableDonate: true

What is slug?

slug is used to generate a URL-friendly fragment for the post.

It affects the final path of the article but does not change the overall URL structure.

By default, Hugo converts the post title into a lowercase, hyphen-separated slug.

How to Use slug

In the Front Matter (YAML/TOML/JSON) of a Markdown file:

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

Effect：

If the file is content/posts/my-first-post.md, the URL will be:

http://example.com/posts/my-first-post/

Slug modifies the last part of the URL without affecting the folder structure.

What is url?

url allows complete customization of the post’s access path.

If url is specified, Hugo ignores the default structure, slug, and title when generating the URL.

How to Use url?

title: "My First Hugo Post"
url: "/custom-path/my-special-post/"

Effect：

The post will be accessible at:

http://example.com/custom-path/my-special-post/

url overrides the default behavior and completely controls the post’s location.

Key Differences Between slug and url

When to Use slug vs url?

• Use slug when

  • You want a cleaner and shorter URL but still follow Hugo’s default structure.
  • You want to avoid long titles being automatically converted into long URLs.

• Use url when

  • You need full control over the post’s location.
  • You are migrating a blog and need to keep old URLs unchanged.
  • You have SEO requirements for a specific URL structure.

Example Comparison

For a post content/posts/my-post.md, different slug and url configurations will affect the final URL as follows:

title: "My Hugo Guide"
slug: "hugo-guide"
url: "/docs/hugo-guide.html"