Add Fern docs platform: scaffolding, CI/CD, ecosystem diagram, and new pages

.github/workflows/ci.yaml

@@ -11,6 +11,13 @@ on:
       - '**.md'
       - '.github/triage/**'
       - '.github/workflows/triage-ci.yaml'
+      - 'docs/**'
+      - 'fern/**'
+      - 'package*.json'
+      - 'Makefile'
+      - '.npmrc'
+      - '.nvmrc'
+      - '.github/workflows/*fern*.yml'
   workflow_dispatch:
     inputs:
       PUBLISH:

.github/workflows/fern-docs-ci.yml

@@ -0,0 +1,30 @@
+# Validates Fern docs configuration and checks for broken internal links on PRs.
+# Runs without a FERN_TOKEN — suitable for untrusted forks.
+name: Fern Docs Validate
+
+on:
+  pull_request:
+    types: [synchronize]
+    paths:
+      - 'docs/**'
+      - 'fern/**'
+      - 'package.json'
+      - '.github/workflows/*fern*.yml'
+
+jobs:
+  validate:
+    name: Validate docs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-node@v6
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: fern check
+        run: npm run docs:check
+
+      - name: Check broken links
+        run: npx fern docs broken-links

.github/workflows/fern-docs-preview.yml

@@ -0,0 +1,86 @@
+# Generates a shareable Fern preview URL for every docs PR and posts it as a comment.
+# Requires the FERN_TOKEN repository secret.
+name: Fern Docs Preview
+
+on:
+  push:
+    branches:
+      - "pull-request/[0-9]+"
+
+env:
+  PREVIEW_PATHS: |
+      docs/**
+      fern/**
+      package.json
+      .github/workflows/*fern*.yml
+      .github/workflows/*fern*.yaml
+jobs:
+  preview:
+    name: Generate preview
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Check docs-related changes vs main
+        id: changes
+        shell: bash
+        run: |
+          git fetch origin main
+
+          mapfile -t paths <<< "$PREVIEW_PATHS"
+
+          pathspecs=()
+          for path in "${paths[@]}"; do
+            [[ -z "$path" ]] && continue
+            pathspecs+=(":(glob)$path")
+          done
+
+          if git diff --quiet origin/main...HEAD -- "${pathspecs[@]}"; then
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - uses: actions/setup-node@v6
+        if: steps.changes.outputs.changed == 'true'
+
+
+      - name: Install dependencies
+        if: steps.changes.outputs.changed == 'true'
+        run: npm install
+
+      - name: Generate preview
+        id: preview
+        if: steps.changes.outputs.changed == 'true'
+        run: |
+          output=$(npm run docs:preview 2>&1)
+          echo "$output"
+          url=$(printf '%s\n' "$output" \
+            | grep -oP 'https://[A-Za-z0-9./?&=_:%#~+-]*buildwithfern\.com[A-Za-z0-9./?&=_:%#~+-]*' \
+            | tail -n 1 \
+            | perl -CS -pe 's/\x{200B}//g; s/%E2%80%8B$//i')
+
+          echo "url=$url" >> "$GITHUB_OUTPUT"
+        env:
+          FERN_TOKEN: ${{ secrets.FERN_TOKEN }}
+
+      - name: Post preview URL
+        if: steps.changes.outputs.changed == 'true' && steps.preview.outputs.url != ''
+        uses: actions/github-script@v9
+        with:
+          script: |
+            const match = context.ref.match(/^refs\/heads\/pull-request\/([0-9]+)$/)
+
+            if (!match) {
+              core.setFailed(`Could not find PR number from ref: ${context.ref}`)
+              return
+            }
+
+            await github.rest.issues.createComment({
+              issue_number: Number(match[1]),
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: '📖 [**Docs preview**](${{ steps.preview.outputs.url }})'
+            })

.github/workflows/nsys-jax.yaml

@@ -11,12 +11,13 @@ on:
       - reopened
       - ready_for_review
       - synchronize
-    paths-ignore:
-      - '**.md'
-      - '.github/triage/**'
+    paths:
+      - '.github/container/nsys_jax/**'
   push:
     branches:
       - main
+    paths:
+      - '.github/container/nsys_jax/**'
 
 defaults:
   run:

.github/workflows/publish-fern-docs.yml

@@ -0,0 +1,30 @@
+# Publishes docs to production on every push to main that touches docs/fern,
+# and on manual dispatch. Requires the FERN_TOKEN repository secret.
+name: Publish Fern Docs
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+      - 'fern/**'
+      - 'package.json'
+  workflow_dispatch:
+
+jobs:
+  publish:
+    name: Publish docs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-node@v6
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Publish
+        run: npm run docs:publish
+        env:
+          FERN_TOKEN: ${{ secrets.FERN_TOKEN }}

.github/workflows/triage-ci.yaml

@@ -11,8 +11,8 @@ on:
       - reopened
       - ready_for_review
       - synchronize
-    paths-ignore:
-      - '**.md'
+    paths:
+      - '.github/triage/**'
   push:
     branches:
       - main

.npmrc

@@ -0,0 +1,2 @@
+# Pin exact versions when adding dependencies, for reproducible installs.
+save-exact=true

.nvmrc

@@ -0,0 +1 @@
+22

Makefile

@@ -0,0 +1,21 @@
+.PHONY: docs-dev docs-restart docs-wait docs-check docs-preview
+
+docs-dev:
+	npm run docs:dev
+
+docs-restart:
+	-pkill -f "fern docs dev" 2>/dev/null || true
+	sleep 1
+	npm run docs:dev
+
+# Poll until the dev server responds — run this after backgrounding docs-restart
+docs-wait:
+	@echo "Waiting for http://localhost:3000 ..."
+	@until curl -sf http://localhost:3000 >/dev/null 2>&1; do sleep 3; done
+	@echo "Server ready."
+
+docs-check:
+	npm run docs:check
+
+docs-preview:
+	npm run docs:preview