Decouple slug inference from date resolution when using :filename in front matter config

[maxkapur]

Hugo bug report

Summary

When a post has a date given in both its filename and frontmatter, hugo fails to parse the slug from the filename.

Steps to reproduce

I created a repo here that reproduces the issue: https://github.com/maxkapur/hugo-date-slug-repro

To summarize, consider a hugo.toml configured to extract dates from filename, but allow explicit override in frontmatter:

[frontmatter]
date = ["date", ":filename"]

Create content/posts/2026-05-24-bar.md with empty frontmatter. As expected, the .Date is set to 2025-05-24T00:00:00 and .Slug is set to just bar.

Now add a second post content/posts/2026-05-24-foo.md, but this time also set the date in frontmatter to 2025-05-24T11:59:59 (providing an explicit time, e.g. to force a certain sort order).

In this case, the .Date field is correctly populated with the 11:59:59 version, but .Slug is nil.

Here's the CSV output of hugo list all which may clarify what's going on:

https://github.com/maxkapur/hugo-date-slug-repro/blob/main/hugo_list_all.csv

Why I believe this is a bug

From the source code, it's obvious why this happens—if given an explicit date, then dateAndSlugFromBaseFilename() never gets called and thus no slug is ever inferred.

In my opinion, this is a bug, or at least surprising behavior. The frontmatter.date = [":filename"] date config silently triggers slug inference behavior that users (or at least users like me 😅) could come to rely on. In particular, this behavior generates surprising permalinks—in the example above:

• path content/posts/2026-05-24-foo.md has permalink https://example.org/posts/2026-05-24-foo/
• path content/posts/2026-05-24-bar.md has permalink https://example.org/posts/bar/

And a markdown link like [whatever](/posts/2026-05-24-bar/) (which makes perfect sense looking at the file tree) from another post will 404.

This date/slug interaction is not discussed in the documentation on frontmatter dates, slugs, or URLs. It just happens.

Possible fixes

• New config option frontmatter.slug that allows users to control interaction with frontmatter.date (maximally preserves backwards compat)
• If a filename begins with a date, strip it before inferring the slug if frontmatter.date = [":filename"] is set (even if frontmatter also has an explicit date)

What version of Hugo are you using (hugo version)?

I reproduced with the latest snap version:

$ hugo version
hugo v0.162.0-076dfe13d0f789e3d9586b192f8f7f3329c26990+extended linux/amd64 BuildDate=2026-05-26T13:53:44Z VendorInfo=snap:0.162.0

As well as the latest Docker hugomods/hugo:nightly image:

$ docker run --rm -it -v (pwd):/repro hugomods/hugo:nightly version
hugo v0.163.0-DEV-28d882ab704e5060687a61210ae20b0027595705+extended+withdeploy linux/amd64 BuildDate=2026-05-29T09:28:27Z VendorInfo=hugomods

Does this issue reproduce with the latest release?

Yes

[jmooring]

I've updated the relevant documentation to describe the current behavior.

Based on 68bf1511f it looks like the :filename token was created to ease migrations from Jekyll, where the date and slug are derived from the filename independently. In Jekyll, a front matter date field overrides the date but the slug is derived from the filename unless overridden by a front matter slug field. Unlike Jekyll, Hugo's current behavior skips slug inference entirely when an earlier entry in the date config wins.

Although I don't like the idea of adding yet another config setting, I dislike complicating the :filename token's behavior even more.

If we want to do this, the default configuration that would decouple date from slug would look like this:

[frontmatter]
  date = ['date', 'publishdate', 'pubdate', 'published', 'lastmod', 'modified']
  expiryDate = ['expirydate', 'unpublishdate']
  lastmod = [':git', 'lastmod', 'modified', 'date', 'publishdate', 'pubdate', 'published']
  publishDate = ['publishdate', 'pubdate', 'published', 'date']
  slug = ['slug']

And users could get the Jekyll behavior like this:

[frontmatter]
  date = ['date', ':filename']
  slug = ['slug', ':filename']

[maxkapur]

Thank you! Appreciate the new documentation.

I agree with the concern about bloating the config options and admit I have the biased perspective of someone who is in the midst of a Jekyll migration--but I really like your proposal for the frontmatter.slug key.

Even in a non-Jekyll context, some folks might want to put dates in filenames anyway so that they sort correctly in the file browser. This config option provides separate, explicit control over whether that means the date is part of the slug and/or URL too.