Migrate docs to Vocs v2 and Bun

.github/workflows/README.md

@@ -1,12 +1,18 @@
 # GitHub Actions workflows
 
-This directory contains the workflows used to lint, deploy, and keep release metadata up to date for the docs site.
+This directory contains the workflows used to lint, deploy, preview, and keep release metadata up to date for the docs site.
 
-## `deploy.yml` — Deploy Docs (Nextra) to GitHub Pages
+## `deploy.yml` — Deploy Docs (Vocs) to GitHub Pages
 
 - **Triggers:** `push` to `main`, or manual `workflow_dispatch`.
-- **What it does:** installs deps (Node 20 + Yarn), runs `yarn generate:llms`, builds the static site (`yarn build`), then publishes `out/` to the `gh-pages` branch via `peaceiris/actions-gh-pages`.
-- **Notes:** writes `out/.nojekyll` and sets `cname: docs.celestia.org`.
+- **What it does:** installs deps with Bun, builds the static site (`bun run build`), then publishes `out/public/` to the `gh-pages` branch via `peaceiris/actions-gh-pages`.
+- **Notes:** writes `out/public/.nojekyll` and sets `cname: docs.celestia.org`.
+
+## `deploy-cloudflare.yml` — Deploy to Cloudflare Pages
+
+- **Triggers:** manual `workflow_dispatch`, plus same-repo pull requests.
+- **What it does:** builds the full-static Vocs site, copies `worker/index.js` into `out/public/_worker.js` for the Pages MCP endpoint, ensures the test Pages project exists, then deploys `out/public/` to Cloudflare Pages.
+- **Required secrets:** `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID`.
 
 ## `preview.yaml` — Deploy PR Preview
 
@@ -18,7 +24,7 @@ This directory contains the workflows used to lint, deploy, and keep release met
 ## `lint.yaml` — Lint & Link Check
 
 - **Triggers:** `push`/`pull_request` on `main`, plus a weekly schedule (`0 9 * * 1`).
-- **What it does:** runs `npm run lint` and `npm run check-links` (Node 20).
+- **What it does:** runs `bun run lint` and `bun run check-links`.
 
 ## `latest-tags.yaml` — Latest Tags
 

.github/workflows/deploy-cloudflare.yml

@@ -0,0 +1,88 @@
+# Optional Cloudflare Pages deploy for the Vocs migration branch.
+#
+# Mirrors the Eden docs pattern: build a full-static Vocs site, copy a Pages
+# advanced-mode Worker into the output as _worker.js for /mcp and /api/mcp,
+# then deploy the output directory to Cloudflare Pages.
+#
+# Requires CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID repo secrets.
+name: Deploy to Cloudflare Pages
+
+on:
+  workflow_dispatch:
+  # Temporary branch trigger for testing the Vocs migration before this
+  # workflow exists on the default branch.
+  push:
+    branches:
+      - codex/jcs/migrate-vocs-v2-bun
+  pull_request:
+    types:
+      - opened
+      - reopened
+      - synchronize
+
+permissions:
+  contents: read
+
+concurrency:
+  group: deploy-cloudflare-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  CLOUDFLARE_PAGES_PROJECT: ${{ vars.CLOUDFLARE_PAGES_PROJECT || 'celestia-docs-vocs-test' }}
+
+jobs:
+  deploy:
+    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup Bun
+        # oven-sh/setup-bun v2
+        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Build site and add MCP worker
+        run: bun run prepare:cloudflare
+
+      - name: Check Cloudflare secrets
+        id: cloudflare
+        env:
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+        run: |
+          if [[ -z "$CLOUDFLARE_API_TOKEN" || -z "$CLOUDFLARE_ACCOUNT_ID" ]]; then
+            echo "::notice::Cloudflare secrets are not set; skipping deploy."
+            echo "skip=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "skip=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Ensure Cloudflare Pages project exists
+        if: steps.cloudflare.outputs.skip != 'true'
+        env:
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+        run: |
+          set +e
+          output="$(bunx wrangler pages project create "$CLOUDFLARE_PAGES_PROJECT" --production-branch main 2>&1)"
+          status=$?
+          set -e
+          echo "$output"
+          if [[ "$status" -ne 0 && "$output" != *"already exists"* ]]; then
+            exit "$status"
+          fi
+
+      - name: Deploy
+        if: steps.cloudflare.outputs.skip != 'true'
+        # cloudflare/wrangler-action v3
+        uses: cloudflare/wrangler-action@9acf94ace14e7dc412b076f2c5c20b8ce93c79cd
+        with:
+          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          command: pages deploy out/public --project-name ${{ env.CLOUDFLARE_PAGES_PROJECT }} --branch ${{ github.head_ref || github.ref_name }}

