docs: add tab variants documentation #1713
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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`. | ||
|
|
||
| <CodeBlock> | ||
| {/* <!-- vale off --> */} | ||
|
|
||
| ```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 | ||
| ``` | ||
| {/* <!-- vale on --> */} | ||
| </CodeBlock> | ||
| <Note title="Tab icons"> | ||
| <Markdown src="/snippets/icons.mdx" /> | ||
| </Note> | ||
| Here's an example of how a tabs implementation renders: | ||
| <Frame> | ||
| <img src="./images/tabs-sidebar.png" alt="Tabs displayed in the sidebar (default)" /> | ||
| </Frame> | ||
| ### 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). | ||
|
|
||
| <CodeBlock title="docs.yml"> | ||
| ```yaml | ||
| layout: | ||
| tabs-placement: header | ||
| ``` | ||
| </CodeBlock> | ||
|
|
||
|
|
||
| ## 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. | ||
|
|
||
| <Tip title="When to use variants vs. 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). | ||
|
Contributor
There was a problem hiding this comment. 📝 [vale] reported by reviewdog 🐶 |
||
| </Tip> | ||
|
|
||
| ### 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 | ||
|
|
||
| <ParamField path="title" type="string" required={true}> | ||
| Display name for the variant | ||
| </ParamField> | ||
|
|
||
| <ParamField path="layout" type="list" required={true}> | ||
| Navigation structure using the same format as regular tab layouts | ||
| </ParamField> | ||
|
|
||
| <ParamField path="subtitle" type="string"> | ||
| Text displayed below the variant title | ||
| </ParamField> | ||
|
|
||
| <ParamField path="icon" type="string"> | ||
| <Markdown src="/snippets/icons.mdx" /> | ||
| </ParamField> | ||
|
|
||
| <ParamField path="slug" type="string"> | ||
| Custom URL slug for the variant | ||
| </ParamField> | ||
|
|
||
| <ParamField path="skip-slug" type="boolean"> | ||
| Exclude the variant slug from URLs | ||
| </ParamField> | ||
|
|
||
| <ParamField path="hidden" type="boolean"> | ||
| Hide the variant from navigation | ||
| </ParamField> | ||
|
|
||
| <ParamField path="default" type="boolean"> | ||
| When true, this variant displays by default. If not specified, the first variant in the list is used. | ||
| </ParamField> | ||
|
|
||
| <ParamField path="viewers" type="string | list"> | ||
| Role-based access control for the variant | ||
| </ParamField> | ||
|
|
||
| <ParamField path="feature-flag" type="string | object"> | ||
| Conditional display configuration | ||
| </ParamField> | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,4 +1,4 @@ | ||
| 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., `"<svg>...</svg>"`). |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
[FernStyles.Current] Avoid time-relative terms like 'now' that become outdated