From af8d5efd01f2a49a5b4d9b54d8fc648dfef13101 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Mon, 3 Nov 2025 15:43:41 +0000 Subject: [PATCH 1/5] 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 --- fern/products/docs/docs.yml | 2 + .../docs/pages/changelog/2025-11-03.mdx | 26 +++ .../docs/pages/navigation/tab-variants.mdx | 192 ++++++++++++++++++ 3 files changed, 220 insertions(+) create mode 100644 fern/products/docs/pages/changelog/2025-11-03.mdx create mode 100644 fern/products/docs/pages/navigation/tab-variants.mdx diff --git a/fern/products/docs/docs.yml b/fern/products/docs/docs.yml index dc898fec9..64aeba9dd 100644 --- a/fern/products/docs/docs.yml +++ b/fern/products/docs/docs.yml @@ -19,6 +19,8 @@ navigation: path: ./pages/customization/what-is-docs-yml.mdx - page: Navigation path: ./pages/navigation/overview.mdx + - page: Tab variants + path: ./pages/navigation/tab-variants.mdx - 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 new file mode 100644 index 000000000..bdca30479 --- /dev/null +++ b/fern/products/docs/pages/changelog/2025-11-03.mdx @@ -0,0 +1,26 @@ +## 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/tab-variants) diff --git a/fern/products/docs/pages/navigation/tab-variants.mdx b/fern/products/docs/pages/navigation/tab-variants.mdx new file mode 100644 index 000000000..f9b4f8448 --- /dev/null +++ b/fern/products/docs/pages/navigation/tab-variants.mdx @@ -0,0 +1,192 @@ +--- +title: Tab variants +description: Create multiple content variations within a single tab using variants in Fern Docs navigation. +--- + +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. + +## Basic usage + +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. + +```yaml title="docs.yml" +tabs: + guides: + display-name: Guides + icon: book + +navigation: + - tab: guides + variants: + - title: For developers + layout: + - section: Getting started + contents: + - page: Quick start + path: ./pages/dev-quickstart.mdx + - page: API integration + path: ./pages/dev-api.mdx + - title: For product managers + layout: + - section: Getting started + contents: + - page: Overview + path: ./pages/pm-overview.mdx + - page: Use cases + path: ./pages/pm-use-cases.mdx +``` + +## Setting a default variant + +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. + +```yaml title="docs.yml" {11} +navigation: + - tab: guides + variants: + - title: Advanced + layout: + - section: Advanced topics + contents: + - page: Custom integrations + path: ./pages/advanced.mdx + - title: Beginner + default: true + layout: + - section: Getting started + contents: + - page: Introduction + path: ./pages/intro.mdx +``` + +In this example, the "Beginner" variant displays by default even though it's listed second. + +## Variant properties + +Each variant supports the following properties: + +### Required properties + +- `title` (string): The display name for the variant +- `layout` (list): The navigation structure for this variant, using the same format as regular tab layouts + +### Optional properties + +- `subtitle` (string): A subtitle displayed below the variant title +- `icon` (string): A [Font Awesome icon](https://fontawesome.com/icons) name +- `slug` (string): Custom URL slug for the variant +- `skip-slug` (boolean): If true, the variant slug won't be added to URLs +- `hidden` (boolean): If true, the variant is hidden from the navigation +- `default` (boolean): If true, this variant displays by default +- `viewers` (string or list): Role-based access control for the variant +- `feature-flag` (string or object): Feature flag configuration for conditional display + +## Complete example + +Here's a comprehensive example showing multiple variants with various properties: + +```yaml title="docs.yml" +tabs: + documentation: + display-name: Documentation + icon: book + +navigation: + - tab: documentation + variants: + - title: REST API + subtitle: HTTP-based integration + icon: fa-solid fa-code + slug: rest + default: true + layout: + - section: Authentication + contents: + - page: API keys + path: ./pages/rest/auth.mdx + - api: REST API Reference + + - title: GraphQL API + subtitle: Query-based integration + icon: fa-solid fa-diagram-project + slug: graphql + layout: + - section: Authentication + contents: + - page: OAuth setup + path: ./pages/graphql/auth.mdx + - api: GraphQL API Reference + + - title: SDKs + subtitle: Client libraries + icon: fa-solid fa-cube + slug: sdks + layout: + - section: Client libraries + contents: + - page: TypeScript + path: ./pages/sdks/typescript.mdx + - page: Python + path: ./pages/sdks/python.mdx +``` + +## Use cases + +Tab variants are particularly useful for: + +- **Multiple API types**: Show REST, GraphQL, and gRPC documentation in the same tab +- **User personas**: Provide different content for developers, product managers, and administrators +- **Implementation approaches**: Display different integration methods (SDK, REST API, CLI) +- **Experience levels**: Separate beginner and advanced content +- **Platform-specific guides**: Show iOS, Android, and web documentation variants + +## Variants vs. tabs + +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). + +```yaml title="When to use variants" +# Good: Different approaches to the same topic +navigation: + - tab: integration + variants: + - title: REST API + layout: [...] + - title: GraphQL + layout: [...] +``` + +```yaml title="When to use separate tabs" +# Good: Completely different documentation sections +navigation: + - tab: guides + layout: [...] + - tab: api-reference + layout: [...] +``` + +## Permissions and feature flags + +Variants support role-based access control and feature flags, allowing you to show different content to different users: + +```yaml title="docs.yml" +navigation: + - tab: documentation + variants: + - title: Public documentation + viewers: public + layout: + - section: Getting started + contents: + - page: Introduction + path: ./pages/intro.mdx + + - title: Internal documentation + viewers: internal + layout: + - section: Internal guides + contents: + - page: Architecture + path: ./pages/internal/architecture.mdx +``` + +For more information on permissions, see [Role based access control](/learn/docs/authentication/rbac). From 1e967d01a77aadaa2f86e5885a4ca5bc37c0846a Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Mon, 3 Nov 2025 15:48:16 +0000 Subject: [PATCH 2/5] fix: capitalize API Reference per Vale style guide Co-Authored-By: Colton Berry --- fern/products/docs/pages/navigation/tab-variants.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fern/products/docs/pages/navigation/tab-variants.mdx b/fern/products/docs/pages/navigation/tab-variants.mdx index f9b4f8448..56c2d6680 100644 --- a/fern/products/docs/pages/navigation/tab-variants.mdx +++ b/fern/products/docs/pages/navigation/tab-variants.mdx @@ -142,7 +142,7 @@ Tab variants are particularly useful for: ## Variants vs. tabs -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). +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). ```yaml title="When to use variants" # Good: Different approaches to the same topic From 1103a89f2a99867981915abc259190f66d72d039 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Tue, 4 Nov 2025 15:25:13 -0500 Subject: [PATCH 3/5] clean up pages --- fern/products/docs/docs.yml | 5 +- .../docs/pages/changelog/2025-11-03.mdx | 6 +- .../docs/pages/navigation/overview.mdx | 54 +---------- fern/products/docs/pages/navigation/tabs.mdx | 96 ++++++++----------- fern/snippets/icons.mdx | 2 +- 5 files changed, 48 insertions(+), 115 deletions(-) diff --git a/fern/products/docs/docs.yml b/fern/products/docs/docs.yml index df5917802..49b103847 100644 --- a/fern/products/docs/docs.yml +++ b/fern/products/docs/docs.yml @@ -19,8 +19,9 @@ navigation: path: ./pages/customization/what-is-docs-yml.mdx - page: Navigation path: ./pages/navigation/overview.mdx - - page: Tab variants - path: ./pages/navigation/tab-variants.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 b38a9c1d8..501b053a5 100644 --- a/fern/products/docs/pages/changelog/2025-11-03.mdx +++ b/fern/products/docs/pages/changelog/2025-11-03.mdx @@ -1,4 +1,4 @@ -<<<<<<< HEAD + ## 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. @@ -25,7 +25,7 @@ navigation: ``` [Learn more about tab variants](/learn/docs/configuration/tab-variants) -======= + ## 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. @@ -72,4 +72,4 @@ products: ``` Visit the [product switching documentation](/learn/docs/configuration/products#define-your-products) to learn more. ->>>>>>> 3a88225d8b04d2e44945e09c402114fc08be058c + 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 displayed in the sidebar (default) - - -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 index 164baf3d8..f9c941f0d 100644 --- a/fern/products/docs/pages/navigation/tabs.mdx +++ b/fern/products/docs/pages/navigation/tabs.mdx @@ -1,16 +1,18 @@ --- title: Tabs and tab variants -description: Create multiple content variations within a single tab using variants in Fern Docs navigation. +description: Organize your documentation with tabs and show different content variations using tab variants. --- -Within the navigation, you can 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`. +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 +```yaml title="docs.yml" tabs: api: display-name: API Reference @@ -42,12 +44,18 @@ tabs: {/* */} -Here's an example of what the Tabs implementation looks like: + + + + +Here's an example of how a tabs implementation renders: Tabs displayed in the sidebar (default) +### 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). @@ -60,7 +68,7 @@ layout: ## Tab variants -Tab variants let you display different content variations within a single tab. This is useful for showing different user types, implementation approaches, or experience levels without creating separate tabs. +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). @@ -68,16 +76,30 @@ Tab variants let you display different content variations within a single tab. T ### Basic usage -Define a tab with a `variants` property instead of a `layout` property. Each variant has its own title and layout. - -```yaml title="docs.yml" -tabs: - guides: - display-name: Guides - icon: book +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. -navigation: - - tab: guides +```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: @@ -91,12 +113,9 @@ navigation: contents: - page: Overview path: ./pages/pm-overview.mdx + - tab: github ``` - -Variants support role-based access control. For more information, see [Role based access control](/learn/docs/authentication/rbac). - - ### Variant properties @@ -112,7 +131,7 @@ Variants support role-based access control. For more information, see [Role base - [Font Awesome icon](https://fontawesome.com/icons) name + @@ -139,38 +158,3 @@ Variants support role-based access control. For more information, see [Role base Conditional display configuration - - -```yaml title="docs.yml" -tabs: - documentation: - display-name: Documentation - icon: book - -navigation: - - tab: documentation - variants: - - title: REST API - subtitle: HTTP-based integration - icon: fa-solid fa-code - slug: rest - default: true - layout: - - section: Authentication - contents: - - page: API keys - path: ./pages/rest/auth.mdx - - api: REST API Reference - - - title: GraphQL API - subtitle: Query-based integration - icon: fa-solid fa-diagram-project - slug: graphql - layout: - - section: Authentication - contents: - - page: OAuth setup - path: ./pages/graphql/auth.mdx - - api: GraphQL API Reference -``` - \ No newline at end of file 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 From 751311c9954268a5cad4638b18efabb88db0dd26 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Tue, 4 Nov 2025 15:25:50 -0500 Subject: [PATCH 4/5] vale nit --- fern/products/docs/pages/navigation/tabs.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fern/products/docs/pages/navigation/tabs.mdx b/fern/products/docs/pages/navigation/tabs.mdx index f9c941f0d..52ad69c2e 100644 --- a/fern/products/docs/pages/navigation/tabs.mdx +++ b/fern/products/docs/pages/navigation/tabs.mdx @@ -71,7 +71,7 @@ layout: 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). + 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 From c932035092070ffa3174d20f05219365be3f2108 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Tue, 4 Nov 2025 15:28:09 -0500 Subject: [PATCH 5/5] fix link --- fern/products/docs/pages/changelog/2025-11-03.mdx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/fern/products/docs/pages/changelog/2025-11-03.mdx b/fern/products/docs/pages/changelog/2025-11-03.mdx index 501b053a5..c74882d81 100644 --- a/fern/products/docs/pages/changelog/2025-11-03.mdx +++ b/fern/products/docs/pages/changelog/2025-11-03.mdx @@ -1,4 +1,3 @@ - ## 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. @@ -24,7 +23,7 @@ navigation: path: ./pages/pm-overview.mdx ``` -[Learn more about tab variants](/learn/docs/configuration/tab-variants) +[Learn more about tab variants](/learn/docs/configuration/tabs). ## Custom icons across your navigation