diff --git a/fern/products/docs/docs.yml b/fern/products/docs/docs.yml
index c46be377c..49b103847 100644
--- a/fern/products/docs/docs.yml
+++ b/fern/products/docs/docs.yml
@@ -19,6 +19,9 @@ navigation:
path: ./pages/customization/what-is-docs-yml.mdx
- page: Navigation
path: ./pages/navigation/overview.mdx
+ - page: Tabs and tab variants
+ path: ./pages/navigation/tabs.mdx
+ slug: tabs
- page: Versions
path: ./pages/navigation/versions.mdx
- page: Products
diff --git a/fern/products/docs/pages/changelog/2025-11-03.mdx b/fern/products/docs/pages/changelog/2025-11-03.mdx
index 061be33e5..c74882d81 100644
--- a/fern/products/docs/pages/changelog/2025-11-03.mdx
+++ b/fern/products/docs/pages/changelog/2025-11-03.mdx
@@ -1,3 +1,30 @@
+## Tab variants
+
+Create multiple content variations within a single tab using the new variants feature. This allows you to show different perspectives, user types, or implementation approaches for the same topic without creating separate tabs.
+
+You can now define variants for tabs with different layouts, titles, subtitles, and icons. Each variant can have its own navigation structure, and you can explicitly set which variant should be the default.
+
+```yaml title="docs.yml"
+navigation:
+ - tab: guides
+ variants:
+ - title: For developers
+ layout:
+ - section: Getting started
+ contents:
+ - page: Quick start
+ path: ./pages/dev-quickstart.mdx
+ - title: For product managers
+ default: true
+ layout:
+ - section: Getting started
+ contents:
+ - page: Overview
+ path: ./pages/pm-overview.mdx
+```
+
+[Learn more about tab variants](/learn/docs/configuration/tabs).
+
## Custom icons across your navigation
You can now use your own image files as icons throughout your `docs.yml` navigation config, including for [navbar link](/learn/docs/configuration/what-is-docs-yml#navbar-links-configuration), [section, page](/learn/docs/configuration/navigation#sidebar-icons), and [product](/learn/docs/configuration/products#add-your-product-configuration) icons.
@@ -44,3 +71,4 @@ products:
```
Visit the [product switching documentation](/learn/docs/configuration/products#define-your-products) to learn more.
+
diff --git a/fern/products/docs/pages/navigation/overview.mdx b/fern/products/docs/pages/navigation/overview.mdx
index 3acb1e4c1..f9d2f05b0 100644
--- a/fern/products/docs/pages/navigation/overview.mdx
+++ b/fern/products/docs/pages/navigation/overview.mdx
@@ -242,59 +242,7 @@ navigation:
## Tabs
-Within the navigation, you can add `tabs`. Tabs are used to group sections together. The example below shows tabs for `Help Center`, `API Reference`, and an external link to `Github`. Each tab has a `title` and `icon`.
-
-
-
-
-{/* */}
-
-```yaml
-tabs:
- api:
- display-name: API Reference
- icon: puzzle # Font Awesome icon
- help:
- display-name: Help center
- icon: ./assets/icons/help-icon.svg # Custom image file
- github:
- display-name: GitHub
- icon: brands github # Font Awesome icon
- href: https://github.com/fern-api/fern
-
- navigation:
- - tab: api
- layout:
- - section: Introduction
- contents:
- - page: My page
- path: my-page.mdx
- - api: API Reference
- - tab: help
- layout:
- - section: Help center
- contents:
- - page: Contact us
- path: contact-us.mdx
- - tab: github
-```
-{/* */}
-
-
-Here's an example of what the Tabs implementation looks like:
-
-
-
-
-
-Tabs display in the left sidebar by default. To display them horizontally, set `tabs-placement` to `header` in your [layout configuration](/docs/configuration/what-is-docs-yml#layout-configuration).
-
-
-```yaml
-layout:
- tabs-placement: header
-```
-
+You can add tabs to group sections of content together. Tabs can contain different layouts and navigation structures, and you can use tab variants to show different content variations within a single tab. For more information, see [Tabs and tab variants](/learn/docs/configuration/tabs).
## Versions
diff --git a/fern/products/docs/pages/navigation/tabs.mdx b/fern/products/docs/pages/navigation/tabs.mdx
new file mode 100644
index 000000000..52ad69c2e
--- /dev/null
+++ b/fern/products/docs/pages/navigation/tabs.mdx
@@ -0,0 +1,160 @@
+---
+title: Tabs and tab variants
+description: Organize your documentation with tabs and show different content variations using tab variants.
+---
+
+Tabs let you group sections of your documentation together, while tab variants allow you to display different content perspectives within a single tab.
+
+## 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 `title` and `icon`.
+
+
+{/* */}
+
+```yaml title="docs.yml"
+tabs:
+ api:
+ display-name: API Reference
+ icon: puzzle # Font Awesome icon
+ help:
+ display-name: Help center
+ icon: ./assets/icons/help-icon.svg # Custom image file
+ github:
+ display-name: GitHub
+ icon: brands github # Font Awesome icon
+ href: https://github.com/fern-api/fern
+
+ navigation:
+ - tab: api
+ layout:
+ - section: Introduction
+ contents:
+ - page: My page
+ path: my-page.mdx
+ - api: API Reference
+ - tab: help
+ layout:
+ - section: Help center
+ contents:
+ - page: Contact us
+ path: contact-us.mdx
+ - tab: github
+```
+{/* */}
+
+
+
+
+
+
+Here's an example of how a tabs implementation renders:
+
+
+
+
+
+### Tabs placement
+
+Tabs display in the left sidebar by default. To display them horizontally, set `tabs-placement` to `header` in your [layout configuration](/docs/configuration/what-is-docs-yml#layout-configuration).
+
+
+```yaml
+layout:
+ tabs-placement: header
+```
+
+
+
+## Tab variants
+
+Tab variants let you display different content variations within a single tab, and [support RBAC](/learn/docs/authentication/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).
+
+
+### Basic usage
+
+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.
+
+```yaml title="docs.yml" startLine=20 {22-34}
+tabs:
+ api:
+ display-name: API Reference
+ icon: puzzle
+ help:
+ display-name: Help center
+ icon: home
+ github:
+ display-name: GitHub
+ icon: brands github
+ href: https://github.com/fern-api/fern
+
+navigation:
+ - tab: api
+ layout:
+ - section: Introduction
+ contents:
+ - page: My page
+ path: my-page.mdx
+ - api: API Reference
+ - tab: help
+ variants:
+ - title: For developers
+ layout:
+ - section: Getting started
+ contents:
+ - page: Quick start
+ path: ./pages/dev-quickstart.mdx
+ - title: For product managers
+ layout:
+ - section: Getting started
+ contents:
+ - page: Overview
+ path: ./pages/pm-overview.mdx
+ - tab: github
+```
+
+### Variant properties
+
+
+ Display name for the variant
+
+
+
+ Navigation structure using the same format as regular tab layouts
+
+
+
+ Text displayed below the variant title
+
+
+
+
+
+
+
+ Custom URL slug for the variant
+
+
+
+ Exclude the variant slug from URLs
+
+
+
+ Hide the variant from navigation
+
+
+
+ When true, this variant displays by default. If not specified, the first variant in the list is used.
+
+
+
+ Role-based access control for the variant
+
+
+
+ Conditional display configuration
+
+
diff --git a/fern/snippets/icons.mdx b/fern/snippets/icons.mdx
index 4e8e3fac2..085b030e3 100644
--- a/fern/snippets/icons.mdx
+++ b/fern/snippets/icons.mdx
@@ -1,4 +1,4 @@
-Icons support three formats:
+Icons can be in three formats:
- **Font Awesome icons**: Use icon names like `fa-solid fa-rocket`. Pro and Brand Icons from Font Awesome are supported.
- **Custom image files**: Use relative paths to image files (e.g., `./assets/icons/my-icon.svg` or `../assets/icons/my-icon.png`). Paths are relative to the `docs.yml` file.
- **Inline SVG**: Provide an SVG string wrapped in quotes (e.g., `""`).
\ No newline at end of file
-
-
-Tabs display in the left sidebar by default. To display them horizontally, set `tabs-placement` to `header` in your [layout configuration](/docs/configuration/what-is-docs-yml#layout-configuration).
-
-