Document slug auto-generation for all navigation items

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:
 ```
 {/* <!-- vale on --> */}
 
+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:
 </ParamField>
 </Accordion>
 
+## 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.
+
+{/* <!-- vale off --> */}
+```yaml docs.yml
+navigation:
+  - section: Getting started
+    slug: start
+    contents:
+      - page: Quick Start Guide
+        path: ./pages/quickstart.mdx
+        slug: quickstart
+```
+{/* <!-- vale on --> */}
+
+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.
+
+{/* <!-- vale off --> */}
+```yaml docs.yml
+navigation:
+  - section: Guides
+    skip-slug: true
+    contents:
+      - page: Authentication
+        path: ./pages/auth.mdx
+```
+{/* <!-- vale on --> */}
+
+The page URL becomes `…/authentication` instead of `…/guides/authentication`.
+
+<Note>
+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.
+</Note>
+
 ## 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.