.github/workflows/deploy.yml

@@ -1,4 +1,4 @@
-name: Deploy Docs (Nextra) to GitHub Pages
+name: Deploy Docs (Vocs) to GitHub Pages
 
 on:
   push:
@@ -23,31 +23,28 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v6
 
-      - name: Setup Node
-        uses: actions/setup-node@v6
+      - name: Setup Bun
+        # oven-sh/setup-bun v2
+        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6
         with:
-          node-version: 20
-          cache: yarn
+          bun-version: latest
 
       - name: Install dependencies
-        run: yarn install --frozen-lockfile
-
-      - name: Generate llms.txt
-        run: yarn generate:llms
+        run: bun install --frozen-lockfile
 
       - name: Build static site
         # Note: production deploy uses the root base path (custom domain).
-        # Preview deploys may override BASE / NEXT_PUBLIC_BASE_PATH.
-        run: yarn build
+        # Preview deploys may override BASE.
+        run: bun run build
 
       - name: Disable Jekyll
-        run: touch out/.nojekyll
+        run: touch out/public/.nojekyll
 
       - name: Deploy to GitHub Pages
         uses: peaceiris/actions-gh-pages@v3
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./out
+          publish_dir: ./out/public
           force_orphan: true
           # The following lines assign commit authorship to the official
           # GH-Actions bot for deploys to `gh-pages` branch:

.github/workflows/lint.yaml

@@ -21,32 +21,32 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v6
 
-      - name: Setup Node
-        uses: actions/setup-node@v6
+      - name: Setup Bun
+        # oven-sh/setup-bun v2
+        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6
         with:
-          node-version: 20
-          cache: npm
+          bun-version: latest
 
       - name: Install dependencies
-        run: npm install --no-package-lock --legacy-peer-deps
+        run: bun install --frozen-lockfile
 
       - name: Run lint
-        run: npm run lint
+        run: bun run lint
 
   link-check:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
         uses: actions/checkout@v6
 
-      - name: Setup Node
-        uses: actions/setup-node@v6
+      - name: Setup Bun
+        # oven-sh/setup-bun v2
+        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6
         with:
-          node-version: 20
-          cache: npm
+          bun-version: latest
 
       - name: Install dependencies
-        run: npm install --no-package-lock --legacy-peer-deps
+        run: bun install --frozen-lockfile
 
       - name: Run Link Checker
-        run: npm run check-links -- --all --concurrency=2 --skip="celestia.org,nexus.hyperlane.xyz"
+        run: bun run check-links -- --all --concurrency=2 --skip="celestia.org,nexus.hyperlane.xyz"

.github/workflows/preview.yaml

@@ -23,23 +23,19 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v6
 
-      - name: Setup Node
-        uses: actions/setup-node@v6
+      - name: Setup Bun
+        # oven-sh/setup-bun v2
+        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6
         with:
-          node-version: 20
-          cache: yarn
+          bun-version: latest
 
       - name: Install dependencies
-        run: yarn install --frozen-lockfile
-
-      - name: Generate llms.txt
-        run: yarn generate:llms
+        run: bun install --frozen-lockfile
 
       - name: Build static site
         env:
           BASE: /docs-preview/pr-${{ github.event.number }}/
-          NEXT_PUBLIC_BASE_PATH: /docs-preview/pr-${{ github.event.number }}
-        run: yarn build
+        run: bun run build
 
       - name: Checkout docs-preview repository
         uses: actions/checkout@v6
