Configuring slugs
By default, Fern generates the slug of a page based on the navigation structure in the docs.yml file. Each navigation item — sections, pages, tabs, versions, and products — gets a slug derived from its display name by lowercasing and replacing spaces with hyphens. Special characters such as parentheses are stripped.
For folder-based navigation, page slugs are derived from filenames rather than display names.
Example without tabs
In the example above, the Welcome page would be hosted at plantstore.docs.buildwithfern.com/get-started/welcome.
Example with tabs
In the example above, the Welcome page would be hosted at plantstore.docs.buildwithfern.com/docs/get-started/welcome.
You can customize these default slugs by renaming them or skipping them entirely.
Changing a slug updates the page’s URL. Run fern check to detect pages that moved without a redirect, so existing links don’t break.
Renaming slugs
Set the slug property in docs.yml or in a page’s frontmatter to customize the URL path.
Modify a page or section slug
To modify the slug used for a page or section, set the slug within the navigation object.
In the example above, the Welcome page would be hosted at plantstore.docs.buildwithfern.com/start/intro.
Modify a tab slug
To modify the slug used for a tab, set the slug within the tabs object.
In the example above, the Welcome page would be hosted at plantstore.docs.buildwithfern.com/guides/get-started/welcome.
Modify a landing page’s slug
To modify the slug used for a landing page, set the slug within the landing-page object.
Rename subheading slugs
By default, deep links to subheadings are generated by appending a # and the subheading title (converted to kebab-casing-convention) onto the page URL.
The link to this section will be available at plantstore.docs.buildwithfern.com/get-started/welcome#frequently-asked-questions.
To rename the slug of the subheading, add the desired slug:
The link to this section will now be available at plantstore.docs.buildwithfern.com/get-started/welcome#faqs.
Override with a frontmatter slug
A slug set in docs.yml replaces only that item’s segment, preserving the parent hierarchy. A slug set in page frontmatter replaces the section and folder hierarchy for that page, but preserves any product or version prefix.
Use frontmatter slug when a page needs a short, memorable URL independent of its sidebar position (e.g., a top-level quickstart, a campaign landing page, or a page that moved but must keep its old URL).
With only docs.yml slugs, the page URL is plantstore.docs.buildwithfern.com/start/quick — the hierarchy is preserved. To replace that hierarchy and set the page’s path directly, set slug in the page’s frontmatter:
The page is now at plantstore.docs.buildwithfern.com/quickstart, bypassing the section hierarchy. The page still appears in the sidebar under “Get Started”, but its URL no longer reflects that structure.
Behavior with products and versions
When a page lives inside a product or version, setting a frontmatter slug replaces only the section/folder portion of the URL. The product and version slugs are always preserved.
The resulting URL is plantstore.docs.buildwithfern.com/platform/quickstart — not /quickstart. The product slug platform is retained; only the section and tab hierarchy is bypassed.
The same applies to versions: a page in version “v2” of product “platform” with frontmatter slug: quickstart resolves to /platform/v2/quickstart. To move a page to the absolute root of your docs, place it outside any product or version in your navigation structure.
Skipping slugs
To ignore a tab or section when generating the slug, simply indicate skip-slug: true.
Example without tabs defaultOpen
In the example above, the Welcome page would be hosted at plantstore.docs.buildwithfern.com/welcome.
Example with tabs
In the example above, the Welcome page would be hosted at plantstore.docs.buildwithfern.com/welcome.