How to Build and Publish Dynamo Docs

This document describes the architecture, workflows, and maintenance procedures for the NVIDIA Dynamo documentation website powered by Fern.

Table of Contents

• Branch Architecture
• Directory Layout
• Configuration Files
• GitHub Workflows
  • Fern Docs Workflow
  • Docs Link Check Workflow
• Content Authoring
• Callout Conversion
• Running Locally
• Version Management
• How Publishing Works
• Common Tasks
• Claude Code Skills

Claude Code Skills

A single Claude Code skill automates common docs tasks. Invoke it as a slash command in Claude Code (e.g., /dynamo-docs) — the skill walks through the full workflow: creating, editing, or removing the markdown file, updating the navigation in docs/index.yml, and running fern check to validate.

Branch Architecture

The documentation system uses a dual-branch model:

Authors edit pages on main. A GitHub Actions workflow automatically syncs changes to the docs-website branch and publishes them to Fern. The docs-website branch is never edited by hand — it is entirely managed by CI.

Why two branches?

The docs-website branch accumulates versioned snapshots over time (e.g. pages-v0.8.0/, pages-v0.8.1/). Keeping these on a separate branch avoids bloating the main branch with frozen copies of old documentation.

Directory Layout

On main

fern/                             # Fern CLI configuration (fern/ is a Fern convention)
├── fern.config.json              # Fern org + CLI version pin
├── docs.yml                      # Site configuration (instances, branding, layout)
├── components/
│   └── CustomFooter.tsx          # React component for the site footer
├── main.css                      # Custom CSS (NVIDIA branding, dark mode, etc.)
├── convert_callouts.py           # GitHub → Fern admonition converter script
└── .gitignore                    # Fern-specific ignores
docs/                             # Documentation content
├── index.yml                     # Navigation tree for the dev version
├── getting-started/              # Markdown content (the actual docs)
├── kubernetes/
├── reference/
├── ...
├── assets/                       # Images, fonts, SVGs, logos
├── blogs/                        # Blog posts
└── diagrams/                     # D2 diagram source files

On docs-website

The docs-website branch has a different layout optimized for Fern’s directory conventions, plus versioned snapshots:

fern/
├── fern.config.json              # Fern org + CLI version pin
├── docs.yml                      # Includes the full versions array
├── versions/
│   ├── dev.yml                   # "Next" / dev navigation (synced from main)
│   ├── v0.8.1.yml                # Navigation for v0.8.1 snapshot
│   └── v0.8.0.yml                # Navigation for v0.8.0 snapshot
├── pages/                        # Current dev content (synced from main)
├── pages-v0.8.1/                 # Frozen snapshot of pages/ at v0.8.1
├── pages-v0.8.0/                 # Frozen snapshot of pages/ at v0.8.0
├── components/                   # React components
├── main.css                      # Custom CSS
├── convert_callouts.py           # Callout converter
├── blogs/                        # Blog posts (synced from main)
└── assets/                       # Images, fonts, SVGs

Each pages-vX.Y.Z/ directory is an immutable copy of pages/ taken at release time. The corresponding versions/vX.Y.Z.yml file is a copy of dev.yml with all ../pages/ paths rewritten to ../pages-vX.Y.Z/.

The sync workflow copies content from main’s docs/ into fern/pages/ and transforms navigation paths in index.yml → versions/dev.yml accordingly.

Configuration Files

fern/fern.config.json

1
{
2
  "organization": "nvidia",
3
  "version": "3.73.0"
4
}

• organization: The Fern organization that owns the docs site.
• version: Pins the Fern CLI version used for generation.

fern/docs.yml

This is the main Fern site configuration. Key sections:

Important: On main, docs.yml only lists the dev version. On docs-website, it contains the full versions array (dev + all releases). The sync workflow preserves the versions array from docs-website when copying docs.yml from main.

docs/index.yml

Defines the navigation tree — the sidebar structure of the docs site. Each entry maps a page title to a markdown file path:

1
navigation:
2
  - section: Getting Started
3
    contents:
4
      - page: Quickstart
5
        path: getting-started/quickstart.md
6
      - page: Support Matrix
7
        path: reference/support-matrix.md

Paths are relative to the docs/ directory. Sections can be nested. Pages can be marked as hidden: true to make them accessible by URL but invisible in the sidebar.

During sync to docs-website, the workflow copies index.yml to fern/versions/dev.yml and transforms paths (e.g., getting-started/X → ../pages/getting-started/X) to match the docs-website directory layout.

GitHub Workflows

Fern Docs Workflow (fern-docs.yml)

