Add navigation overview page #6456
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,42 @@ | ||
| --- | ||
| title: Navigation overview | ||
| 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. | ||
| --- | ||
|
|
||
| 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 | ||
|
|
||
| <CardGroup cols={2}> | ||
| <Card title="Sections, pages, and folders" icon="fa-duotone fa-bars" href="/learn/docs/configuration/navigation"> | ||
| The sidebar itself: grouped, nestable entries pointing at Markdown files | ||
| </Card> | ||
| <Card title="Tabs" icon="fa-duotone fa-folder-open" href="/learn/docs/configuration/tabs"> | ||
| A top-level row that splits one product or version into parallel bodies of content | ||
| </Card> | ||
| <Card title="Versions" icon="fa-duotone fa-code-branch" href="/learn/docs/configuration/versions"> | ||
| A dropdown for multiple releases of the same content, each with its own structure | ||
| </Card> | ||
| <Card title="Products" icon="fa-duotone fa-grid-2" href="/learn/docs/configuration/products"> | ||
| A switcher for distinct offerings, each with its own navigation, tabs, and versions | ||
| </Card> | ||
| </CardGroup> | ||
|
|
||
| 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. | ||
|
|
||
| ## Other sidebar entries | ||
|
|
||
| A sidebar can also hold three entries that aren't layers: | ||
|
|
||
| - 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. | ||
|
|
||
| ## Where navigation lives | ||
|
|
||
| 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. How readers search across your navigation is controlled by [search configuration](/learn/docs/customization/search). |
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
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,24 +1,27 @@ | ||
| --- | ||
| 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 give a single tab more than one version of its content, such as REST versus GraphQL or beginner versus advanced. | ||
|
Contributor
There was a problem hiding this comment. 📝 [vale] reported by reviewdog 🐶 |
||
|
|
||
| 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. | ||
|
Contributor
There was a problem hiding this comment. 📝 [vale] reported by reviewdog 🐶 |
||
|
|
||
| ## Tabs | ||
|
|
||
| To configure tabs: | ||
|
|
||
| - 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. | ||
|
|
||
| <CodeBlock> | ||
| {/* <!-- vale off --> */} | ||
|
|
||
| ```yaml title="docs.yml" | ||
| 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: # 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 # External link, so no layout | ||
| ``` | ||
| {/* <!-- vale on --> */} | ||
| </CodeBlock> | ||
|
|
||
| <Frame> | ||
| <img src="./images/tabs-sidebar.png" alt="Tabs displayed in the sidebar (default)" /> | ||
| </Frame> | ||
|
|
||
| <Note title="Tab icons"> | ||
| <Markdown src="/products/docs/snippets/icons.mdx" /> | ||
| </Note> | ||
|
|
||
| ### 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: | |
| </ParamField> | ||
|
|
||
| <ParamField path="variants" type="list" toc={true}> | ||
| List of [tab variants](#tab-variants). Use instead of `layout`. | ||
| </ParamField> | ||
|
|
||
| <ParamField path="href" type="string" toc={true}> | ||
|
|
@@ -180,27 +181,14 @@ navigation: | |
|
|
||
| ## Tab variants | ||
|
|
||
| To add variants to a tab: | ||
|
|
||
| - 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`. | ||
|
|
||
| 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=16 {22-34} | ||
| tabs: | ||
| api: | ||
| display-name: API Reference | ||
|
|
@@ -222,8 +210,8 @@ navigation: | |
| path: my-page.mdx | ||
| - api: API Reference | ||
| - tab: help | ||
| 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 | ||
| ``` | ||
|
|
||
| <Frame> | ||
| <video | ||
| autoPlay | ||
| muted | ||
| loop | ||
| > | ||
| <source src="assets/merge-tab-variants.mp4" type="video/mp4" /> | ||
| </video> | ||
| </Frame> | ||
|
|
||
| ### Variant properties | ||
|
|
||
| <ParamField path="title" type="string" required={true} toc={true}> | ||
|
|
||
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
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.
📝 [vale] reported by reviewdog 🐶
[Microsoft.OxfordComma] Use the Oxford comma in ', with search and tag filtering built in.'.