fern-api · fern-api · Jul 29, 2026 · Jul 29, 2026 · Jul 29, 2026 · Jul 29, 2026
@@ -20,13 +20,19 @@ navigation:
     contents:
       - page: Overview
         path: ./pages/navigation/overview.mdx
-      - page: Site-level settings
+      - page: Site settings
         path: ./pages/navigation/site-level-settings.mdx
         slug: site-level-settings
+      - page: Page settings
+        path: ./pages/navigation/frontmatter.mdx
+        slug: page-level-settings
       - section: Navigation
         skip-slug: true
         contents:
-          - page: Sections, pages, and folder
+          - page: Overview
+            path: ./pages/navigation/navigation-overview.mdx
+            slug: navigation-overview
+          - page: Sections, pages, and folders
             path: ./pages/navigation/navigation.mdx
             slug: navigation
           - page: Tabs and tab variants
@@ -39,9 +45,6 @@ navigation:
           - page: Changelog pages
             path: ./pages/navigation/changelogs.mdx
             slug: changelogs
-      - page: Page-level settings
-        path: ./pages/navigation/frontmatter.mdx
-        slug: page-level-settings
   - section: Writing content
     contents:
       - page: Markdown basics

@@ -1,10 +1,11 @@
 ---
 title: Changelog pages
 subtitle: Keep a chronological record of project changes with tagging, search, and RSS
+description: Configure changelog pages in Fern, including entry files, the timeline and classic layouts, tag filtering, and the RSS feed.
 ---
 
 
