Repository navigation
resources/page: Don't let a title's "/" split an auto-derived slug - #15255
Merged
Merged
Conversation
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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
When a page has no explicit
slugfront matter value, the:titleand:slugpermalink tokens fall back to a URL-safe form of the page title.That fallback goes through
pageToPermalinkTitle, which urlizes the titlewith
PathSpec.URLize(MakePathSanitized). That sanitizer intentionallytreats
/as a valid path character β it's also used for e.g. taxonomyterm 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
slugfront 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
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 nowarning β 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.MakeSegmentfor auto-derivedtitles, explicitly exempting only taxonomy pages (which need
/to buildhierarchical 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
URLizefunction 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:
pageToPermalinkTitlenow replaces/(and\) with-beforeurlizing the title, but only for page kinds other than
taxonomyand
term. Multi-level taxonomy hierarchies (the exact behavior Restore 0.48 slash handling in taxonomiesΒ #5571asked for) keep working unchanged β verified against the existing
TestTaxonomiesPathSeparationtest and a manual repro.slugfront matter values are not touched by this changeβ
pageToPermalinkSlugElseTitleonly falls through topageToPermalinkTitlewhenp.Slug() == "". Users remain in fullcontrol of an explicitly-set slug, including any
/in it.Testing
TestPermalinkExpansionTitleSlashinresources/page/permalinks_test.go, covering: a page with a/in itsauto-derived title/slug, an explicit slug containing
/(unchanged),and a taxonomy term with
/in its name (unchanged, multi-levelhierarchy preserved).
go test ./...passes (143 packages, 0 failures) on top of this change../check.sh ./resources/page/...(gofmt + staticcheck + tests) passes.hugobinary:/blog/2026/watch-listen-to-this/.[permalinks.term]using:slugand a termvalue of
country/region/citystill 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 showon the relevant history,implementation, and tests), reviewed and submitted by me.