diff --git a/fern/products/docs/docs.yml b/fern/products/docs/docs.yml index 4d4b75c31..32fd453d3 100644 --- a/fern/products/docs/docs.yml +++ b/fern/products/docs/docs.yml @@ -20,16 +20,22 @@ navigation: contents: - page: Overview path: ./pages/navigation/overview.mdx - - page: Site-level settings + - page: Site settings path: ./pages/navigation/site-level-settings.mdx slug: site-level-settings + - page: Page settings + path: ./pages/navigation/frontmatter.mdx + slug: page-level-settings - section: Navigation skip-slug: true contents: - - page: Sections, pages, and folder + - page: Overview + path: ./pages/navigation/navigation-overview.mdx + slug: navigation-overview + - page: Sections, pages, and folders path: ./pages/navigation/navigation.mdx slug: navigation - - page: Tabs and tab variants + - page: Tabs path: ./pages/navigation/tabs.mdx slug: tabs - page: Versions @@ -39,9 +45,6 @@ navigation: - page: Changelog pages path: ./pages/navigation/changelogs.mdx slug: changelogs - - page: Page-level settings - path: ./pages/navigation/frontmatter.mdx - slug: page-level-settings - section: Writing content contents: - page: Markdown basics diff --git a/fern/products/docs/pages/navigation/changelogs.mdx b/fern/products/docs/pages/navigation/changelogs.mdx index bc22b3bdb..20c36b1d3 100644 --- a/fern/products/docs/pages/navigation/changelogs.mdx +++ b/fern/products/docs/pages/navigation/changelogs.mdx @@ -1,10 +1,11 @@ --- title: Changelog pages subtitle: Keep a chronological record of project changes with tagging, search, and RSS +description: Configure changelog pages in Fern, including entry files, the timeline and classic layouts, tag filtering, and the RSS feed. --- -Keep a record of how your project has changed by writing changelog entries. The changelog renders as a scannable timeline of entry cards grouped by date, automatically populated from the files in your `changelog` folder. Search and tag filtering are built into the timeline, with no configuration required. You can also [switch to the classic layout](#customize-layout) of stacked full entries. +A changelog is a navigation entry that renders a dated timeline of entries. Point the `changelog` key at a folder and every Markdown file in it becomes an entry, grouped by date, with search and tag filtering built in. A changelog can go wherever a section can — as its own tab, or as an entry in your sidebar. + + The sidebar itself: grouped, nestable entries pointing at Markdown files + + + A top-level row that splits one product or version into parallel bodies of content + + + A dropdown for multiple releases of the same content, each with its own structure + + + A switcher for distinct offerings, each with its own navigation, tabs, and versions + + + +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). diff --git a/fern/products/docs/pages/navigation/navigation.mdx b/fern/products/docs/pages/navigation/navigation.mdx index 955e48060..561b95b80 100644 --- a/fern/products/docs/pages/navigation/navigation.mdx +++ b/fern/products/docs/pages/navigation/navigation.mdx @@ -6,22 +6,9 @@ max-toc-depth: 3 --- -The `navigation` key in `docs.yml` defines your sidebar structure. Build it by combining sections, pages, and folders. +A `page` points at a single Markdown file, a `section` groups entries and can nest more sections, and a `folder` pulls in every file in a directory. - -Use the special `api` key to create a [generated API Reference section](/learn/docs/api-references/overview). - -```yaml docs.yml -navigation: - - section: Introduction - contents: - - page: My page - path: ./pages/my-page.mdx - - api: API Reference -``` - - -### Add a section +## Add a section Sections organize your documentation in the left-side nav bar. Each section has a name and a list of `contents`, which can include pages, folders, or nested sections. @@ -76,7 +63,20 @@ navigation: Sections also support [`slug` and `skip-slug`](/learn/docs/seo/configuring-slugs) to customize URL paths. -### Add a page + +Use the special `api` key to create a [generated API Reference section](/learn/docs/api-references/overview). + +```yaml docs.yml +navigation: + - section: Introduction + contents: + - page: My page + path: ./pages/my-page.mdx + - api: API Reference +``` + + +## Add a page Create an `.md` or `.mdx` file, then add a `page` entry to a section's `contents` with the file path. @@ -90,7 +90,7 @@ navigation: path: ./pages/another-page.mdx ``` -### Add a folder +## Add a folder Add a `folder` entry pointing to a directory. Fern auto-discovers all `.md` and `.mdx` files and adds them to the navigation. diff --git a/fern/products/docs/pages/navigation/overview.mdx b/fern/products/docs/pages/navigation/overview.mdx index 8ca0f10ae..be920acb2 100644 --- a/fern/products/docs/pages/navigation/overview.mdx +++ b/fern/products/docs/pages/navigation/overview.mdx @@ -5,39 +5,18 @@ description: Understand how to configure your Fern documentation site at the sit --- -Fern documentation is configured at two levels: **site-level** settings in `docs.yml` that apply globally, and **page-level** settings in frontmatter that control individual pages. +Fern documentation is configured at two levels: **site-level** settings in `docs.yml` that apply globally, and **page-level** settings in frontmatter that control individual pages. Where both set the same property, such as a title, slug, or layout, the page's frontmatter wins. -## Site-level configuration +`docs.yml` covers two concerns. Site-level settings determine how the site looks and behaves — branding, layout, navbar links, and analytics. Navigation determines what the site contains: which files become pages, how they group into sections, and what URL each one gets. Navigation is where most structural decisions land, so it spans several pages of its own. -The `docs.yml` file controls your site's appearance, structure, and behavior. All of the settings below are configured in `docs.yml`. - - - + + Colors, typography, logo, layout, navbar links, and analytics - - Organize your sidebar with sections, pages, and folders - - - Group content into switchable tabs with optional variants - - - Add a dropdown version selector for multiple doc versions - - - Add a product switcher for multi-product sites + + Titles, descriptions, slugs, layout, availability badges, and more - - Chronological record of changes with search, tagging, and RSS + + Products, versions, tabs, sections, folders, and pages - -## Page-level configuration - -Use frontmatter in individual `.mdx` files to override site-level defaults for a specific page, such as titles, meta descriptions, slugs, layout, and visibility of page elements. - - - - Titles, descriptions, slugs, layout, availability badges, and more - - diff --git a/fern/products/docs/pages/navigation/products.mdx b/fern/products/docs/pages/navigation/products.mdx index 4f03c12a1..958795c3d 100644 --- a/fern/products/docs/pages/navigation/products.mdx +++ b/fern/products/docs/pages/navigation/products.mdx @@ -1,12 +1,13 @@ --- title: Products subtitle: Add a product switcher for multi-product documentation sites +description: Configure multi-product documentation in Fern, including the product switcher, per-product navigation, and internal and external products. --- -Add a product switcher for multi-product documentation sites. Each product can have its own navigation, tabs, versions, and API references, and products can share content. +Products add a switcher to your docs for documenting distinct offerings. Each product can contain its own navigation, tabs, versions, and API references, and products can share content. Products can be internal (hosted on your site) or external (linking to external URLs). diff --git a/fern/products/docs/pages/navigation/site-level-settings.mdx b/fern/products/docs/pages/navigation/site-level-settings.mdx index e96c7f19a..b740f3c7f 100644 --- a/fern/products/docs/pages/navigation/site-level-settings.mdx +++ b/fern/products/docs/pages/navigation/site-level-settings.mdx @@ -1,5 +1,5 @@ --- -title: Site-level settings +title: Site settings subtitle: Customize colors, typography, logo, layout, navbar links, and analytics in `docs.yml` description: "Learn how to configure your Fern documentation site with the docs.yml file. Customize colors, typography, layout, analytics and more." max-toc-depth: 2 diff --git a/fern/products/docs/pages/navigation/tabs.mdx b/fern/products/docs/pages/navigation/tabs.mdx index 723affa49..36c0c4f8c 100644 --- a/fern/products/docs/pages/navigation/tabs.mdx +++ b/fern/products/docs/pages/navigation/tabs.mdx @@ -1,24 +1,27 @@ --- -title: Tabs and tab variants +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 let you group sections of your documentation together, while tab variants allow you to display different content perspectives within a single tab. +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. + +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. ## 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 `display-name` and `icon`. +To configure tabs: -In the `navigation` section, each tab reference must include either a `layout` (for content) or `variants` (for [tab variants](#tab-variants)). Tabs with an `href` property are external links and must not include `layout` or `variants`. +- 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. {/* */} ```yaml title="docs.yml" -tabs: +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: +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 + - tab: github # External link, so no layout ``` {/* */} - - - - -Here's an example of how a tabs implementation renders: - Tabs displayed in the sidebar (default) + + + + ### 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: - List of [tab variants](#tab-variants) for displaying different content perspectives. Use instead of `layout`. + List of [tab variants](#tab-variants). Use instead of `layout`. @@ -180,27 +181,14 @@ navigation: ## Tab variants -Tab variants let you display different content variations within a single tab, and [support RBAC](/learn/docs/authentication/features/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). - +To add variants to a tab: -### Basic usage +- 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`. -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. +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=20 {22-34} +```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: - - title: For developers + 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 ``` + + + + ### Variant properties diff --git a/fern/products/docs/pages/navigation/versions.mdx b/fern/products/docs/pages/navigation/versions.mdx index f20560f00..1505319d5 100644 --- a/fern/products/docs/pages/navigation/versions.mdx +++ b/fern/products/docs/pages/navigation/versions.mdx @@ -1,12 +1,13 @@ --- title: Versions subtitle: Add a dropdown version selector for multiple doc versions +description: Configure versioned documentation in Fern, including the version dropdown, per-version navigation, and sharing content across versions. --- -Each version of your docs can contain its own distinct tabs, sections, pages, and API references. Versions can also share content. +Versions add a dropdown to your docs for multiple releases of the same content. Each version can contain its own tabs, sections, pages, and API references, and versions can share content. ![A dropdown of the available versions](assets/versions.png)