@@ -58,7 +54,7 @@ jobs:
           rm -rrf "$TARGET_DIR"/*
 
           # Copy built files
-          cp -r out/* "$TARGET_DIR"/
+          cp -r out/public/* "$TARGET_DIR"/
 
           # Ensure .nojekyll exists in root
           touch docs-preview/.nojekyll

.gitignore

@@ -5,16 +5,14 @@
 /.pnp
 .pnp.*
 .yarn/*
-!.yarn/patches
-!.yarn/plugins
-!.yarn/releases
-!.yarn/versions
 
 # testing
 /coverage
 
-# next.js
-/.next/
+# vocs
+/.vocs/
+/dist/
+/src/pages/
 /out/
 
 # production
@@ -29,18 +27,21 @@ npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
 .pnpm-debug.log*
+bun-debug.log*
 
 # env files (can opt-in for committing if needed)
 .env*
 
 # vercel
 .vercel
 
+# cloudflare
+.wrangler
+
 # typescript
 *.tsbuildinfo
-next-env.d.ts
 
-# nextra
+# generated search
 _pagefind/
 
 # agents llms

README.md

@@ -29,7 +29,7 @@ Celestia Documentation Access:
 - LLMs.txt: https://docs.celestia.org/llms.txt
 - Skill file: https://docs.celestia.org/SKILL.md (served from `public/SKILL.md`)
 - CIPs (Celestia Improvement Proposals): https://cips.celestia.org
-- Built with: Next.js + Nextra (MDX), exported as a static site.
+- Built with: Vocs v2 (MDX), Vite, and Bun, exported as a static site.
 - **LLM-ready**: Add `.md` to any URL to get clean markdown (e.g., `https://docs.celestia.org/learn/TIA/overview` → `https://docs.celestia.org/learn/TIA/overview.md`)
 - DeepWikis for @celestiaorg:
     - https://deepwiki.com/celestiaorg/docs
@@ -39,50 +39,63 @@ Celestia Documentation Access:
 
 ## Local development
 
-Prereqs: Node.js 20+ and Yarn.
+Prereqs: Bun 1.3+.
 
 ```bash
-yarn install
-yarn dev
+bun install
+bun run dev
 ```
 
-Open http://localhost:3000
+Open http://localhost:5173
 
 ## Build & preview the static export
 
-`next.config.mjs` is configured for static export (`output: 'export'`). Builds write to `out/` and generate a Pagefind search index in `out/_pagefind/`.
+Vocs is configured for full static rendering. Builds write the browser-ready site to `out/public/`.
 
 ```bash
-yarn build
-yarn start
+bun run build
+bun run preview
+```
+
+## Cloudflare Pages preview
+
+The Cloudflare Pages setup mirrors Eden docs: the Vocs site stays fully static,
+and `worker/index.js` is copied into the output as `_worker.js` to serve `/mcp`
+and `/api/mcp` from the same origin.
+
+```bash
+bun run prepare:cloudflare
+bun run deploy:cloudflare -- --project-name celestia-docs-vocs-test --branch <branch_name>
 ```
 
 ## Base paths (deploying under a subpath)
 
 For deployments that live under a subdirectory (e.g. GitHub Pages previews), set:
 
-- `BASE` with a trailing slash (used for `assetPrefix`)
-- `NEXT_PUBLIC_BASE_PATH` without a trailing slash (used by client-side components for asset URLs)
+- `BASE` with a trailing slash (used by Vocs as the base path)
 
 ```bash
-BASE=/docs-preview/new_docs/ NEXT_PUBLIC_BASE_PATH=/docs-preview/new_docs yarn build
+BASE=/docs-preview/new_docs/ bun run build
 ```
 
 ## Content & structure
 
 - `app/**/page.mdx`: documentation pages
 - `app/**/_meta.js`: sidebar order/titles
+- `src/vocs/`: Vocs runtime glue, compatibility components, and generated-page templates
+- `src/pages/`: generated Vocs page tree, created by `bun run prepare:vocs` and ignored by git
 - `public/`: static assets, including the published agent skill at `public/SKILL.md`
 - `constants/*.json`: shared values referenced in MDX (e.g. `{{mainnetVersions['app-latest-tag']}}`), replaced by `plugins/remark-replace-variables.mjs`
 
 ## Useful scripts
 
-- `yarn lint`: lint the codebase (also runs on `git push` via hook)
-- `yarn check-links -- --all`: validate internal + external links (see `scripts/check-links.mjs --help`)
-- `yarn generate:llms`: generate LLM-ready markdown files from MDX sources
+- `bun run prepare:vocs`: generate the Vocs `src/pages` tree from `app`
+- `bun run lint`: lint the codebase (also runs on `git push` via hook)
+- `bun run check-links -- --all`: validate internal + external links (see `scripts/check-links.mjs --help`)
+- `bun run generate:llms`: generate LLM-ready markdown files from MDX sources
   - Creates clean `.md` versions of all documentation pages
   - Removes JSX components, imports, and MDX-specific syntax
-  - Automatically runs during build process (`yarn build`)
+  - Automatically runs during build process (`bun run build`)
   - Access any doc page as markdown by adding `.md` to the URL
 
 ## Contribution guidelines

app/build/rpc/components/CopyIcon.tsx

@@ -8,7 +8,8 @@ export default function CopyIcon() {
       viewBox='0 0 24 24'
       strokeWidth={1.5}
       stroke='currentColor'
-      className='nx-h-6 w-6 text-gray-500 hover:text-blue-500'
+      width={22}
+      height={22}
     >
       <path
         strokeLinecap='round'
@@ -18,4 +19,3 @@ export default function CopyIcon() {
     </svg>
   );
 }
-