From d72d88740cca6244a7217beb10e778e2709d02b4 Mon Sep 17 00:00:00 2001 From: "fern-api[bot]" <115122769+fern-api[bot]@users.noreply.github.com> Date: Wed, 29 Jul 2026 19:59:45 +0000 Subject: [PATCH 1/6] Add navigation overview page --- fern/products/docs/docs.yml | 3 + .../pages/navigation/navigation-overview.mdx | 79 +++++++++++++++++++ .../docs/pages/navigation/overview.mdx | 3 + 3 files changed, 85 insertions(+) create mode 100644 fern/products/docs/pages/navigation/navigation-overview.mdx diff --git a/fern/products/docs/docs.yml b/fern/products/docs/docs.yml index 4d4b75c310..29e734fe80 100644 --- a/fern/products/docs/docs.yml +++ b/fern/products/docs/docs.yml @@ -26,6 +26,9 @@ navigation: - section: Navigation skip-slug: true contents: + - page: Navigation overview + path: ./pages/navigation/navigation-overview.mdx + slug: navigation-overview - page: Sections, pages, and folder path: ./pages/navigation/navigation.mdx slug: navigation diff --git a/fern/products/docs/pages/navigation/navigation-overview.mdx b/fern/products/docs/pages/navigation/navigation-overview.mdx new file mode 100644 index 0000000000..6320f67100 --- /dev/null +++ b/fern/products/docs/pages/navigation/navigation-overview.mdx @@ -0,0 +1,79 @@ +--- +title: Navigation overview +subtitle: Understand the levers that shape your site's information architecture +description: Understand how products, versions, tabs, sections, folders, and pages fit together to form the navigation of a Fern documentation site. +--- + +Navigation is defined in YAML, under the `navigation` key. Fern gives you five structural levers, which nest from broadest to narrowest: products, versions, tabs, sections, and pages. A small site needs only sections and pages; larger sites add the outer levers as their content grows. + +## Structural levers + + + + A switcher for distinct offerings, each with its own navigation, tabs, and versions + + + A dropdown for multiple releases of the same content, each with its own structure + + + A top-level row that splits one product or version into parallel bodies of content + + + The sidebar itself: grouped, nestable entries pointing at Markdown files + + + +Each lever is optional and each one adds a segment to your page URLs unless you [skip its slug](/learn/docs/seo/configuring-slugs). The outer levers wrap the 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 levers 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 lever 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, including title, slug, and layout. See [page-level settings](/learn/docs/configuration/page-level-settings). + +## 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). diff --git a/fern/products/docs/pages/navigation/overview.mdx b/fern/products/docs/pages/navigation/overview.mdx index 8ca0f10aed..38bac78baa 100644 --- a/fern/products/docs/pages/navigation/overview.mdx +++ b/fern/products/docs/pages/navigation/overview.mdx @@ -15,6 +15,9 @@ The `docs.yml` file controls your site's appearance, structure, and behavior. Al Colors, typography, logo, layout, navbar links, and analytics + + How products, versions, tabs, sections, and pages fit together + Organize your sidebar with sections, pages, and folders From e198658555c4f6fab17c33547264fe961e42b5c0 Mon Sep 17 00:00:00 2001 From: "fern-api[bot]" <115122769+fern-api[bot]@users.noreply.github.com> Date: Wed, 29 Jul 2026 20:06:14 +0000 Subject: [PATCH 2/6] Slim configuration overview and move page-level settings above navigation --- fern/products/docs/docs.yml | 6 ++-- .../docs/pages/navigation/overview.mdx | 36 +++---------------- 2 files changed, 8 insertions(+), 34 deletions(-) diff --git a/fern/products/docs/docs.yml b/fern/products/docs/docs.yml index 29e734fe80..9271a7ba0a 100644 --- a/fern/products/docs/docs.yml +++ b/fern/products/docs/docs.yml @@ -23,6 +23,9 @@ navigation: - page: Site-level settings path: ./pages/navigation/site-level-settings.mdx slug: site-level-settings + - page: Page-level settings + path: ./pages/navigation/frontmatter.mdx + slug: page-level-settings - section: Navigation skip-slug: true contents: @@ -42,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 diff --git a/fern/products/docs/pages/navigation/overview.mdx b/fern/products/docs/pages/navigation/overview.mdx index 38bac78baa..e9f6d1c92a 100644 --- a/fern/products/docs/pages/navigation/overview.mdx +++ b/fern/products/docs/pages/navigation/overview.mdx @@ -7,40 +7,14 @@ 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. -## Site-level configuration - -The `docs.yml` file controls your site's appearance, structure, and behavior. All of the settings below are configured in `docs.yml`. - - + Colors, typography, logo, layout, navbar links, and analytics - - How products, versions, tabs, sections, and pages fit together - - - Organize your sidebar with sections, pages, and folders - - - Group content into switchable tabs with optional variants - - - Add a dropdown version selector for multiple doc versions + + Titles, descriptions, slugs, layout, availability badges, and more - - Add a product switcher for multi-product sites + + Products, versions, tabs, sections, folders, and pages - - Chronological record of changes with search, tagging, and RSS - - - -## 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. - - - - Titles, descriptions, slugs, layout, availability badges, and more - From cff9d3a93f5f45fe329eed031c804502f6e5e5bc Mon Sep 17 00:00:00 2001 From: "fern-api[bot]" <115122769+fern-api[bot]@users.noreply.github.com> Date: Wed, 29 Jul 2026 20:08:28 +0000 Subject: [PATCH 3/6] Connect the configuration overview cards with framing text --- fern/products/docs/pages/navigation/overview.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/fern/products/docs/pages/navigation/overview.mdx b/fern/products/docs/pages/navigation/overview.mdx index e9f6d1c92a..9a7f88dd4a 100644 --- a/fern/products/docs/pages/navigation/overview.mdx +++ b/fern/products/docs/pages/navigation/overview.mdx @@ -5,7 +5,9 @@ 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. + +`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. From 3b25f093eca209d5655627438263ba2ece67d052 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Wed, 29 Jul 2026 16:29:29 -0400 Subject: [PATCH 4/6] small edits --- fern/products/docs/docs.yml | 8 ++++---- fern/products/docs/pages/navigation/frontmatter.mdx | 2 +- .../docs/pages/navigation/navigation-overview.mdx | 4 ++-- fern/products/docs/pages/navigation/overview.mdx | 4 ++-- .../docs/pages/navigation/site-level-settings.mdx | 2 +- fern/products/docs/pages/navigation/tabs.mdx | 2 +- 6 files changed, 11 insertions(+), 11 deletions(-) diff --git a/fern/products/docs/docs.yml b/fern/products/docs/docs.yml index 9271a7ba0a..b694887d8a 100644 --- a/fern/products/docs/docs.yml +++ b/fern/products/docs/docs.yml @@ -20,19 +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-level settings + - page: Page settings path: ./pages/navigation/frontmatter.mdx slug: page-level-settings - section: Navigation skip-slug: true contents: - - page: Navigation overview + - page: Overview path: ./pages/navigation/navigation-overview.mdx slug: navigation-overview - - page: Sections, pages, and folder + - page: Sections, pages, and folders path: ./pages/navigation/navigation.mdx slug: navigation - page: Tabs and tab variants diff --git a/fern/products/docs/pages/navigation/frontmatter.mdx b/fern/products/docs/pages/navigation/frontmatter.mdx index 700d6e2632..08393ddee7 100644 --- a/fern/products/docs/pages/navigation/frontmatter.mdx +++ b/fern/products/docs/pages/navigation/frontmatter.mdx @@ -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. --- diff --git a/fern/products/docs/pages/navigation/navigation-overview.mdx b/fern/products/docs/pages/navigation/navigation-overview.mdx index 6320f67100..cac93a02d6 100644 --- a/fern/products/docs/pages/navigation/navigation-overview.mdx +++ b/fern/products/docs/pages/navigation/navigation-overview.mdx @@ -4,7 +4,7 @@ subtitle: Understand the levers that shape your site's information architecture description: Understand how products, versions, tabs, sections, folders, and pages fit together to form the navigation of a Fern documentation site. --- -Navigation is defined in YAML, under the `navigation` key. Fern gives you five structural levers, which nest from broadest to narrowest: products, versions, tabs, sections, and pages. A small site needs only sections and pages; larger sites add the outer levers as their content grows. +Your site's information architecture is defined under the `navigation` key of the `docs.yml`. Fern gives you five structural levers, which nest from broadest to narrowest: products, versions, tabs, sections, and pages. A small site needs only sections and pages; larger sites add the outer levers as their content grows. ## Structural levers @@ -23,7 +23,7 @@ Navigation is defined in YAML, under the `navigation` key. Fern gives you five s -Each lever is optional and each one adds a segment to your page URLs unless you [skip its slug](/learn/docs/seo/configuring-slugs). The outer levers wrap the inner ones: a product contains versions, a version contains tabs, and a tab contains sections. +Each structural navigation lever 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 levers individually or in combination with each other. The outer levers wrap the inner ones: a product contains versions, a version contains tabs, and a tab contains sections. ```yaml docs.yml products: diff --git a/fern/products/docs/pages/navigation/overview.mdx b/fern/products/docs/pages/navigation/overview.mdx index 9a7f88dd4a..be920acb22 100644 --- a/fern/products/docs/pages/navigation/overview.mdx +++ b/fern/products/docs/pages/navigation/overview.mdx @@ -10,10 +10,10 @@ Fern documentation is configured at two levels: **site-level** settings in `docs `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. - + Colors, typography, logo, layout, navbar links, and analytics - + Titles, descriptions, slugs, layout, availability badges, and more diff --git a/fern/products/docs/pages/navigation/site-level-settings.mdx b/fern/products/docs/pages/navigation/site-level-settings.mdx index e96c7f19ab..b740f3c7f0 100644 --- a/fern/products/docs/pages/navigation/site-level-settings.mdx +++ b/fern/products/docs/pages/navigation/site-level-settings.mdx @@ -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 diff --git a/fern/products/docs/pages/navigation/tabs.mdx b/fern/products/docs/pages/navigation/tabs.mdx index 723affa49b..70a67c398e 100644 --- a/fern/products/docs/pages/navigation/tabs.mdx +++ b/fern/products/docs/pages/navigation/tabs.mdx @@ -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 group sections of your documentation together, while tab variants display different content perspectives within a single tab. ## Tabs From 6b46f58d8fa29ff0446cb1575778a4eaaf797843 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Thu, 30 Jul 2026 11:50:07 -0400 Subject: [PATCH 5/6] edits --- .../docs/pages/navigation/changelogs.mdx | 3 +- .../pages/navigation/navigation-overview.mdx | 30 +++++++++---------- .../docs/pages/navigation/navigation.mdx | 26 ++++++++-------- .../docs/pages/navigation/products.mdx | 3 +- fern/products/docs/pages/navigation/tabs.mdx | 2 +- .../docs/pages/navigation/versions.mdx | 3 +- 6 files changed, 35 insertions(+), 32 deletions(-) diff --git a/fern/products/docs/pages/navigation/changelogs.mdx b/fern/products/docs/pages/navigation/changelogs.mdx index bc22b3bdb8..20c36b1d35 100644 --- a/fern/products/docs/pages/navigation/changelogs.mdx +++ b/fern/products/docs/pages/navigation/changelogs.mdx @@ -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. - - A switcher for distinct offerings, each with its own navigation, tabs, and versions - - - A dropdown for multiple releases of the same content, each with its own structure + + The sidebar itself: grouped, nestable entries pointing at Markdown files A top-level row that splits one product or version into parallel bodies of content - - The sidebar itself: grouped, nestable entries pointing at Markdown files + + A dropdown for multiple releases of the same content, each with its own structure + + + A switcher for distinct offerings, each with its own navigation, tabs, and versions -Each structural navigation lever 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 levers individually or in combination with each other. The outer levers wrap the inner ones: a product contains versions, a version contains tabs, and a tab contains sections. +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: @@ -44,7 +44,7 @@ navigation: path: ./pages/quickstart.mdx ``` -Which files hold the `navigation` key depends on the levers 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. +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 @@ -61,7 +61,7 @@ Inside a section's `contents`, each entry is one of the following types. ## Per-entry controls -These properties apply to individual navigation entries, regardless of which lever they sit under. +These properties apply to individual navigation entries, regardless of which layer they sit under. | Control | Effect | |---------|--------| @@ -72,7 +72,7 @@ These properties apply to individual navigation entries, regardless of which lev | [`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, including title, slug, and layout. See [page-level settings](/learn/docs/configuration/page-level-settings). +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 diff --git a/fern/products/docs/pages/navigation/navigation.mdx b/fern/products/docs/pages/navigation/navigation.mdx index 955e480608..b0c9d1e677 100644 --- a/fern/products/docs/pages/navigation/navigation.mdx +++ b/fern/products/docs/pages/navigation/navigation.mdx @@ -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. - -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 -``` - - ### 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. + +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 +``` + + ### Add a page Create an `.md` or `.mdx` file, then add a `page` entry to a section's `contents` with the file path. diff --git a/fern/products/docs/pages/navigation/products.mdx b/fern/products/docs/pages/navigation/products.mdx index 4f03c12a13..958795c3dd 100644 --- a/fern/products/docs/pages/navigation/products.mdx +++ b/fern/products/docs/pages/navigation/products.mdx @@ -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. --- -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). diff --git a/fern/products/docs/pages/navigation/tabs.mdx b/fern/products/docs/pages/navigation/tabs.mdx index 70a67c398e..600cb23c56 100644 --- a/fern/products/docs/pages/navigation/tabs.mdx +++ b/fern/products/docs/pages/navigation/tabs.mdx @@ -6,7 +6,7 @@ max-toc-depth: 3 --- -Tabs group sections of your documentation together, while tab variants 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 diff --git a/fern/products/docs/pages/navigation/versions.mdx b/fern/products/docs/pages/navigation/versions.mdx index f20560f00f..1505319d52 100644 --- a/fern/products/docs/pages/navigation/versions.mdx +++ b/fern/products/docs/pages/navigation/versions.mdx @@ -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. --- -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. ![A dropdown of the available versions](assets/versions.png) From 2cbeee74412b4b124db0554441187ab347ccaf27 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Thu, 30 Jul 2026 14:55:29 -0400 Subject: [PATCH 6/6] updates --- fern/products/docs/docs.yml | 2 +- .../pages/navigation/navigation-overview.mdx | 59 ++++------------- .../docs/pages/navigation/navigation.mdx | 8 +-- fern/products/docs/pages/navigation/tabs.mdx | 66 +++++++++---------- 4 files changed, 48 insertions(+), 87 deletions(-) diff --git a/fern/products/docs/docs.yml b/fern/products/docs/docs.yml index b694887d8a..32fd453d3e 100644 --- a/fern/products/docs/docs.yml +++ b/fern/products/docs/docs.yml @@ -35,7 +35,7 @@ navigation: - page: Sections, pages, and folders path: ./pages/navigation/navigation.mdx slug: navigation - - page: Tabs and tab variants + - page: Tabs path: ./pages/navigation/tabs.mdx slug: tabs - page: Versions diff --git a/fern/products/docs/pages/navigation/navigation-overview.mdx b/fern/products/docs/pages/navigation/navigation-overview.mdx index 6a12506058..e2afca5cda 100644 --- a/fern/products/docs/pages/navigation/navigation-overview.mdx +++ b/fern/products/docs/pages/navigation/navigation-overview.mdx @@ -4,7 +4,7 @@ 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 nests from narrowest to broadest: pages, sections, tabs, versions, and products. Every layer is optional, and any combination of them is valid. ## Navigation layers @@ -12,7 +12,7 @@ Your site's navigation is defined under the `navigation` key of `docs.yml`. Navi The sidebar itself: grouped, nestable entries pointing at Markdown files - + A top-level row that splits one product or version into parallel bodies of content @@ -23,57 +23,20 @@ Your site's navigation is defined under the `navigation` key of `docs.yml`. Navi -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. +Outer layers wrap inner ones: a product contains versions, a version contains tabs, and a tab contains sections. Each layer a page sits under adds a segment to its URL. You can [rename or drop any segment](/learn/docs/seo/configuring-slugs), and a page's own [frontmatter](/learn/docs/configuration/page-level-settings) can override its title, slug, and layout. -```yaml docs.yml -products: - - display-name: Product A - path: ./products/product-a/product-a.yml -``` +## Other sidebar entries -```yaml product-a.yml -tabs: - guides: - display-name: Guides -navigation: - - tab: guides - layout: - - section: Get started - contents: - - page: Quickstart - path: ./pages/quickstart.mdx -``` +A sidebar can also hold three entries that aren't layers: -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. +- An [API Reference](/learn/docs/api-references/overview) generated from your API definition. +- A [changelog](/learn/docs/configuration/changelogs) that renders a dated timeline of entries. +- A [link](/learn/docs/configuration/navigation#links) pointing at an external URL. -## Sidebar entry types +## Where navigation lives -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. +The `navigation` key holds your sidebar structure, and which file holds that key depends on the layers you use. An unversioned single-product site keeps it in `docs.yml`. Adding [products](/learn/docs/configuration/products) or [versions](/learn/docs/configuration/versions) moves it into a separate `.yml` file for each one. ## 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). +Navbar links, the logo, the footer, and site-wide layout are [site-level settings](/learn/docs/configuration/site-level-settings) rather than navigation entries. How readers search across your navigation is controlled by [search configuration](/learn/docs/customization/search). diff --git a/fern/products/docs/pages/navigation/navigation.mdx b/fern/products/docs/pages/navigation/navigation.mdx index b0c9d1e677..561b95b80f 100644 --- a/fern/products/docs/pages/navigation/navigation.mdx +++ b/fern/products/docs/pages/navigation/navigation.mdx @@ -6,9 +6,9 @@ max-toc-depth: 3 --- -The `navigation` key in `docs.yml` defines your sidebar structure. Build it by combining sections, pages, and folders. +A `page` points at a single Markdown file, a `section` groups entries and can nest more sections, and a `folder` pulls in every file in a directory. -### Add a section +## 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,7 +76,7 @@ navigation: ``` -### Add a page +## Add a page Create an `.md` or `.mdx` file, then add a `page` entry to a section's `contents` with the file path. @@ -90,7 +90,7 @@ navigation: path: ./pages/another-page.mdx ``` -### Add a folder +## Add a folder Add a `folder` entry pointing to a directory. Fern auto-discovers all `.md` and `.mdx` files and adds them to the navigation. diff --git a/fern/products/docs/pages/navigation/tabs.mdx b/fern/products/docs/pages/navigation/tabs.mdx index 600cb23c56..36c0c4f8c6 100644 --- a/fern/products/docs/pages/navigation/tabs.mdx +++ b/fern/products/docs/pages/navigation/tabs.mdx @@ -1,24 +1,27 @@ --- -title: Tabs and tab variants +title: Tabs subtitle: Group content into switchable tabs with optional variants description: Learn how to configure tabs and tab variants in Fern documentation. Group content sections with custom icons and display multiple perspectives. max-toc-depth: 3 --- -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 split a product or version into parallel bodies of content, each with its own sidebar. Tab variants give a single tab more than one version of its content, such as REST versus GraphQL or beginner versus advanced. + +Two tabs make sense when the content is unrelated, like guides and an API Reference. Variants of one tab make sense when it covers the same ground for a different reader. ## Tabs -Add `tabs` to group sections together. The example below shows tabs for `Help Center`, `API Reference`, and an external link to `Github`. Each tab has a `display-name` and `icon`. +To configure tabs: -In the `navigation` section, each tab reference must include either a `layout` (for content) or `variants` (for [tab variants](#tab-variants)). Tabs with an `href` property are external links and must not include `layout` or `variants`. +- Declare each tab under the top-level `tabs` key with a `display-name` and an `icon`. +- Reference the tab in `navigation` with `tab:`. Each tab requires either a `layout` for its content, `variants` for [tab variants](#tab-variants), or an `href` pointing at an external URL. {/* */} ```yaml title="docs.yml" -tabs: +tabs: # Declare each tab api: display-name: API Reference icon: puzzle # Font Awesome icon @@ -31,7 +34,7 @@ tabs: href: https://github.com/fern-api/fern target: _blank # Link opens in a new tab -navigation: +navigation: # Reference each tab by its key - tab: api layout: - section: Introduction @@ -45,21 +48,19 @@ navigation: contents: - page: Contact us path: contact-us.mdx - - tab: github + - tab: github # External link, so no layout ``` {/* */} - - - - -Here's an example of how a tabs implementation renders: - Tabs displayed in the sidebar (default) + + + + ### Tabs placement and styling Tabs display in the left sidebar by default. Use [`theme.tabs`](/learn/docs/configuration/site-level-settings#theme-configuration) to control placement, style, and alignment. @@ -101,7 +102,7 @@ theme: - List of [tab variants](#tab-variants) for displaying different content perspectives. Use instead of `layout`. + List of [tab variants](#tab-variants). Use instead of `layout`. @@ -180,27 +181,14 @@ navigation: ## Tab variants -Tab variants let you display different content variations within a single tab, and [support RBAC](/learn/docs/authentication/features/rbac). This is useful for showing different user types, implementation approaches, or experience levels without creating separate tabs. - - - - - - - Use **variants** for different perspectives on the same content area (REST vs. GraphQL, beginner vs. advanced). Use **tabs** for completely different documentation sections (guides vs. API Reference). - +To add variants to a tab: -### Basic usage +- Replace the tab's `layout` with a `variants` list. The declaration under `tabs:` doesn't change. +- Give each variant a `title` and its own `layout`. -Define a tab with a `variants` property instead of a `layout` property. Each variant has its own title and layout. The example below shows two variants for the `Help Center` tab. +Variants [support RBAC](/learn/docs/authentication/features/rbac), so a variant can be limited to readers holding a given role. -```yaml title="docs.yml" startLine=20 {22-34} +```yaml title="docs.yml" startLine=16 {22-34} tabs: api: display-name: API Reference @@ -222,8 +210,8 @@ navigation: path: my-page.mdx - api: API Reference - tab: help - variants: - - title: For developers + variants: # Replaces this tab's layout + - title: For developers # Each variant has its own title and layout layout: - section: Getting started contents: @@ -238,6 +226,16 @@ navigation: - tab: github ``` + + + + ### Variant properties