Configuring slugs
Fern automatically generates a URL slug for each navigation item and joins them into every page’s full URL. You can rename a slug, skip a level, or override a page’s path in its frontmatter.
How slugs are generated
By default, Fern derives each navigation item’s slug from its display name in docs.yml, lowercasing the name, replacing spaces with hyphens, and stripping special characters such as parentheses. Pages in folder-based navigation take their slugs from filenames instead.
A page’s full URL joins these slugs from the outermost scope inward — product, version, tab, section and folder, then page.
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.
Renaming slugs
Set the slug property in docs.yml or in a page’s frontmatter to customize the URL path. Where you set it determines how much of the URL it replaces:
docs.yml: replaces only that navigation item’s own segment.- Page frontmatter: replaces the page’s entire section and folder hierarchy, and takes precedence over a
docs.ymlslug on the same page. - Product and version prefixes: preserved in both cases.
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.
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 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 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 a ## or ### 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
Use a frontmatter slug when a page needs a short, memorable URL independent of its sidebar position — a top-level quickstart, a campaign landing page, or a page that moved but must keep its old URL.
Given the page and section slugs that place Welcome at /start/intro, adding a slug to the page’s frontmatter replaces that entire hierarchy:
The page now resolves to plantstore.docs.buildwithfern.com/welcome, taking precedence over the docs.yml slugs. It still appears in the sidebar under “Get Started”, but its URL no longer reflects that structure.
A frontmatter slug never escapes a product or version prefix. A Quickstart page inside the product platform with frontmatter slug: quickstart resolves to /platform/quickstart — not /quickstart — and in version v2 of that product, /platform/v2/quickstart.
To move a page to the absolute root of your docs, place it outside any product or version in your navigation.
Skipping slugs
To ignore a tab or section when generating the slug, simply indicate skip-slug: true.
Example without tabs
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.