From 634bdb277a269bff92958ce54871c7dca7ad9226 Mon Sep 17 00:00:00 2001 From: "fern-api[bot]" <115122769+fern-api[bot]@users.noreply.github.com> Date: Tue, 9 Jun 2026 20:53:28 +0000 Subject: [PATCH 1/9] Add comprehensive slug documentation to navigation page --- .../docs/pages/navigation/navigation.mdx | 60 ++++++++++++++++++- 1 file changed, 58 insertions(+), 2 deletions(-) diff --git a/fern/products/docs/pages/navigation/navigation.mdx b/fern/products/docs/pages/navigation/navigation.mdx index 77029bb1f0..3c1f2d041f 100644 --- a/fern/products/docs/pages/navigation/navigation.mdx +++ b/fern/products/docs/pages/navigation/navigation.mdx @@ -1,7 +1,7 @@ --- title: Sections, pages, and folders subtitle: Organize your sidebar navigation structure in `docs.yml` -description: Configure the sidebar navigation for your Fern documentation site, including sections, pages, folders, icons, and links. +description: Configure the sidebar navigation for your Fern documentation site, including sections, pages, folders, URL slugs, icons, and links. max-toc-depth: 3 --- @@ -74,6 +74,8 @@ navigation: ``` {/* */} +Sections also support [`slug` and `skip-slug`](#slugs-and-url-paths) to customize URL paths. + ### Add a page Create an `.md` or `.mdx` file, then add a `page` entry to a section's `contents` with the file path. @@ -114,7 +116,7 @@ navigation: ``` For the pages in a folder, Fern automatically: -- Converts filenames to titles and URL slugs +- Derives titles and [URL slugs](#slugs-and-url-paths) from filenames - Creates nested sections from subdirectories - Sorts pages alphabetically - Uses `index.mdx` or `index.md` files as section overview pages (case-insensitive) @@ -158,6 +160,60 @@ navigation: +## Slugs and URL paths + +Fern builds page URLs by combining slugs from each level of the navigation hierarchy. By default, every navigation item gets an auto-generated slug derived from its display name — lowercased, with spaces replaced by hyphens. + +| Navigation item | Slug derived from | Example | Auto-generated slug | +|---|---|---|---| +| Section | `section` name | `Key Concepts` | `key-concepts` | +| Page | `page` name | `Quick Start` | `quick-start` | +| Folder | Directory name or `title` | `api-guides` | `api-guides` | +| Tab | `display-name` | `API Reference` | `api-reference` | +| Version | `display-name` | `v3 (Latest)` | `v-3-latest` | +| Product | `display-name` | `My Product` | `my-product` | + +Special characters such as parentheses are stripped during generation. For [folder-based navigation](#add-a-folder), page slugs are derived from filenames rather than display names — a file named `quick-start.mdx` produces the slug `quick-start`. + +### Customize slugs + +Set `slug` on any navigation item in `docs.yml` to replace the auto-generated value. The slug is relative to the item's position in the hierarchy. + +{/* */} +```yaml docs.yml +navigation: + - section: Getting started + slug: start + contents: + - page: Quick Start Guide + path: ./pages/quickstart.mdx + slug: quickstart +``` +{/* */} + +This produces `…/start/quickstart` instead of the auto-generated `…/getting-started/quick-start-guide`. + +### Skip slugs + +To exclude an item from the URL path, use `skip-slug: true`. Sections, folders, tabs, and tab variants support this property. + +{/* */} +```yaml docs.yml +navigation: + - section: Guides + skip-slug: true + contents: + - page: Authentication + path: ./pages/auth.mdx +``` +{/* */} + +The page URL becomes `…/authentication` instead of `…/guides/authentication`. + + +Pages also support a `slug` in [frontmatter](/learn/docs/configuration/page-level-settings#slug). A frontmatter slug is absolute — it sets the full URL path from the docs root, ignoring the navigation hierarchy. + + ## Hiding content To hide a page, folder, or section, add `hidden: true`. Hidden content (including all pages within a folder) is still accessible via direct URL but is excluded from search and won't be indexed. From a0c85ab93e2d128ed1c2fa375a962c0f04e6c7f3 Mon Sep 17 00:00:00 2001 From: "fern-api[bot]" <115122769+fern-api[bot]@users.noreply.github.com> Date: Mon, 15 Jun 2026 15:14:15 +0000 Subject: [PATCH 2/9] Reconcile slug docs: trim navigation page, add algorithm to canonical slug page --- .../docs/pages/navigation/navigation.mdx | 41 +------------------ .../docs/pages/seo/configuring-slugs.mdx | 11 ++++- 2 files changed, 12 insertions(+), 40 deletions(-) diff --git a/fern/products/docs/pages/navigation/navigation.mdx b/fern/products/docs/pages/navigation/navigation.mdx index 3c1f2d041f..5bbb94ce23 100644 --- a/fern/products/docs/pages/navigation/navigation.mdx +++ b/fern/products/docs/pages/navigation/navigation.mdx @@ -74,7 +74,7 @@ navigation: ``` {/* */} -Sections also support [`slug` and `skip-slug`](#slugs-and-url-paths) to customize URL paths. +Sections also support [`slug` and `skip-slug`](/learn/docs/seo/configuring-slugs) to customize URL paths. ### Add a page @@ -175,44 +175,7 @@ Fern builds page URLs by combining slugs from each level of the navigation hiera Special characters such as parentheses are stripped during generation. For [folder-based navigation](#add-a-folder), page slugs are derived from filenames rather than display names — a file named `quick-start.mdx` produces the slug `quick-start`. -### Customize slugs - -Set `slug` on any navigation item in `docs.yml` to replace the auto-generated value. The slug is relative to the item's position in the hierarchy. - -{/* */} -```yaml docs.yml -navigation: - - section: Getting started - slug: start - contents: - - page: Quick Start Guide - path: ./pages/quickstart.mdx - slug: quickstart -``` -{/* */} - -This produces `…/start/quickstart` instead of the auto-generated `…/getting-started/quick-start-guide`. - -### Skip slugs - -To exclude an item from the URL path, use `skip-slug: true`. Sections, folders, tabs, and tab variants support this property. - -{/* */} -```yaml docs.yml -navigation: - - section: Guides - skip-slug: true - contents: - - page: Authentication - path: ./pages/auth.mdx -``` -{/* */} - -The page URL becomes `…/authentication` instead of `…/guides/authentication`. - - -Pages also support a `slug` in [frontmatter](/learn/docs/configuration/page-level-settings#slug). A frontmatter slug is absolute — it sets the full URL path from the docs root, ignoring the navigation hierarchy. - +To rename or skip slugs, see [Customizing slugs](/learn/docs/seo/configuring-slugs). To override a page's entire URL path, see the [frontmatter `slug` property](/learn/docs/configuration/page-level-settings#slug). ## Hiding content diff --git a/fern/products/docs/pages/seo/configuring-slugs.mdx b/fern/products/docs/pages/seo/configuring-slugs.mdx index 9f05f718c0..9c543208ea 100644 --- a/fern/products/docs/pages/seo/configuring-slugs.mdx +++ b/fern/products/docs/pages/seo/configuring-slugs.mdx @@ -4,7 +4,16 @@ description: Customize URL paths in your Fern documentation site. Rename slugs f --- -By default, Fern generates the slug of a page based on the navigation structure in the `docs.yml` file. +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](/learn/docs/configuration/navigation#add-a-folder), page slugs are derived from filenames rather than display names. + +| Navigation item | Slug derived from | Example | Auto-generated slug | +|---|---|---|---| +| Section | `section` name | `Key Concepts` | `key-concepts` | +| Page | `page` name | `Quick Start` | `quick-start` | +| Folder | Directory name or `title` | `api-guides` | `api-guides` | +| Tab | `display-name` | `API Reference` | `api-reference` | +| Version | `display-name` | `v3 (Latest)` | `v-3-latest` | +| Product | `display-name` | `My Product` | `my-product` | From 27964bde4d255c0536d94df717f4fd369f93496d Mon Sep 17 00:00:00 2001 From: "fern-api[bot]" <115122769+fern-api[bot]@users.noreply.github.com> Date: Mon, 15 Jun 2026 17:35:11 +0000 Subject: [PATCH 3/9] Expand frontmatter slug override explanation on canonical slug page --- .../docs/pages/navigation/navigation.mdx | 2 +- .../docs/pages/seo/configuring-slugs.mdx | 22 ++++++++++++------- 2 files changed, 15 insertions(+), 9 deletions(-) diff --git a/fern/products/docs/pages/navigation/navigation.mdx b/fern/products/docs/pages/navigation/navigation.mdx index 5bbb94ce23..2378346331 100644 --- a/fern/products/docs/pages/navigation/navigation.mdx +++ b/fern/products/docs/pages/navigation/navigation.mdx @@ -175,7 +175,7 @@ Fern builds page URLs by combining slugs from each level of the navigation hiera Special characters such as parentheses are stripped during generation. For [folder-based navigation](#add-a-folder), page slugs are derived from filenames rather than display names — a file named `quick-start.mdx` produces the slug `quick-start`. -To rename or skip slugs, see [Customizing slugs](/learn/docs/seo/configuring-slugs). To override a page's entire URL path, see the [frontmatter `slug` property](/learn/docs/configuration/page-level-settings#slug). +To rename or skip slugs, see [Customizing slugs](/learn/docs/seo/configuring-slugs). A `slug` set in [page frontmatter](/learn/docs/configuration/page-level-settings#slug) overrides the entire URL path from the docs root — the page is served at that path regardless of its position in the navigation hierarchy. For example, setting `slug: quickstart` in frontmatter produces the URL `/quickstart` even if the page lives inside a `Getting started` section. ## Hiding content diff --git a/fern/products/docs/pages/seo/configuring-slugs.mdx b/fern/products/docs/pages/seo/configuring-slugs.mdx index 9c543208ea..07fde2b958 100644 --- a/fern/products/docs/pages/seo/configuring-slugs.mdx +++ b/fern/products/docs/pages/seo/configuring-slugs.mdx @@ -112,29 +112,35 @@ landing-page: slug: /welcome ``` -### Override a page's slug with frontmatter +### Override a page's entire URL path -Frontmatter slugs take precedence over slugs generated or set in `docs.yml`, giving you full control over a page's URL. +A `slug` set in docs.yml replaces only that item's segment, preserving the parent hierarchy. A `slug` set in page frontmatter overrides the **entire** URL path from the docs root, ignoring the navigation hierarchy completely. -```yaml title="docs.yml" +```yaml title="docs.yml" {3, 6} navigation: - section: Get Started slug: start contents: - page: Quickstart + slug: quick path: ./docs/pages/quickstart.mdx ``` -With this configuration, the page would normally be at `plantstore.docs.buildwithfern.com/start/quickstart`. To override this, set `slug` in the page's frontmatter: +With only docs.yml slugs, the page URL is `plantstore.docs.buildwithfern.com/start/quick` — the hierarchy is preserved. -```markdown title="quickstart.mdx" {2} +To override the full path, set `slug` in the page's frontmatter: + +```markdown title="quickstart.mdx" --- -title: Quickstart -slug: start-up +slug: quickstart --- ``` -The page is now available at `plantstore.docs.buildwithfern.com/start/start-up` instead. See [frontmatter configuration](/learn/docs/configuration/page-level-settings#slug) for more details. +The page is now at `plantstore.docs.buildwithfern.com/quickstart` — the section hierarchy is bypassed entirely. The page still appears in the sidebar under "Get Started", but its URL no longer reflects that structure. + +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). + +See [frontmatter configuration](/learn/docs/configuration/page-level-settings#slug) for additional details. ### Renaming slugs for subheadings By default, deep links to subheadings are generated by appending a `#` and the subheading title (converted to `kebab-casing-convention`) onto the page URL. From db1600a32e0c53c829ecebfd05eaa55baf210bd8 Mon Sep 17 00:00:00 2001 From: "fern-api[bot]" <115122769+fern-api[bot]@users.noreply.github.com> Date: Mon, 15 Jun 2026 19:28:30 +0000 Subject: [PATCH 4/9] Trim navigation page slug section to brief explanation + link to canonical page --- .../products/docs/pages/navigation/navigation.mdx | 15 ++------------- 1 file changed, 2 insertions(+), 13 deletions(-) diff --git a/fern/products/docs/pages/navigation/navigation.mdx b/fern/products/docs/pages/navigation/navigation.mdx index 2378346331..42abbf0ef0 100644 --- a/fern/products/docs/pages/navigation/navigation.mdx +++ b/fern/products/docs/pages/navigation/navigation.mdx @@ -162,20 +162,9 @@ navigation: ## Slugs and URL paths -Fern builds page URLs by combining slugs from each level of the navigation hierarchy. By default, every navigation item gets an auto-generated slug derived from its display name — lowercased, with spaces replaced by hyphens. +Fern builds page URLs by combining slugs from each level of the navigation hierarchy. By default, every navigation item — sections, pages, folders, tabs, versions, and products — gets an auto-generated slug derived from its display name (lowercased, spaces replaced by hyphens, special characters stripped). For [folder-based navigation](#add-a-folder), page slugs are derived from filenames rather than display names. -| Navigation item | Slug derived from | Example | Auto-generated slug | -|---|---|---|---| -| Section | `section` name | `Key Concepts` | `key-concepts` | -| Page | `page` name | `Quick Start` | `quick-start` | -| Folder | Directory name or `title` | `api-guides` | `api-guides` | -| Tab | `display-name` | `API Reference` | `api-reference` | -| Version | `display-name` | `v3 (Latest)` | `v-3-latest` | -| Product | `display-name` | `My Product` | `my-product` | - -Special characters such as parentheses are stripped during generation. For [folder-based navigation](#add-a-folder), page slugs are derived from filenames rather than display names — a file named `quick-start.mdx` produces the slug `quick-start`. - -To rename or skip slugs, see [Customizing slugs](/learn/docs/seo/configuring-slugs). A `slug` set in [page frontmatter](/learn/docs/configuration/page-level-settings#slug) overrides the entire URL path from the docs root — the page is served at that path regardless of its position in the navigation hierarchy. For example, setting `slug: quickstart` in frontmatter produces the URL `/quickstart` even if the page lives inside a `Getting started` section. +For full details on how slugs are generated, how to rename or skip them, and how to override a page's entire URL path with frontmatter, see [Customizing slugs](/learn/docs/seo/configuring-slugs). ## Hiding content From b840f93c2a7d8b642982fa92319d43523f6da4d9 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Mon, 15 Jun 2026 15:42:47 -0400 Subject: [PATCH 5/9] update intro --- fern/products/docs/pages/seo/configuring-slugs.mdx | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/fern/products/docs/pages/seo/configuring-slugs.mdx b/fern/products/docs/pages/seo/configuring-slugs.mdx index 07fde2b958..31c7424e95 100644 --- a/fern/products/docs/pages/seo/configuring-slugs.mdx +++ b/fern/products/docs/pages/seo/configuring-slugs.mdx @@ -1,10 +1,11 @@ --- -title: Customizing slugs within your site +title: Configuring slugs description: Customize URL paths in your Fern documentation site. Rename slugs for pages, sections, tabs, landing pages, and subheadings, or skip them entirely. --- +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. -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](/learn/docs/configuration/navigation#add-a-folder), page slugs are derived from filenames rather than display names. +For [folder-based navigation](/learn/docs/configuration/navigation#add-a-folder), page slugs are derived from filenames rather than display names. | Navigation item | Slug derived from | Example | Auto-generated slug | |---|---|---|---| From 6aed8e488496ec3b1ca9d7d003008e4d642a2551 Mon Sep 17 00:00:00 2001 From: "fern-api[bot]" <115122769+fern-api[bot]@users.noreply.github.com> Date: Mon, 15 Jun 2026 19:56:14 +0000 Subject: [PATCH 6/9] Correct frontmatter slug docs: preserves product/version prefixes, does not wipe entire URL --- .../docs/pages/navigation/frontmatter.mdx | 18 ++++---- .../docs/pages/navigation/navigation.mdx | 2 +- .../docs/pages/seo/configuring-slugs.mdx | 41 ++++++++++++++++--- 3 files changed, 47 insertions(+), 14 deletions(-) diff --git a/fern/products/docs/pages/navigation/frontmatter.mdx b/fern/products/docs/pages/navigation/frontmatter.mdx index a37bd88f6f..d32c2902d5 100644 --- a/fern/products/docs/pages/navigation/frontmatter.mdx +++ b/fern/products/docs/pages/navigation/frontmatter.mdx @@ -5,7 +5,7 @@ description: Use frontmatter to set a variety of page properties and metadata. --- -You can optionally use frontmatter to set each page's title, full slug override, meta description, a URL to suggest edits to the page, and its OpenGraph image. You can also use frontmatter to disable certain page elements like the table of contents, on-page feedback, and page actions. +You can optionally use frontmatter to set each page's title, slug override, meta description, a URL to suggest edits to the page, and its OpenGraph image. You can also use frontmatter to disable certain page elements like the table of contents, on-page feedback, and page actions. For advanced styling and functionality customizations beyond frontmatter options, see [custom CSS and JavaScript](/docs/customization/custom-css-js). @@ -128,14 +128,14 @@ Want to automatically update the `last-updated` field when MDX files change? See ## Slug - Overrides the full URL path for the page, starting from the root of your docs site. This takes precedence over any slug defined in docs.yml. + Overrides the section and folder hierarchy in the page's URL. Product and version prefixes are preserved. This takes precedence over any slug defined in docs.yml. -For example, if you set `slug: email` in frontmatter, the page will be available at `/email` regardless of its location in the navigation structure. +For example, if you set `slug: email` in frontmatter, the page bypasses its section/tab/folder slugs and resolves to `/email` (or `/product-slug/email` if inside a product). There are two ways to set a page's URL slug: -1. Using `slug` in docs.yml, which is relative to the page's location in the navigation: +1. Using `slug` in docs.yml, which replaces only that item's segment while preserving the parent hierarchy: ```yaml navigation: @@ -149,18 +149,20 @@ navigation: ``` -2. Using `slug` in frontmatter, which overrides everything and sets the absolute path from the root: +2. Using `slug` in frontmatter, which bypasses the section/tab/folder hierarchy: ```mdx --- -slug: email # Results in /email (ignores navigation structure) +slug: email # Results in /email (bypasses tab and section) --- ``` The key difference is: -- A slug in docs.yml is relative to the page's location in the navigation structure -- A slug in frontmatter is absolute and ignores the navigation structure completely +- A slug in docs.yml replaces only that item's segment, preserving the parent hierarchy +- A slug in frontmatter bypasses the section/tab/folder hierarchy (but product and version prefixes are always retained) + +See [Customizing slugs](/learn/docs/seo/configuring-slugs#override-with-a-frontmatter-slug) for detailed examples, including behavior within products and versions. ## Meta description diff --git a/fern/products/docs/pages/navigation/navigation.mdx b/fern/products/docs/pages/navigation/navigation.mdx index 42abbf0ef0..5aeb653ed3 100644 --- a/fern/products/docs/pages/navigation/navigation.mdx +++ b/fern/products/docs/pages/navigation/navigation.mdx @@ -164,7 +164,7 @@ navigation: Fern builds page URLs by combining slugs from each level of the navigation hierarchy. By default, every navigation item — sections, pages, folders, tabs, versions, and products — gets an auto-generated slug derived from its display name (lowercased, spaces replaced by hyphens, special characters stripped). For [folder-based navigation](#add-a-folder), page slugs are derived from filenames rather than display names. -For full details on how slugs are generated, how to rename or skip them, and how to override a page's entire URL path with frontmatter, see [Customizing slugs](/learn/docs/seo/configuring-slugs). +For full details on how slugs are generated, how to rename or skip them, and how to override a page's URL path with frontmatter, see [Customizing slugs](/learn/docs/seo/configuring-slugs). ## Hiding content diff --git a/fern/products/docs/pages/seo/configuring-slugs.mdx b/fern/products/docs/pages/seo/configuring-slugs.mdx index 07fde2b958..b12f677a91 100644 --- a/fern/products/docs/pages/seo/configuring-slugs.mdx +++ b/fern/products/docs/pages/seo/configuring-slugs.mdx @@ -112,9 +112,9 @@ landing-page: slug: /welcome ``` -### Override a page's entire URL path +### 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 overrides the **entire** URL path from the docs root, ignoring the navigation hierarchy completely. +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. ```yaml title="docs.yml" {3, 6} navigation: @@ -128,7 +128,7 @@ navigation: With only docs.yml slugs, the page URL is `plantstore.docs.buildwithfern.com/start/quick` — the hierarchy is preserved. -To override the full path, set `slug` in the page's frontmatter: +To override the path within the current product/version scope, set `slug` in the page's frontmatter: ```markdown title="quickstart.mdx" --- @@ -136,9 +136,40 @@ slug: quickstart --- ``` -The page is now at `plantstore.docs.buildwithfern.com/quickstart` — the section hierarchy is bypassed entirely. The page still appears in the sidebar under "Get Started", but its URL no longer reflects that structure. +The page is now at `plantstore.docs.buildwithfern.com/quickstart` — the section hierarchy is bypassed. The page still appears in the sidebar under "Get Started", but its URL no longer reflects that structure. -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). +#### Behavior with products and versions + +When a page lives inside a [product](/learn/docs/configuration/navigation#add-a-product) or [version](/learn/docs/configuration/navigation#add-a-version), the frontmatter slug replaces only the section/folder portion of the URL. The product and version slugs are always preserved. + +```yaml title="docs.yml" +products: + - display-name: Platform + slug: platform + navigation: + - tab: guides + layout: + - section: Get Started + contents: + - page: Quickstart + path: ./docs/pages/quickstart.mdx +``` + +```markdown title="quickstart.mdx" +--- +slug: quickstart +--- +``` + +The resulting URL is `example.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`. + + + A frontmatter slug cannot escape the product or version prefix. To move a page to the absolute root of your docs, place it outside any product or version in your navigation structure. + + +Use frontmatter `slug` when a page needs a short, memorable URL independent of its sidebar position within a product (e.g., a top-level quickstart, a campaign landing page, or a page that moved but must keep its old URL). See [frontmatter configuration](/learn/docs/configuration/page-level-settings#slug) for additional details. From 8c6a807a395d2befd87320bd677f5cbb2964a48f Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Mon, 15 Jun 2026 16:51:04 -0400 Subject: [PATCH 7/9] clarify wording and structure --- .../docs/pages/navigation/frontmatter.mdx | 35 +------------------ .../docs/pages/navigation/navigation.mdx | 17 +++++++-- .../docs/pages/seo/configuring-slugs.mdx | 30 ++++++---------- 3 files changed, 27 insertions(+), 55 deletions(-) diff --git a/fern/products/docs/pages/navigation/frontmatter.mdx b/fern/products/docs/pages/navigation/frontmatter.mdx index d32c2902d5..b5980a9bba 100644 --- a/fern/products/docs/pages/navigation/frontmatter.mdx +++ b/fern/products/docs/pages/navigation/frontmatter.mdx @@ -128,42 +128,9 @@ Want to automatically update the `last-updated` field when MDX files change? See ## Slug - Overrides the section and folder hierarchy in the page's URL. Product and version prefixes are preserved. This takes precedence over any slug defined in docs.yml. + Overrides the page's URL path, replacing the section and folder hierarchy while preserving any product or version prefix. Takes precedence over a slug set in `docs.yml`. See [configuring slugs](/learn/docs/seo/configuring-slugs#override-with-a-frontmatter-slug) for detailed examples, including behavior within products and versions. -For example, if you set `slug: email` in frontmatter, the page bypasses its section/tab/folder slugs and resolves to `/email` (or `/product-slug/email` if inside a product). - -There are two ways to set a page's URL slug: - -1. Using `slug` in docs.yml, which replaces only that item's segment while preserving the parent hierarchy: - -```yaml -navigation: - - tab: overview - layout: - - section: Support - contents: - - page: Email Us - path: ./pages/email-us.mdx - slug: email # Results in /overview/support/email -``` - - -2. Using `slug` in frontmatter, which bypasses the section/tab/folder hierarchy: - -```mdx ---- -slug: email # Results in /email (bypasses tab and section) ---- -``` - - -The key difference is: -- A slug in docs.yml replaces only that item's segment, preserving the parent hierarchy -- A slug in frontmatter bypasses the section/tab/folder hierarchy (but product and version prefixes are always retained) - -See [Customizing slugs](/learn/docs/seo/configuring-slugs#override-with-a-frontmatter-slug) for detailed examples, including behavior within products and versions. - ## Meta description diff --git a/fern/products/docs/pages/navigation/navigation.mdx b/fern/products/docs/pages/navigation/navigation.mdx index 5aeb653ed3..2b5dd28515 100644 --- a/fern/products/docs/pages/navigation/navigation.mdx +++ b/fern/products/docs/pages/navigation/navigation.mdx @@ -162,9 +162,22 @@ navigation: ## Slugs and URL paths -Fern builds page URLs by combining slugs from each level of the navigation hierarchy. By default, every navigation item — sections, pages, folders, tabs, versions, and products — gets an auto-generated slug derived from its display name (lowercased, spaces replaced by hyphens, special characters stripped). For [folder-based navigation](#add-a-folder), page slugs are derived from filenames rather than display names. +Fern builds each page's URL by combining slugs from every level of its navigation hierarchy — section, folder, tab, version, and product. Each level gets an auto-generated slug from its display name, or from the filename for [folder-based navigation](#add-a-folder). You can [rename a slug, skip a level, or override the path in a page's frontmatter](/learn/docs/seo/configuring-slugs). -For full details on how slugs are generated, how to rename or skip them, and how to override a page's URL path with frontmatter, see [Customizing slugs](/learn/docs/seo/configuring-slugs). +```yaml docs.yml +navigation: + - section: Get Started # slug renamed to "start" + slug: start + contents: + - section: Guides # skipped — omitted from the URL + skip-slug: true + contents: + - page: Quickstart # slug renamed to "quick" + slug: quick + path: ./pages/quickstart.mdx +``` + +The **Quickstart** page is hosted at `/start/quick`. The renamed section and page slugs apply, and the skipped **Guides** slug drops out of the path. ## Hiding content diff --git a/fern/products/docs/pages/seo/configuring-slugs.mdx b/fern/products/docs/pages/seo/configuring-slugs.mdx index 5549b1743d..61336e3c9a 100644 --- a/fern/products/docs/pages/seo/configuring-slugs.mdx +++ b/fern/products/docs/pages/seo/configuring-slugs.mdx @@ -66,7 +66,7 @@ You can customize these default slugs by renaming them or skipping them entirely 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, you can set the `slug` within the `navigation` object. +To modify the slug used for a page or section, set the `slug` within the `navigation` object. ```yaml docs.yml {3, 6} navigation: @@ -82,7 +82,7 @@ In the example above, the **Welcome** page would be hosted at `plantstore.docs.b ### Modify a tab slug -To modify the slug used for a tab, you can set the `slug` within the `tabs` object. +To modify the slug used for a tab, set the `slug` within the `tabs` object. ```yaml docs.yml {4} tabs: @@ -104,7 +104,7 @@ navigation: 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, you can set the `slug` within the `landing-page` object. +To modify the slug used for a landing page, set the `slug` within the `landing-page` object. ```yaml title="docs.yml" {4} landing-page: @@ -115,7 +115,9 @@ landing-page: ### 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. +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). ```yaml title="docs.yml" {3, 6} navigation: @@ -127,9 +129,7 @@ navigation: path: ./docs/pages/quickstart.mdx ``` -With only docs.yml slugs, the page URL is `plantstore.docs.buildwithfern.com/start/quick` — the hierarchy is preserved. - -To override the path within the current product/version scope, set `slug` in the page's frontmatter: +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: ```markdown title="quickstart.mdx" --- @@ -137,11 +137,11 @@ slug: quickstart --- ``` -The page is now at `plantstore.docs.buildwithfern.com/quickstart` — the section hierarchy is bypassed. The page still appears in the sidebar under "Get Started", but its URL no longer reflects that structure. +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](/learn/docs/configuration/navigation#add-a-product) or [version](/learn/docs/configuration/navigation#add-a-version), the frontmatter slug replaces only the section/folder portion of the URL. The product and version slugs are always preserved. +When a page lives inside a [product](/learn/docs/configuration/navigation#add-a-product) or [version](/learn/docs/configuration/navigation#add-a-version), setting a frontmatter slug replaces only the section/folder portion of the URL. The product and version slugs are always preserved. ```yaml title="docs.yml" products: @@ -162,17 +162,9 @@ slug: quickstart --- ``` -The resulting URL is `example.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`. - - - A frontmatter slug cannot escape the product or version prefix. To move a page to the absolute root of your docs, place it outside any product or version in your navigation structure. - - -Use frontmatter `slug` when a page needs a short, memorable URL independent of its sidebar position within a product (e.g., a top-level quickstart, a campaign landing page, or a page that moved but must keep its old URL). +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. -See [frontmatter configuration](/learn/docs/configuration/page-level-settings#slug) for additional details. +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. ### Renaming slugs for subheadings By default, deep links to subheadings are generated by appending a `#` and the subheading title (converted to `kebab-casing-convention`) onto the page URL. From c13e29fc082c28d861f9eb21e3b05024cf0f413e Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Mon, 15 Jun 2026 16:59:42 -0400 Subject: [PATCH 8/9] fix parse error --- .../docs/pages/navigation/frontmatter.mdx | 49 ------------------- 1 file changed, 49 deletions(-) diff --git a/fern/products/docs/pages/navigation/frontmatter.mdx b/fern/products/docs/pages/navigation/frontmatter.mdx index 9689a17f7e..e527817d98 100644 --- a/fern/products/docs/pages/navigation/frontmatter.mdx +++ b/fern/products/docs/pages/navigation/frontmatter.mdx @@ -158,55 +158,6 @@ Want to automatically update the `last-updated` field when MDX files change? See Overrides the page's URL path, replacing the section and folder hierarchy while preserving any product or version prefix. Takes precedence over a slug set in `docs.yml`. See [configuring slugs](/learn/docs/seo/configuring-slugs#override-with-a-frontmatter-slug) for detailed examples, including behavior within products and versions. -<<<<<<< fern/document-slug-generation -## Meta description - - - Set the [meta description](https://web.dev/learn/html/metadata#description) for a page. Like the page title, the meta description is important for SEO. It impacts the text that search engines display about your page in search results snippets. It can also influence search engine indexing and ranking. For more information, see [Google's guidelines for meta descriptions](https://developers.google.com/search/docs/appearance/snippet#meta-descriptions). The description is also used in [`llms.txt` and `llms-full.txt`](/learn/docs/ai-features/llms-txt#page-descriptions). - - - -```mdx ---- -title: API Authentication -description: Learn how to authenticate your API requests using API keys, OAuth 2.0, or JWT tokens. Includes code examples in multiple languages and security best practices. ---- -``` - -======= -For example, if you set `slug: email` in frontmatter, the page will be available at `/email` regardless of its location in the navigation structure. - -There are two ways to set a page's URL slug: - -1. Using `slug` in docs.yml, which is relative to the page's location in the navigation: - -```yaml -navigation: - - tab: overview - layout: - - section: Support - contents: - - page: Email Us - path: ./pages/email-us.mdx - slug: email # Results in /overview/support/email -``` - - -2. Using `slug` in frontmatter, which overrides everything and sets the absolute path from the root: - -```mdx ---- -slug: email # Results in /email (ignores navigation structure) ---- -``` - - -The key difference is: -- A slug in docs.yml is relative to the page's location in the navigation structure -- A slug in frontmatter is absolute and ignores the navigation structure completely - ->>>>>>> main - ## Edit this page From 172baa912bcf02717f9fdd2793c6d8198bdb1800 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Mon, 15 Jun 2026 19:23:44 -0400 Subject: [PATCH 9/9] fix render error --- .../docs/pages/seo/configuring-slugs.mdx | 56 +++++++++---------- 1 file changed, 28 insertions(+), 28 deletions(-) diff --git a/fern/products/docs/pages/seo/configuring-slugs.mdx b/fern/products/docs/pages/seo/configuring-slugs.mdx index 61336e3c9a..e4ad8c666a 100644 --- a/fern/products/docs/pages/seo/configuring-slugs.mdx +++ b/fern/products/docs/pages/seo/configuring-slugs.mdx @@ -112,6 +112,34 @@ landing-page: path: path/to/landing-page.mdx slug: /welcome ``` +### 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. + +```yaml docs.yml +navigation: + - section: Get Started + contents: + - page: Welcome + path: ./docs/pages/welcome.mdx +``` + +```jsx welcome.mdx +... + +## Frequently Asked Questions +... +``` + +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: + +```jsx welcome.mdx +## Frequently Asked Questions [#faqs] +``` + +The link to this section will now be available at `plantstore.docs.buildwithfern.com/get-started/welcome#faqs`. ### Override with a frontmatter slug @@ -166,34 +194,6 @@ The resulting URL is `plantstore.docs.buildwithfern.com/platform/quickstart` — 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. -### Renaming slugs for subheadings -By default, deep links to subheadings are generated by appending a `#` and the subheading title (converted to `kebab-casing-convention`) onto the page URL. - -```yaml docs.yml -navigation: - - section: Get Started - contents: - - page: Welcome - path: ./docs/pages/welcome.mdx -``` - -```markdown welcome.mdx -... - -## Frequently Asked Questions -... -``` - -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: - -```markdown welcome.mdx -## Frequently Asked Questions [#faqs] -``` - -The link to this section will now be available at `plantstore.docs.buildwithfern.com/get-started/welcome#faqs`. - ## Skipping slugs To ignore a tab or section when generating the slug, simply indicate `skip-slug: true`.