Skip to content

Commit af8d5ef

Browse files
devin-ai-integration[bot]coltondotio
devin-ai-integration[bot]
and
coltondotio
committed
docs: add tab variants documentation
- Add comprehensive documentation for the new tab variants feature - Include examples of basic usage, default variants, and all properties - Add use cases and comparison with regular tabs - Include permissions and feature flags examples - Add changelog entry for 2025-11-03 - Add navigation entry in docs.yml Co-Authored-By: Colton Berry <[email protected]>
1 parent 67ad044 commit af8d5ef

File tree

3 files changed

+220
-0
lines changed

3 files changed

+220
-0
lines changed

‎fern/products/docs/docs.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,8 @@ navigation:
1919
path: ./pages/customization/what-is-docs-yml.mdx
2020
- page: Navigation
2121
path: ./pages/navigation/overview.mdx
22+
- page: Tab variants
23+
path: ./pages/navigation/tab-variants.mdx
2224
- page: Versions
2325
path: ./pages/navigation/versions.mdx
2426
- page: Products

‎fern/products/docs/pages/changelog/2025-11-03.mdx‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
## Tab variants
2+
3+
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.
4+
5+
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.
6+
7+
```yaml title="docs.yml"
8+
navigation:
9+
- tab: guides
10+
variants:
11+
- title: For developers
12+
layout:
13+
- section: Getting started
14+
contents:
15+
- page: Quick start
16+
path: ./pages/dev-quickstart.mdx
17+
- title: For product managers
18+
default: true
19+
layout:
20+
- section: Getting started
21+
contents:
22+
- page: Overview
23+
path: ./pages/pm-overview.mdx
24+
```
25+
26+
[Learn more about tab variants](/learn/docs/configuration/tab-variants)

‎fern/products/docs/pages/navigation/tab-variants.mdx‎

