Configuring slugs
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. A page in product Platform, version v2, tab Guides, section Get Started, named Quickstart resolves to platform/v2/guides/get-started/quickstart.
You can override any segment by renaming or skipping it. When a slug is set in more than one place, precedence depends on where it’s set: a slug in docs.yml replaces only that item’s own segment, while a slug in a page’s frontmatter replaces the entire section and folder hierarchy. Product and version prefixes are always preserved.
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 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. Unlike a docs.yml slug, which replaces only its own segment, a frontmatter slug replaces the page’s entire section and folder hierarchy.
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, a frontmatter slug still replaces only the section and folder portion, leaving the product and version prefixes intact.
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.