NVIDIA · miyoungc · Mar 13, 2026 · Mar 13, 2026 · Mar 13, 2026 · Mar 13, 2026
@@ -4,7 +4,7 @@ on:
     push:
         branches: [main]
         paths:
-            - "docs/**"
+            - "fern/**"
     workflow_dispatch:
 
 defaults:
@@ -19,7 +19,7 @@ concurrency:
     cancel-in-progress: true
 
 jobs:
-    build:
+    publish:
         runs-on: build-arm64
         container:
             image: ghcr.io/nvidia/openshell/ci:latest
@@ -33,102 +33,10 @@ jobs:
             - name: Install tools
               run: mise install
 
-            - name: Build documentation
-              run: mise run docs:build:strict
-
-            - name: Delete unnecessary files
-              run: |
-                  find _build -name .doctrees -prune -exec rm -rf {} \;
-                  find _build -name .buildinfo -exec rm {} \;
-
-            - name: Upload HTML
-              uses: actions/upload-artifact@v4
-              with:
-                  name: html-build-artifact
-                  path: _build/docs
-                  if-no-files-found: error
-                  retention-days: 1
+            - name: Install Fern CLI
+              run: npm install -g fern-api
 
-    publish:
-        if: false # disabled until GitHub Pages is configured
-        needs: [build]
-        runs-on: build-arm64
-        container:
-            image: ghcr.io/nvidia/openshell/ci:latest
-            credentials:
-                username: ${{ github.actor }}
-                password: ${{ secrets.GITHUB_TOKEN }}
-        steps:
-            - uses: actions/checkout@v4
-              with:
-                  ref: "gh-pages"
-
-            - name: Initialize Git configuration
-              run: |
-                  git config --global --add safe.directory "$GITHUB_WORKSPACE"
-                  git config --global user.name "github-actions[bot]"
-                  git config --global user.email "github-actions[bot]@users.noreply.github.com"
-
-            - name: Download artifacts
-              uses: actions/download-artifact@v4
-              with:
-                  name: html-build-artifact
-                  path: ${{ github.ref_name }}
-
-            - name: Copy HTML directories
-              run: |
-                  ls -asl
-                  for i in `ls -d *`
-                  do
-                    echo "Git adding ${i}"
-                    git add "${i}"
-                  done
-            - name: Check or create dot-no-jekyll file
-
-              run: |
-                  if [ -f ".nojekyll" ]; then
-                    echo "The dot-no-jekyll file already exists."
-                    exit 0
-                  fi
-                  touch .nojekyll
-                  git add .nojekyll
-
-            - name: Check or create redirect page
+            - name: Publish documentation
               env:
-                  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-              run: |
-                  resp=$(grep 'http-equiv="refresh"' index.html 2>/dev/null) || true
-                  if [ -n "${resp}" ]; then
-                    echo "The redirect file already exists."
-                    exit 0
-                  fi
-                  def_branch=$(gh api "repos/${GITHUB_REPOSITORY}" --jq ".default_branch")
-                  html_url=$(gh api "repos/${GITHUB_REPOSITORY}/pages" --jq ".html_url")
-                  echo '<!DOCTYPE html>'                                                                         > index.html
-                  echo '<html>'                                                                                 >> index.html
-                  echo '  <head>'                                                                               >> index.html
-                  echo '    <title>Redirect to documentation</title>'                                           >> index.html
-                  echo '    <meta charset="utf-8">'                                                             >> index.html
-                  echo '    <meta http-equiv="refresh" content="3; URL='${html_url}${def_branch}'/index.html">' >> index.html
-                  echo '    <link rel="canonical" href="'${html_url}${def_branch}'/index.html">'                >> index.html
-                  echo '    <script language="javascript">'                                                     >> index.html
-                  echo '      function redirect() {'                                                            >> index.html
-                  echo '        window.location.assign("'${html_url}${def_branch}'/index.html")'                >> index.html
-                  echo '      }'                                                                                >> index.html
-                  echo '    </script>'                                                                          >> index.html
-                  echo '  </head>'                                                                              >> index.html
-                  echo '  <body onload="redirect()">'                                                           >> index.html
-                  echo '    <p>Please follow the link to the <a href="'${html_url}${def_branch}'/index.html">'  >> index.html
-                  echo      ${def_branch}'</a> branch documentation.</p>'                                       >> index.html
-                  echo '  </body>'                                                                              >> index.html
-                  echo '</html>'                                                                                >> index.html
-                  git add index.html
-
-            - name: Commit changes to the GitHub Pages branch
-              run: |
-                  git status
-                  if git commit -m 'Pushing changes to GitHub Pages.'; then
-                    git push -f
-                  else
-                   echo "Nothing changed."
-                  fi
+                  FERN_TOKEN: ${{ secrets.FERN_TOKEN }}
+              run: fern generate --docs
@@ -3,16 +3,16 @@ name: docs-preview-pr
 on:
     pull_request:
         branches: [main]