Lines changed: 192 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,192 @@
1+
---
2+
title: Tab variants
3+
description: Create multiple content variations within a single tab using variants in Fern Docs navigation.
4+
---
5+
6+
Tab variants allow you to display different content variations within a single tab. This is useful when you want to show different perspectives, user types, or implementation approaches for the same topic without creating separate tabs.
7+
8+
## Basic usage
9+
10+
To use tab variants, define a tab with a `variants` property instead of a `layout` property. Each variant has its own title, layout, and optional configuration.
11+
12+
```yaml title="docs.yml"
13+
tabs:
14+
guides:
15+
display-name: Guides
16+
icon: book
17+
18+
navigation:
19+
- tab: guides
20+
variants:
21+
- title: For developers
22+
layout:
23+
- section: Getting started
24+
contents:
25+
- page: Quick start
26+
path: ./pages/dev-quickstart.mdx
27+
- page: API integration
28+
path: ./pages/dev-api.mdx
29+
- title: For product managers
30+
layout:
31+
- section: Getting started
32+
contents:
33+
- page: Overview
34+
path: ./pages/pm-overview.mdx
35+
- page: Use cases
36+
path: ./pages/pm-use-cases.mdx
37+
```
38+
39+
## Setting a default variant
40+
41+
By default, the first variant in the list is displayed. You can explicitly set which variant should be the default by adding `default: true` to a variant.
42+
43+
```yaml title="docs.yml" {11}
44+
navigation:
45+
- tab: guides
46+
variants:
47+
- title: Advanced
48+
layout:
49+
- section: Advanced topics
50+
contents:
51+
- page: Custom integrations
52+
path: ./pages/advanced.mdx
53+
- title: Beginner
54+
default: true
55+
layout:
56+
- section: Getting started
57+
contents:
58+
- page: Introduction
59+
path: ./pages/intro.mdx
60+
```
61+
62+
In this example, the "Beginner" variant displays by default even though it's listed second.
63+
64+
## Variant properties
65+
66+
Each variant supports the following properties:
67+
68+
### Required properties
69+
70+
- `title` (string): The display name for the variant
71+
- `layout` (list): The navigation structure for this variant, using the same format as regular tab layouts
72+
73+
### Optional properties
74+
75+
- `subtitle` (string): A subtitle displayed below the variant title
76+
- `icon` (string): A [Font Awesome icon](https://fontawesome.com/icons) name
77+
- `slug` (string): Custom URL slug for the variant
78+
- `skip-slug` (boolean): If true, the variant slug won't be added to URLs
79+
- `hidden` (boolean): If true, the variant is hidden from the navigation
80+
- `default` (boolean): If true, this variant displays by default
81+
- `viewers` (string or list): Role-based access control for the variant
82+
- `feature-flag` (string or object): Feature flag configuration for conditional display
83+
84+
## Complete example
85+
86+
Here's a comprehensive example showing multiple variants with various properties:
87+
88+
```yaml title="docs.yml"
89+
tabs:
90+
documentation:
91+
display-name: Documentation
92+
icon: book
93+
94+
navigation:
95+
- tab: documentation
96+
variants:
97+
- title: REST API
98+
subtitle: HTTP-based integration
99+
icon: fa-solid fa-code
100+
slug: rest
101+
default: true
102+
layout:
103+
- section: Authentication
104+
contents:
105+
- page: API keys
106+
path: ./pages/rest/auth.mdx
107+
- api: REST API Reference
108+
109+
- title: GraphQL API
110+
subtitle: Query-based integration
111+
icon: fa-solid fa-diagram-project
112+
slug: graphql
113+
layout:
114+
- section: Authentication
115+
contents:
116+
- page: OAuth setup
117+
path: ./pages/graphql/auth.mdx
118+
- api: GraphQL API Reference
119+
120+
- title: SDKs
121+
subtitle: Client libraries
122+
icon: fa-solid fa-cube
123+
slug: sdks
124+
layout:
125+
- section: Client libraries
126+
contents:
127+
- page: TypeScript
128+
path: ./pages/sdks/typescript.mdx
129+
- page: Python
130+
path: ./pages/sdks/python.mdx
131+
```
132+
133+
## Use cases
134+
135+
Tab variants are particularly useful for:
136+
137+
- **Multiple API types**: Show REST, GraphQL, and gRPC documentation in the same tab
138+
- **User personas**: Provide different content for developers, product managers, and administrators
139+
- **Implementation approaches**: Display different integration methods (SDK, REST API, CLI)
140+
- **Experience levels**: Separate beginner and advanced content
141+
- **Platform-specific guides**: Show iOS, Android, and web documentation variants
142+
143+
## Variants vs. tabs
144+
145+
Use **variants** when you want to show different perspectives or approaches to the same content area. Use **tabs** when you want to organize completely different sections of your documentation (like separating guides from API reference).
146+
147+
```yaml title="When to use variants"
148+
# Good: Different approaches to the same topic
149+
navigation:
150+
- tab: integration
151+
variants:
152+
- title: REST API
153+
layout: [...]
154+
- title: GraphQL
155+
layout: [...]
156+
```
157+
158+
```yaml title="When to use separate tabs"
159+
# Good: Completely different documentation sections
160+
navigation:
161+
- tab: guides
162+
layout: [...]
163+
- tab: api-reference
164+
layout: [...]
165+
```
166+
167+
## Permissions and feature flags
168+
169+
Variants support role-based access control and feature flags, allowing you to show different content to different users:
170+
171+
```yaml title="docs.yml"
172+
navigation:
173+
- tab: documentation
174+
variants:
175+
- title: Public documentation
176+
viewers: public
177+
layout:
178+
- section: Getting started
179+
contents:
180+
- page: Introduction
181+
path: ./pages/intro.mdx
182+
183+
- title: Internal documentation
184+
viewers: internal
185+
layout:
186+
- section: Internal guides
187+
contents:
188+
- page: Architecture
189+
path: ./pages/internal/architecture.mdx
190+
```
191+
192+
For more information on permissions, see [Role based access control](/learn/docs/authentication/rbac).

0 commit comments

Comments
 (0)