Skip to content

resources/page: Don't let a title's "/" split an auto-derived slug - #15255

Merged
bep merged 1 commit into
gohugoio:masterfrom
ipince:fix/title-slash-permalink-segment
Aug 31, 2026
Merged

bep merged 1 commit into
gohugoio:masterfrom
ipince:fix/title-slash-permalink-segment

Conversation

@ipince

@ipince ipince commented Aug 30, 2026

Copy link
Copy Markdown
Contributor

What

When a page has no explicit slug front matter value, the :title and
:slug permalink tokens fall back to a URL-safe form of the page title.
That fallback goes through pageToPermalinkTitle, which urlizes the title
with PathSpec.URLize (MakePathSanitized). That sanitizer intentionally
treats / as a valid path character β€” it's also used for e.g. taxonomy
term names, which are allowed to span multiple path segments (see #5571).

For a regular content page, section, etc., though, the auto-derived slug
is meant to be a single path segment β€” the slug front matter docs say it
"overrides the last segment of the URL path". A title containing a
literal /, e.g. Watch/listen to this, was passed straight through,
silently creating an extra, unintended nested path segment.

Repro

[permalinks.page]
  blog = "/blog/:year/:slug/"
---
title: "Watch/listen to this"
date: 2026-03-05
---

Before this fix, this built to /blog/2026/watch/listen-to-this/
(an extra watch/ directory) instead of the intended single segment
/blog/2026/watch-listen-to-this/. The build succeeds silently, with no
warning β€” easy to miss, since it's not a build error, just an unintended
URL structure.

Why this regressed

This is not a new problem β€” it was fixed once before via #4092 / #5282,
which used a stricter helpers.PathSpec.MakeSegment for auto-derived
titles, explicitly exempting only taxonomy pages (which need / to build
hierarchical terms). That taxonomy/non-taxonomy distinction was lost when
slash handling for taxonomy terms was restored for #5571 β€” the fix for
#5571 switched title handling back to the slash-preserving URLize
function for all page kinds, not just taxonomies, silently
reintroducing this bug for regular pages. This regression was called out
in a comment on #5571 by @max-arnold at the time but was never
separately tracked or fixed.

The fix

Restore the taxonomy/term exemption, scoped narrowly:

  • pageToPermalinkTitle now replaces / (and \) with - before
    urlizing the title, but only for page kinds other than taxonomy
    and term. Multi-level taxonomy hierarchies (the exact behavior Restore 0.48 slash handling in taxonomiesΒ #5571
    asked for) keep working unchanged β€” verified against the existing
    TestTaxonomiesPathSeparation test and a manual repro.
  • Explicit slug front matter values are not touched by this change
    β€” pageToPermalinkSlugElseTitle only falls through to
    pageToPermalinkTitle when p.Slug() == "". Users remain in full
    control of an explicitly-set slug, including any / in it.

Testing

  • Added TestPermalinkExpansionTitleSlash in
    resources/page/permalinks_test.go, covering: a page with a / in its
    auto-derived title/slug, an explicit slug containing / (unchanged),
    and a taxonomy term with / in its name (unchanged, multi-level
    hierarchy preserved).
  • go test ./... passes (143 packages, 0 failures) on top of this change.
  • ./check.sh ./resources/page/... (gofmt + staticcheck + tests) passes.
  • Manually verified against two throwaway sites built with this branch's
    hugo binary:
    • The repro above now builds to /blog/2026/watch-listen-to-this/.
    • A taxonomy site with [permalinks.term] using :slug and a term
      value of country/region/city still builds to
      /regions/country/region/city/ (unchanged from before this fix).

Fixes #3577
See #5571
See #4090

AI assistance disclosure

This PR was written primarily by Claude Code (research, reproduction,
root-cause analysis via git log/git show on the relevant history,
implementation, and tests), reviewed and submitted by me.

When a page has no explicit slug, the :title and :slug permalink tokens
fall back to a URL-safe form of the title. That sanitization step
(PathSpec.URLize / MakePathSanitized) intentionally treats "/" as a
valid path character, since it is also used for things like taxonomy
term names that legitimately span multiple path segments.

For a regular content page, though, the auto-derived slug is meant to
be a single path segment (the front matter "slug" field docs say it
"overrides the last segment of the URL path"). A title containing a
literal "/", e.g. "Watch/listen to this", was passed straight through
into the permalink pattern, silently creating an extra nested path
segment (.../watch/listen-to-this/) instead of a single sanitized one
(.../watch-listen-to-this/). No warning or error was produced; the
site just built with an unintended URL structure.

This behavior regressed from a fix already applied once via gohugoio#4092 and
gohugoio#5282 (which used a stricter helpers.PathSpec.MakeSegment for titles,
exempting only taxonomy pages). That distinction was lost when slash
handling in taxonomy terms was restored for gohugoio#5571, which switched
title handling back to the slash-preserving URLize function for all
page kinds, not just taxonomies.

Restore the taxonomy/term exemption: pageToPermalinkTitle now replaces
"/" (and "\") with "-" before urlizing the title, but only for page
kinds other than taxonomy and term, so multi-level taxonomy
hierarchies (the behavior gohugoio#5571 asked for) keep working exactly as
before. Explicit "slug" front matter values are untouched by this
change, since users should stay in full control of an explicitly set
slug.

Fixes gohugoio#3577
See gohugoio#5571
See gohugoio#4090
@CLAassistant

CLAassistant commented Aug 30, 2026 •

Copy link
Copy Markdown

CLA assistant check
All committers have signed the CLA.

@bep bep added the Review OK label Aug 30, 2026
@bep
bep merged commit 39507d5 into gohugoio:master Aug 31, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Title used in permalink does not have forward slash escaped

3 participants