Migrate docs from Nextra to Vocs 2

[jcstein]

Summary

Migrates the docs site from Nextra (Next.js) to Vocs 2 and consolidates deployment onto Cloudflare Pages (site + MCP endpoint on one origin).

Changes

• Framework: Nextra → Vocs 2.0.11 (vite 8 + waku, managed with pnpm)
• Content: pages moved to docs/pages/, static assets to public/ at the repo root (vite convention)
• MDX: Nextra <Callout> → vocs :::info/:::warning directives, <Steps> → ::::steps, FAQ <details> → :::details directives
• Features gained: system dark-mode toggle, built-in search, MCP/AI integration, clean .md URLs for every page ("View as Markdown" / AI agents), llms.txt + llms-full.txt
• Cleanup: removed Nextra app/, components/, next.config.mjs, postcss.config.mjs, bun.lock; CI standardized on pnpm

Deployment (Cloudflare Pages only)

• The vocs build is fully prerendered (renderStrategy: 'full-static'); worker/index.js is deployed as the Pages _worker.js to serve a stateless MCP server (Streamable HTTP) at /mcp, passing everything else through to the static assets
• deploy-cloudflare.yml: push to main → production; pull requests → preview at <branch>.eden-docs.pages.dev (same-repo branches only)
• The previous GitHub Pages deploy is removed — it duplicated the site at a second origin and needed a BASE_PATH subpath build. After merge, disable GitHub Pages in repo settings.
• Repo secrets in place: CLOUDFLARE_API_TOKEN (account-owned, Pages:Edit only), CLOUDFLARE_ACCOUNT_ID
• patches/vocs@2.0.11.patch: mdRouter hardening + "Copy MCP URL" honors mcp.url from config

Testing

pnpm install
pnpm dev   # http://localhost:5173
pnpm build

Demo

Preview deployed from this branch by the PR workflow:

• Site: https://migrate-to-vocs.eden-docs.pages.dev/
• MCP endpoint: https://migrate-to-vocs.eden-docs.pages.dev/mcp (Streamable HTTP)

Production after merge: https://eden-docs.pages.dev/ (MCP at /mcp)

Known follow-ups (non-blocking)

• public/robots.txt still has Disallow: / — flip when the site should be indexed
• Bump GitHub Actions to Node 24-compatible versions before June 16

🤖 Generated with Claude Code

[jcstein]

🚀 Live demo deployment

The Vocs 2 site from this branch is deployed on Cloudflare Pages:

Site: https://eden-docs.pages.dev
MCP endpoint: https://eden-docs.pages.dev/mcp (Streamable HTTP)

Everything is verified working:

• ✅ Full-static site (every page prerendered, client-side nav, pagefind search)
• ✅ Logo / favicons / images
• ✅ llms.txt + llms-full.txt, and clean markdown URLs (e.g. /why-eden.md) for AI agents and the "View as Markdown" button
• ✅ MCP server with list_pages, read_page, and search_docs tools, served same-origin by a small Pages _worker.js that reads the static markdown the build emits

Try it:

# add to Claude Code
claude mcp add --transport http eden-docs https://eden-docs.pages.dev/mcp

# or poke it directly
curl -s -X POST https://eden-docs.pages.dev/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_docs","arguments":{"query":"bridge"}}}'

🤖 Generated with Claude Code

[jcstein]

📦 How deployment works after merge

Two workflows fire on every push to main, building the same commit:

Target	Workflow	Serves
GitHub Pages — celestiaorg.github.io/eden-docs	deploy.yml	Canonical docs site (full-static)
Cloudflare Pages — eden-docs.pages.dev	deploy-cloudflare.yml	MCP endpoint at /mcp + a self-contained mirror of the site it reads from

GitHub Pages needs no new setup (same Pages-via-Actions flow as before). The Cloudflare workflow needs two repo secrets (Settings → Secrets and variables → Actions):

1. CLOUDFLARE_ACCOUNT_ID — 8b18f1d078bd5e9866dd15df721c3b10 (the "Figo Company" account, where the eden-docs Pages project currently lives; visible in the Cloudflare dashboard sidebar or any dashboard URL).
2. CLOUDFLARE_API_TOKEN — create at dash.cloudflare.com → My Profile → API Tokens → Create Token → Create Custom Token with a single permission: Account → Cloudflare Pages → Edit, scoped to the Figo Company account.

Until the secrets are set, manual deploys work from a checkout: wrangler login once, then pnpm deploy (builds, adds the markdown mirror + _worker.js, and runs wrangler pages deploy --branch main).

Moving to a different Cloudflare account later (e.g. a Celestia-owned one): wrangler pages project create eden-docs --production-branch main on the new account, swap the two secrets, update mcp.url in vocs.config.ts if the *.pages.dev URL changes, and redeploy. A custom domain can be attached to the Pages project at any point — only BASE_URL/mcp.url values need updating.

🤖 Generated with Claude Code

[jcstein]

Deploy consolidation: Cloudflare Pages only (3031f15)

What changed

• Removed the GitHub Pages deploy (deploy.yml). It duplicated the full site at a second origin, required the BASE_PATH=/eden-docs subpath build, and its "Copy MCP URL" button pointed cross-origin at the Cloudflare deployment.
• deploy-cloudflare.yml is now the only deploy: the full-static vocs build plus the MCP endpoint (worker/index.js deployed as the Pages _worker.js) are served from one origin, eden-docs.pages.dev.
  • Push to main → production deploy
  • Pull requests → Cloudflare Pages preview at <branch>.eden-docs.pages.dev (same-repo branches only; fork PRs don't get secrets)
• Simplified vocs.config.ts: dropped the BASE_PATH/BASE_URL env plumbing — baseUrl is now hardcoded to https://eden-docs.pages.dev.
• Repo secrets CLOUDFLARE_API_TOKEN (account-owned token, Pages:Edit only) and CLOUDFLARE_ACCOUNT_ID are in place.

Verified on this PR's preview

The pull_request trigger deployed https://migrate-to-vocs.eden-docs.pages.dev (green in 43s), checked end to end:

• ✅ Site responds 200
• ✅ Clean markdown URLs (/why-eden.md serves raw markdown)
• ✅ MCP endpoint: tools/list returns list_pages/read_page/search_docs; read_page for /why-eden returns page content

Merging to main runs this same workflow with --branch main, promoting to production.

Known follow-ups (non-blocking)

• public/robots.txt still has Disallow: / — flip when the site should be indexed
• Bump actions to Node 24-compatible versions before June 16 (runner deprecation warning)
• Disable GitHub Pages in repo settings after merge so the old celestiaorg.github.io/eden-docs URL stops serving stale content

🤖 Generated with Claude Code