-        types: [opened, reopened, synchronize, closed]
+        types: [opened, reopened, synchronize]
         paths:
-            - "docs/**"
+            - "fern/**"
 
 concurrency:
     group: preview-${{ github.ref }}
     cancel-in-progress: true
 
 permissions:
-    contents: write
+    contents: read
     pull-requests: write
     packages: read
 
@@ -38,20 +38,21 @@ jobs:
             - name: Install tools
               run: mise install
 
-            - name: Build documentation
-              if: github.event.action != 'closed'
-              run: mise run docs:build:strict
+            - name: Install Fern CLI
+              run: npm install -g fern-api
 
-            - name: Delete unnecessary files
-              if: github.event.action != 'closed'
+            - name: Generate preview URL
+              id: generate-docs
+              env:
+                  FERN_TOKEN: ${{ secrets.FERN_TOKEN }}
               run: |
-                  find _build -name .doctrees -prune -exec rm -rf {} \;
-                  find _build -name .buildinfo -exec rm {} \;
-
-            - name: Deploy preview
-              uses: rossjrw/pr-preview-action@v1
+                  OUTPUT=$(fern generate --docs --preview 2>&1) || true
+                  echo "$OUTPUT"
+                  URL=$(echo "$OUTPUT" | grep -oP 'Published docs to \K.*(?= \()')
+                  echo "Preview URL: $URL"
+                  echo "Preview your docs: $URL" > preview_url.txt
+
+            - name: Comment preview URL on PR
+              uses: thollander/actions-comment-pull-request@v2.4.3
               with:
-                  source-dir: ./_build/docs/
-                  preview-branch: gh-pages
-                  umbrella-dir: pr-preview
-                  action: auto
+                  filePath: preview_url.txt
@@ -0,0 +1,100 @@
+# NVIDIA OpenShell Fern Documentation
+
+This folder contains the Fern Docs configuration for NVIDIA OpenShell.
+
+## Installation
+
+```bash
+npm install -g fern-api
+# Or: npx fern-api --version
+```
+
+## Local Preview
+
+```bash
+cd fern/
+fern docs dev
+# Or from project root: fern docs dev --project ./fern
+```
+
+Docs available at `http://localhost:3000`.
+
+## Folder Structure
+
+```
+fern/
+├── docs.yml              # Global config (title, colors, versions)
+├── fern.config.json      # Fern CLI config
+├── versions/
+│   └── v0.0.1.yml       # Navigation for v0.0.1
+├── v0.0.1/
+│   └── pages/            # MDX content for v0.0.1
+├── scripts/              # Migration and conversion scripts
+├── components/           # Custom React components (footer)
+└── assets/               # Favicon, logos, images
+```
+
+## Migration Workflow
+
+To migrate or update docs from `docs/` to Fern:
+
+```bash
+# 1. Copy docs to fern (run from repo root)
+python3 fern/scripts/copy_docs_to_fern.py v0.0.1
+
+# 2. Expand {include} directives (index)
+python3 fern/scripts/expand_includes.py fern/v0.0.1/pages
+
+# 3. Convert OpenShell-specific syntax ({doc} roles, {ref} roles)
+python3 fern/scripts/convert_openshell_specific.py fern/v0.0.1/pages
+
+# 4. Convert MyST to Fern MDX
+python3 fern/scripts/convert_myst_to_fern.py fern/v0.0.1/pages
+
+# 5. Add frontmatter
+python3 fern/scripts/add_frontmatter.py fern/v0.0.1/pages
+
+# 6. Update internal links
+python3 fern/scripts/update_links.py fern/v0.0.1/pages
+
+# 7. Remove duplicate H1s (when title matches frontmatter)
+python3 fern/scripts/remove_duplicate_h1.py fern/v0.0.1/pages
+
+# 8. Fix MyST frontmatter for Fern compatibility
+python3 fern/scripts/fix_frontmatter.py fern/v0.0.1/pages
+
+# 9. Validate
+./fern/scripts/check_unconverted.sh fern/v0.0.1/pages
+```
+
+## MDX Components
+
+```mdx
+<Note>Informational note</Note>
+<Tip>Helpful tip</Tip>
+<Warning>Warning message</Warning>
+<Info>Info callout</Info>
+
+<Cards>
+  <Card title="Title" href="/path">Description</Card>
+</Cards>
+
+<Tabs>
+  <Tab title="Python">```python\ncode\n```</Tab>
+</Tabs>
+
+<Accordion title="Details">Collapsible content</Accordion>
+```
+
+## Deploying
+
+```bash
+fern generate --docs
+fern docs deploy
+```
+
+## Useful Links
+
+- [Fern Docs](https://buildwithfern.com/learn/docs)
+- [MDX Components](https://buildwithfern.com/learn/docs/components)
+- [Versioning Guide](https://buildwithfern.com/learn/docs/configuration/versions)