Location: .github/workflows/fern-docs.yml

This single consolidated workflow handles linting, syncing, versioning, and publishing. It runs three jobs depending on the trigger:

Job 1: Lint (PRs)

Triggers: Pull requests that modify docs/** files.

Steps:

1. fern check — validates Fern configuration syntax
2. fern docs broken-links — checks for broken internal links

Purpose: Catches broken docs before they merge.

Job 2: Sync dev (push to main)

Triggers: Push to main that modifies docs/** files, or manual workflow_dispatch (with no tag specified).

Steps:

1. Checks out both main and docs-website branches side-by-side
2. Copies content from main’s docs/ → docs-website’s fern/pages/
3. Copies docs/index.yml → fern/versions/dev.yml and transforms paths for the docs-website layout using yq
4. Syncs assets from docs/assets/ and blogs from docs/blogs/
5. Copies Fern config files from fern/ → docs-website’s fern/ (fern.config.json, components/, main.css, convert_callouts.py)
6. Runs convert_callouts.py to transform GitHub-style callouts to Fern format
7. Updates docs.yml from main while preserving the versions array from docs-website (uses yq to save/restore the versions list)
8. Commits and pushes to docs-website
9. Publishes to Fern via fern generate --docs

Job 3: Version Release (tags)

Triggers: New Git tags matching vX.Y.Z (e.g., v0.9.0, v1.0.0), or manual workflow_dispatch with a tag specified.

Steps:

1. Validates tag format (must be exactly vX.Y.Z, no suffixes like -rc1)
2. Checks that the version doesn’t already exist (no duplicate snapshots)
3. Creates fern/pages-vX.Y.Z/ by copying fern/pages/
4. Rewrites GitHub links in the snapshot:
   • github.com/ai-dynamo/dynamo/tree/v1.0.1 → tree/vX.Y.Z
   • github.com/ai-dynamo/dynamo/blob/v1.0.1 → blob/vX.Y.Z
5. Runs convert_callouts.py on the snapshot
6. Creates fern/versions/vX.Y.Z.yml from dev.yml with paths updated to ../pages-vX.Y.Z/
7. Updates fern/docs.yml:
   • Inserts new version right after the “dev” entry
   • Sets the product’s default path to the new version
   • Updates the “Latest” display-name to "Latest (vX.Y.Z)"
8. Commits and pushes to docs-website
9. Publishes to Fern via fern generate --docs

Anti-recursion note: Pushes made with GITHUB_TOKEN do not trigger other workflows (GitHub’s built-in guard). This is why the publish step is inline in each job rather than in a separate workflow.

Docs Link Check Workflow (docs-link-check.yml)

Location: .github/workflows/docs-link-check.yml

Triggers: Push to main and pull requests.

Runs two independent link-checking jobs:

Content Authoring

Writing docs on main

1. Edit or add markdown files in docs/.
2. If adding a new page, add an entry in docs/index.yml to make it appear in the sidebar navigation.
3. Use standard GitHub-flavored markdown. Callouts (admonitions) should use GitHub’s native syntax — they are automatically converted during sync:

   1
   <Note>This is a note that will become a Fern `<Note>` component.</Note>
   2
   3
   <Warning>This warning will become a Fern `<Warning>` component.</Warning>
4. Open a PR. The lint jobs (fern check, fern docs broken-links, lychee, broken-links-check) run automatically.
5. Once merged to main, the sync-dev workflow publishes changes within minutes.

Assets and images

Place images in docs/assets/ and reference them with relative paths from your markdown files:

1
![Architecture Diagram](../assets/img/dynamo-architecture.svg)

Custom components

React components in fern/components/ can be used in markdown via MDX. The CustomFooter.tsx renders the NVIDIA footer with legal links and branding.

Callout Conversion

The fern/convert_callouts.py script bridges the gap between GitHub-flavored markdown and Fern’s admonition format. This lets authors use GitHub’s native callout syntax on main while Fern gets its required component format.

Mapping

Usage

$
# Convert all files in a directory (recursive, in-place)
$
python fern/convert_callouts.py --dir docs/
$
$
# Convert a single file
$
python fern/convert_callouts.py input.md output.md
$
$
# Run built-in tests
$
python fern/convert_callouts.py --test

The conversion happens automatically during the sync-dev and release-version workflows. Authors never need to run it manually.

Running Locally

You can preview the documentation site on your machine using the Fern CLI. This is useful for verifying layout, navigation, and content before opening a PR.

Prerequisites

Install the Fern CLI globally via npm:

$
npm install -g fern-api

Validate configuration

Run fern check from the repo root to validate that fern/docs.yml, fern/fern.config.json, and the navigation files are syntactically correct:

$
fern check

Check for broken links

Use fern docs broken-links to scan all pages for internal links that don’t resolve:

$
fern docs broken-links

This is the same check that runs in CI on every pull request.

Start a local preview server

Run fern docs dev to build the site and serve it locally with hot-reload:

$
fern docs dev

The local server lets you see exactly how pages will look on the live site, including navigation, version dropdowns, and custom styling.

Version Management

How versions work

The Fern site supports a version dropdown in the UI. Each version is defined by:

1. A navigation file (fern/versions/vX.Y.Z.yml) — sidebar structure pointing to version-specific pages (on the docs-website branch).
2. A pages directory (fern/pages-vX.Y.Z/) — frozen snapshot of the markdown content at release time (on the docs-website branch).
3. An entry in fern/docs.yml — tells Fern about the version’s display name, slug, and config path.

Version types

URL structure

• Latest (default): docs.dynamo.nvidia.com/dynamo/
• Specific version: docs.dynamo.nvidia.com/dynamo/v0.8.1/
• Dev: docs.dynamo.nvidia.com/dynamo/dev/

Creating a new version

Simply push a semver tag:

$
git tag v0.9.0
$
git push origin v0.9.0

The release-version job in fern-docs.yml handles everything else automatically.

How Publishing Works

┌─────────────────────────────────────────────────────────────────────┐
│                        CONTINUOUS (dev)                             │
│                                                                     │
│  Developer pushes to main                                           │
│       │                                                             │
│       ▼                                                             │
│  docs/** changed? ── No ──▶ (nothing happens)                      │
│       │                                                             │
│      Yes                                                            │
│       │                                                             │
│       ▼                                                             │
│  sync-dev job:                                                      │
│    1. Copy docs/ content → fern/pages/ on docs-website branch │
│    2. Copy fern/ configs → fern/ on docs-website branch             │
│    3. Convert GitHub callouts → Fern admonitions                    │
│    4. Preserve version list from docs-website's docs.yml            │
│    5. Commit + push to docs-website                                 │
│    6. fern generate --docs (publishes to Fern)                      │
│       │                                                             │
│       ▼                                                             │
│  Live on docs.dynamo.nvidia.com/dynamo/dev/ within minutes          │
└─────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────┐
│                      VERSION RELEASE                                │
│                                                                     │
│  Maintainer pushes vX.Y.Z tag                                       │
│       │                                                             │
│       ▼                                                             │
│  release-version job:                                               │
│    1. Validate tag format (vX.Y.Z only)                             │
│    2. Check version doesn't already exist                           │
│    3. Snapshot fern/pages/ → fern/pages-vX.Y.Z/                     │
│    4. Rewrite GitHub links (tree/main → tree/vX.Y.Z)               │
│    5. Convert callouts in snapshot                                  │
│    6. Create fern/versions/vX.Y.Z.yml (paths → pages-vX.Y.Z/)     │
│    7. Update fern/docs.yml (insert version, set as default)         │
│    8. Commit + push to docs-website                                 │
│    9. fern generate --docs (publishes to Fern)                      │
│       │                                                             │
│       ▼                                                             │
│  New version visible in dropdown at docs.dynamo.nvidia.com/dynamo/  │
└─────────────────────────────────────────────────────────────────────┘

Secrets

Common Tasks

Update existing documentation

1. Edit files in docs/ on a feature branch.
2. If adding a new page, add its entry in docs/index.yml.
3. Open a PR — linting runs automatically.
4. Merge — sync + publish happens automatically.

Add a new top-level section

1. Create a directory under docs/ (e.g., docs/new-section/).
2. Add markdown files for each page.
3. Add a new - section: block in docs/index.yml with the desired hierarchy.

Release versioned documentation

$
git tag v1.0.0
$
git push origin v1.0.0

That’s it. The workflow snapshots the current dev docs, creates the version config, and publishes.

Manually trigger a sync or release

Go to Actions → Fern Docs → Run workflow:

• Leave tag empty to trigger a dev sync.
• Enter a tag (e.g., v0.9.0) to trigger a version release.

Debug a failed publish

1. Check the Actions tab for the failed Fern Docs workflow run.
2. Common issues:
   • Broken links: Fix the links flagged by fern docs broken-links.
   • Invalid YAML: Check fern/docs.yml or docs/index.yml syntax.
   • Expired FERN_TOKEN: Rotate the token in repo secrets.
   • Duplicate version: The tag was already released; check docs-website for existing fern/pages-vX.Y.Z/ directory.