RFC: Support Datetime-only Filenames for Content Pages

Feature requests
1

RFC: Support Datetime-only Filenames for Content Pages

Summary

Currently, Zola expects content page filenames with date prefixes to also include a slug, e.g. YYYY-MM-DD-title.md. This proposal adds support for “datetime-only” filenames of the form YYYY-MM-DD.md, enabling users to create pages identified solely by date, such as news articles or changelogs, without requiring a redundant slug.

Motivation

Many Zola users create dated content—such as news, releases, or daily logs—where the filename’s date alone is a sufficient and unique identifier. Requiring a slug after the date results in filenames like 2025-08-04.md being rejected or mishandled, forcing users to create unnecessary (and sometimes arbitrary) slugs.

Supporting YYYY-MM-DD.md as a valid filename:

  • Reduces friction for date-based content workflows.
  • Makes Zola easier to use for changelogs, journals, news feeds, and similar sites.
  • Aligns with common patterns in other static site generators and blogs, which often allow date-only filenames.

Guide-level Explanation

Before this change:

  • Zola expects a filename like 2025-08-04-title.md for a dated content page.
  • If the filename is 2025-08-04.md, Zola ignores the date and treats it as a regular page without a date.

After this change:

  • Zola will also recognize files named 2025-08-04.md (or any valid date) as dated content pages.
  • The date will be parsed from the filename, and the slug will default to an empty string or the date itself.
  • Existing filename patterns (YYYY-MM-DD-title.md) continue to work as before.
  • This change is fully backward compatible.

Example:

content/news/
  2025-08-04.md      ← now recognized as a news article for 2025-08-04
  2025-08-03-post.md ← also recognized (as before)

Reference-level Explanation

  • The filename regex is updated to allow matching YYYY-MM-DD.md in addition to YYYY-MM-DD-title.md.

  • If the filename matches only the date (no slug), the slug field is set to an empty string (or the date, if preferable).

  • Internal logic ensures these date-only pages are parsed and handled like other dated content, including sorting, permalinks, and template access.

  • Error messages are updated to reflect the new accepted pattern.

Patch summary:

  • Adjusted the regex in components/content/page.rs to optionally match the slug.

  • Updated error handling to accept date-only matches.

  • No changes to front matter, sorting, or templates are needed.

Drawbacks

  • Potential ambiguity if users want both 2025-08-04.md and 2025-08-04-something.md in the same section. However, as dates are often unique in this context, this is rare.

  • Slightly more complexity in the filename parsing logic.

Rationale and Alternatives

Alternatives considered:

  • Keep requiring a slug: This is more restrictive and less ergonomic for common use-cases.

  • Use front matter only for dates: This loses the convenience of filename-driven dates, which is well-established and user-friendly.

Rationale for proposed approach:

  • The change is backward compatible.

  • It improves usability for date-driven content sites.

  • It is consistent with practices in other static site generators (e.g. Jekyll, Hugo).

Unresolved Questions

  • Should the slug be set to an empty string, the date, or auto-generated from the title in these cases?
    (Current patch sets it as an empty string; this matches the existing logic for missing slugs.)

  • Are there any edge-cases where filename collisions could cause confusion? (For example, if a section contains both 2025-08-04.md and 2025-08-04-news.md.)

Future Possibilities

  • Optionally allow more flexible date formats (e.g., including time, or just year/month).

  • Allow configuring this behavior via config.toml.

Appendix: Patch

The complete patch is at components: content: page: Allow datetime-only filenames · getzola/zola@64c96ed · GitHub

1 Like
2

So it’s been over two weeks. Does anyone any comment? Is it good or bad? Can I create a PR for it? @keats Do you have a comment?

3

sorry for the delay. I think it makes sense. The slug should probably be the date i think? Is it meant to support full datetime or only dates?

4

But because we already have the date in the path, having it again in the slug is redundant.

And, it already supports full datetime.

Here is a sample site you can play with: https://github.com/yashi/zola-slugless-date Make sure to use it with components: content: page: Allow datetime-only filenames · getzola/zola@64c96ed · GitHub

5

I have created a PR on next.