Fern Navigation

Fern Navigation & Site Structure

Fern documentation is configured at two levels: site-level in docs.yml (and, for multi-product or multi-version sites, in per-product / per-version .yml files), and page-level in each .md / .mdx file's frontmatter. This skill catalogs the whole site-structure surface — what each building block does, when to reach for it, and the exact YAML — and points to references/navigation-reference.md for every field, default, and copy-paste example.

This skill is structure & configuration knowledge. In-page MDX components (<Card>, <Steps>, <Tabs> content tabs, <Accordion>, callouts…) belong to the fern-components skill. Page placement conventions, the style guide, SPDX headers, terminology, and this repo's .md-vs-.mdx rule belong to the dynamo-docs skill. Use all three together when authoring.

"tabs" and "tabs" are two different things (read this first)

Fern overloads several words. Keep the layers straight before touching config:

The mental model: how a URL is built

Fern composes each page's URL by concatenating a slug from every level of the hierarchy it passes through, outermost first:

/<product>/<version>/<tab>/<section>/<folder>/<page>

Each level auto-generates a slug from its display name (or filename, for folders). Any level can slug: rename itself, skip-slug: true drop itself from the path, or a page's frontmatter slug: override the whole section/folder portion (product/version prefix is preserved). Understanding this composition is the key to predicting and controlling URLs — see the reference's Slugs section.

Choosing the right structural tool

Decide by how different two bodies of content are, from lightest to heaviest:

Rules of thumb:

• Don't reach for products when a tab will do. Products are a heavyweight, Team/Enterprise feature that removes top-level navigation/tabs and splits config into files. Use them only for genuinely separate products, not for two sections of one product.
• Variants vs tabs: variants = different lenses on the same area; tabs = different areas.
• Versions and products compose — a product can be versioned, and versioned/unversioned products coexist. Standalone versioning (no products) is simpler; prefer it if you have one product.

Hard constraints that bite (verify against these)

• Products/versions eject top-level nav. When you add products: (or versions:), you MUST remove the top-level navigation: and tabs: from docs.yml — they move into the per-product / per-version files. fern check rejects a navigation block coexisting with products: and would otherwise render an empty site.
• External products / href tabs cannot have navigation, tabs, layout, or variants.
• A tab needs exactly one of layout, variants, or href — never href + content.
• The default version (first in the list) can't be hidden.
• changelog/ must be named exactly that, files live flat in its root (no subdirs), and file names must be dated (YYYY-MM-DD, MM-DD-YYYY, or MM-DD-YY). Section-level changelogs can't nest under an api entry.
• Team plan gate: versions and products are Team/Enterprise features.

The eight source pages (what's in the reference)

references/navigation-reference.md mirrors the eight pages of Fern's navigation/ docs section, with full YAML and every field:

1. Overview — the two config levels; index of the structural cards.
2. Sections, pages, folders — the navigation: tree, nesting, folder auto-discovery, slugs, hiding, availability badges, collapsed state, sidebar icons, external links.
3. Tabs & tab variants — tabs: + navigation:, all tab props, variants, placement/style.
4. Versions — versions/*.yml, the switcher, availability, slugs, audiences, hiding, styling.
5. Products — products/*.yml, internal vs external, the switcher, versioned products, landing page, audiences, conditional content, search scoping, selector CSS.
6. Changelogs — changelog/ folder, tab vs section placement, entry files, tags, layouts, RSS.
7. Frontmatter (page-level settings) — every per-page field: titles, slug, description, layout, TOC/nav/feedback toggles, availability, SEO/OpenGraph, changelog tags.
8. Site-level settings — the full docs.yml surface: colors, logo, typography, layout, theme, navbar/footer links, instances, settings (search etc.), page actions, redirects, metadata, analytics, edit-this-page, Ask Fern, agents/llms.txt, check rules.

Workflow for a structure change in this repo

1. Locate the config. Find this repo's docs.yml (and any products/ or versions/ files) — dynamo-docs owns where pages live; this skill owns their arrangement.
2. Pick the lightest tool from the table above that expresses the change.
3. Write the YAML from the reference, honoring the hard constraints.
4. Mind the URL impact. Any slug/section/tab/version/product change alters URLs — add redirects: for moved pages, and remember check.rules.missing-redirects.
5. Validate: run fern check (broken links, missing redirects, config coherence) before publish.

Keeping this skill current

Fern's config schema drifts. The source of truth is fern-api/docs (branch main), fern/products/docs/pages/navigation/*.mdx. manifest.json records each tracked page's git blob SHA as of the last sync. To check for drift and refresh:

python3 scripts/refresh_navigation.py --check                 # what changed upstream?
python3 scripts/refresh_navigation.py --fetch --out /tmp/fern # download changed pages
# ...update references/navigation-reference.md + this SKILL.md from those...
python3 scripts/refresh_navigation.py --sync                  # record new SHAs as current

For anything load-bearing, verify field names against the live docs-yml schema or the current docs rather than trusting a summary — this surface changes.