How it works
Folders carry URL segments, pages pick a folder, and the plugin joins the segments into the page's slug when it is saved.
A page's slug is its folder path followed by its own segment. Each folder contributes its pathSegment; the page contributes its pageSegment.
Create folders in the Payload admin, each with a pathSegment such as appeals or 2024.
Nest folders to build the hierarchy, for example 2024 inside appeals.
Create a page and pick a folder from the dropdown.
The slug is generated from the folder path and the page segment: appeals/2024/spring-campaign.
The page in the 2024 folder with page segment spring-campaign gets the slug appeals/2024/spring-campaign and is served at /appeals/2024/spring-campaign. A page with no folder gets just its segment.
Segments
Both segment fields are slugified when saved: lowercased, trimmed, characters other than letters, digits, underscores, spaces and hyphens removed, spaces turned into hyphens, and repeated or leading/trailing hyphens collapsed. Spring Campaign! becomes spring-campaign.
- If you leave a folder's
pathSegmentempty, it is generated from the folder'sname. - If you leave a page's
pageSegmentempty when creating it, it is generated from the page'stitle.
After a page or folder exists, its display name and its URL segment are independent. Renaming never changes a URL; use Edit URL for that.
When slugs are regenerated
The slug is built in a beforeChange hook on each managed collection.
- On create, the slug is always generated.
- On update, the slug is regenerated only when the page's folder or
pageSegmentchanged. Editing other content never touches the URL. - Tree actions decide explicitly. "Keep existing URL" always preserves the slug; "Update URLs", Edit URL and Regenerate URLs always rebuild it.
Changing a folder through Payload's standard folder edit screen does not cascade to its pages. Cascades only run from the tree view's "Update URLs" choice, Edit URL, or Regenerate URLs. See Cascading updates.
Whenever a page's slug changes, the old one is added to its slugHistory. See URL history.
Want URLs that don't follow the folder structure? The buildSlug option replaces the folderPath/pageSegment rule with your own function.