-Keep a record of how your project has changed by writing changelog entries. The changelog renders as a scannable timeline of entry cards grouped by date, automatically populated from the files in your `changelog` folder. Search and tag filtering are built into the timeline, with no configuration required. You can also [switch to the classic layout](#customize-layout) of stacked full entries.
+A changelog is a navigation entry that renders a dated timeline of entries. Point the `changelog` key at a folder and every Markdown file in it becomes an entry, grouped by date, with search and tag filtering built in. A changelog can go wherever a section can — as its own tab, or as an entry in your sidebar.
 
 <Frame
     caption="Keep your users updated as your project evolves"

@@ -1,5 +1,5 @@
 ---
-title: Page-level settings
+title: Page settings
 subtitle: Set titles, descriptions, slugs, layout, and visibility using frontmatter
 description: Use frontmatter to set a variety of page properties and metadata.
 ---

@@ -0,0 +1,79 @@
+---
+title: Navigation overview
+subtitle: Understand the layers that make up your site's navigation
+description: Understand how pages, folders, sections, tabs, versions, and products fit together to form the navigation of a Fern documentation site.
+---
+
+Your site's navigation is defined under the `navigation` key of `docs.yml`. Navigation is built from nested layers, ordered from narrowest to broadest: pages, sections, tabs, versions, and products.
+
+## Navigation layers
+
+<CardGroup cols={2}>
+  <Card title="Sections, pages, and folders" icon="fa-duotone fa-bars" href="/learn/docs/configuration/navigation">
+    The sidebar itself: grouped, nestable entries pointing at Markdown files
+  </Card>
+  <Card title="Tabs and tab variants" icon="fa-duotone fa-folder-open" href="/learn/docs/configuration/tabs">
+    A top-level row that splits one product or version into parallel bodies of content
+  </Card>
+  <Card title="Versions" icon="fa-duotone fa-code-branch" href="/learn/docs/configuration/versions">
+    A dropdown for multiple releases of the same content, each with its own structure
+  </Card>
+  <Card title="Products" icon="fa-duotone fa-grid-2" href="/learn/docs/configuration/products">
+    A switcher for distinct offerings, each with its own navigation, tabs, and versions
+  </Card>
+</CardGroup>
+
+Each navigation layer is optional, and each one adds a segment to your page URLs unless you [skip its slug](/learn/docs/seo/configuring-slugs). You can use these layers individually or in combination with each other. Outer layers wrap inner ones: a product contains versions, a version contains tabs, and a tab contains sections.
+
+```yaml docs.yml
+products:
+  - display-name: Product A
+    path: ./products/product-a/product-a.yml
+```
+
+```yaml product-a.yml
+tabs:
+  guides:
+    display-name: Guides
+navigation:
+  - tab: guides
+    layout:
+      - section: Get started
+        contents:
+          - page: Quickstart
+            path: ./pages/quickstart.mdx
+```
+
+Which files hold the `navigation` key depends on the layers you use. Unversioned single-product sites keep it in `docs.yml`; products and versions each move it into their own `.yml` file. [Project structure](/learn/docs/getting-started/project-structure) shows the resulting file layouts.
+
+## Sidebar entry types
+
+Inside a section's `contents`, each entry is one of the following types.
+
+| Entry | Renders | Reference |
+|-------|---------|-----------|
+| `page` | A single Markdown or MDX file | [Add a page](/learn/docs/configuration/navigation#add-a-page) |
+| `folder` | Every file in a directory, auto-titled and auto-sorted | [Add a folder](/learn/docs/configuration/navigation#add-a-folder) |
+| `section` | A group of nested entries, optionally with its own overview page | [Add a section](/learn/docs/configuration/navigation#add-a-section) |
+| `api` | A generated API Reference | [API References](/learn/docs/api-references/overview) |
+| `changelog` | A dated timeline of release entries | [Changelog pages](/learn/docs/configuration/changelogs) |
+| `link` | An external URL in the sidebar | [Links](/learn/docs/configuration/navigation#links) |
+
+## Per-entry controls
+
+These properties apply to individual navigation entries, regardless of which layer they sit under.
+
+| Control | Effect |
+|---------|--------|
+| [`icon`](/learn/docs/configuration/navigation#sidebar-icons) | Adds a Font Awesome icon, image file, or inline SVG next to the entry |
+| [`slug` and `skip-slug`](/learn/docs/seo/configuring-slugs) | Renames the entry's URL segment or drops it from the path |
+| [`hidden`](/learn/docs/customization/hiding-content) | Keeps the entry out of the sidebar and search while leaving its URL reachable |
+| [`availability`](/learn/docs/configuration/navigation#availability) | Marks lifecycle status with a badge, inherited by child entries |
+| [`collapsed`](/learn/docs/configuration/navigation#collapsed-sections-or-folders) | Controls whether a section or folder starts collapsed |
+| [`viewers`](/learn/docs/authentication/features/rbac) | Restricts the entry to readers holding a given role |
+
+Individual pages can also override navigation-derived behavior from their own [frontmatter](/learn/docs/configuration/page-level-settings), including title, slug, and layout.
+
+## Beyond the sidebar
+
+Navbar links, the logo, the footer, and site-wide layout are [site-level settings](/learn/docs/configuration/site-level-settings) rather than navigation entries. Search behavior across your navigation is covered in [search configuration](/learn/docs/customization/search).
@@ -8,19 +8,6 @@ max-toc-depth: 3
 
 The `navigation` key in `docs.yml` defines your sidebar structure. Build it by combining sections, pages, and folders.
 
-<Info title="API Reference section">
-Use the special `api` key to create a [generated API Reference section](/learn/docs/api-references/overview).
-
-```yaml docs.yml
-navigation:
-  - section: Introduction
-    contents:
-      - page: My page
-        path: ./pages/my-page.mdx
-  - api: API Reference
-```
-</Info>
-
 ### Add a section
 
 Sections organize your documentation in the left-side nav bar. Each section has a name and a list of `contents`, which can include pages, folders, or nested sections.
@@ -76,6 +63,19 @@ navigation:
 
 Sections also support [`slug` and `skip-slug`](/learn/docs/seo/configuring-slugs) to customize URL paths.
 
+<Info title="API Reference section">
+Use the special `api` key to create a [generated API Reference section](/learn/docs/api-references/overview).
+
+```yaml docs.yml
+navigation:
+  - section: Introduction
+    contents:
+      - page: My page
+        path: ./pages/my-page.mdx
+  - api: API Reference
+```
+</Info>
+
 ### Add a page
 
 Create an `.md` or `.mdx` file, then add a `page` entry to a section's `contents` with the file path.

@@ -5,39 +5,18 @@ description: Understand how to configure your Fern documentation site at the sit
 ---
 
 
-Fern documentation is configured at two levels: **site-level** settings in `docs.yml` that apply globally, and **page-level** settings in frontmatter that control individual pages.
+Fern documentation is configured at two levels: **site-level** settings in `docs.yml` that apply globally, and **page-level** settings in frontmatter that control individual pages. Where both set the same property, such as a title, slug, or layout, the page's frontmatter wins.
 
-## Site-level configuration
+`docs.yml` covers two concerns. Site-level settings determine how the site looks and behaves — branding, layout, navbar links, and analytics. Navigation determines what the site contains: which files become pages, how they group into sections, and what URL each one gets. Navigation is where most structural decisions land, so it spans several pages of its own.
 
-The `docs.yml` file controls your site's appearance, structure, and behavior. All of the settings below are configured in `docs.yml`.
-
-<CardGroup cols={2}>
-  <Card title="Site-level settings" icon="fa-duotone fa-sliders" href="/learn/docs/configuration/site-level-settings">
+<CardGroup cols={3}>
+  <Card title="Site settings" icon="fa-duotone fa-sliders" href="/learn/docs/configuration/site-level-settings">
     Colors, typography, logo, layout, navbar links, and analytics
   </Card>
-  <Card title="Sections, pages, and folders" icon="fa-duotone fa-bars" href="/learn/docs/configuration/navigation">
-    Organize your sidebar with sections, pages, and folders
-  </Card>
-  <Card title="Tabs" icon="fa-duotone fa-folder-open" href="/learn/docs/configuration/tabs">
-    Group content into switchable tabs with optional variants
-  </Card>
-  <Card title="Versions" icon="fa-duotone fa-code-branch" href="/learn/docs/configuration/versions">
-    Add a dropdown version selector for multiple doc versions
-  </Card>
-  <Card title="Products" icon="fa-duotone fa-grid-2" href="/learn/docs/configuration/products">
-    Add a product switcher for multi-product sites
+  <Card title="Page settings" icon="fa-duotone fa-file-lines" href="/learn/docs/configuration/page-level-settings">
+    Titles, descriptions, slugs, layout, availability badges, and more
   </Card>
-  <Card title="Changelog" icon="fa-duotone fa-clock-rotate-left" href="/learn/docs/configuration/changelogs">
-    Chronological record of changes with search, tagging, and RSS
+  <Card title="Navigation" icon="fa-duotone fa-sitemap" href="/learn/docs/configuration/navigation-overview">
+    Products, versions, tabs, sections, folders, and pages
   </Card>
 </CardGroup>
-
-## Page-level configuration
-
-Use frontmatter in individual `.mdx` files to override site-level defaults for a specific page, such as titles, meta descriptions, slugs, layout, and visibility of page elements.
-
-<CardGroup cols={2}>
-<Card title="Page-level settings" icon="fa-duotone fa-file-lines" href="/learn/docs/configuration/page-level-settings">
-  Titles, descriptions, slugs, layout, availability badges, and more
-</Card>
-</CardGroup>
@@ -1,12 +1,13 @@
 ---
 title: Products
 subtitle: Add a product switcher for multi-product documentation sites
+description: Configure multi-product documentation in Fern, including the product switcher, per-product navigation, and internal and external products.
 ---
 
 
 <Markdown src="/snippets/team-plan.mdx"/>
 
-Add a product switcher for multi-product documentation sites. Each product can have its own navigation, tabs, versions, and API references, and products can share content.
+Products add a switcher to your docs for documenting distinct offerings. Each product can contain its own navigation, tabs, versions, and API references, and products can share content.
 
 Products can be internal (hosted on your site) or external (linking to external URLs).
 

@@ -1,5 +1,5 @@
 ---
-title: Site-level settings
+title: Site settings
 subtitle: Customize colors, typography, logo, layout, navbar links, and analytics in `docs.yml`
 description: "Learn how to configure your Fern documentation site with the docs.yml file. Customize colors, typography, layout, analytics and more."
 max-toc-depth: 2

@@ -6,7 +6,7 @@ max-toc-depth: 3
 ---
 
 
-Tabs let you group sections of your documentation together, while tab variants allow you to display different content perspectives within a single tab.
+Tabs split a product or version into parallel bodies of content, each with its own sidebar. Tab variants offer alternate versions of a single tab's content for different audiences, such as beginner versus advanced.
 
 ## Tabs
 

@@ -1,12 +1,13 @@
 ---
 title: Versions
 subtitle: Add a dropdown version selector for multiple doc versions
+description: Configure versioned documentation in Fern, including the version dropdown, per-version navigation, and sharing content across versions.
 ---
 
 
 <Markdown src="/snippets/team-plan.mdx"/>
 
-Each version of your docs can contain its own distinct tabs, sections, pages, and API references. Versions can also share content.
+Versions add a dropdown to your docs for multiple releases of the same content. Each version can contain its own tabs, sections, pages, and API references, and versions can share content.
 
 <Frame>
 ![A dropdown of the available versions](assets/versions.png)
-Original file line number
+Diff line change
@@ Expand Up / @@ -6,7 +6,7 @@ max-toc-depth: 3 @@
     ---
-    Tabs let you group sections of your documentation together, while tab variants allow you to display different content perspectives within a single tab.
+    Tabs split a product or version into parallel bodies of content, each with its own sidebar. Tab variants offer alternate versions of a single tab's content for different audiences, such as beginner versus advanced.
     ## Tabs
@@ Expand Down @@