Documentation site: migrate from VitePress to Fumadocs

[scottmessinger]

What & why

Replaces the hand-rolled VitePress docs with a maintained Fumadocs site (React Router 8 + Vite 8 + MDX), deployed to GitHub Pages under /supergrain/. After comparing VitePress, Starlight, Docusaurus, and Vocs, Fumadocs won on Vite + native React + MDX with first-class twoslash/type-table tooling.

What's in this PR

Docs site (packages/docs)

• Fumadocs site branded as Supergrain (landing page, nav, footer), with real content ported from the package READMEs + the comparison guide, plus an Introduction page.
• GitHub Pages ready: base/basename configured for /supergrain/, and build:pages flattens the prerendered output into a single deployable artifact.

Twoslash ✅ — type-on-hover code blocks (ts twoslash), compiled against the real @supergrain/kernel types, demonstrated on the intro page. A great fit for a type-inference-focused library.

Static search ✅ — the example shipped server-route search, which can't work on static GitHub Pages (no server). Swapped for Fumadocs' build-time static index: the Orama index is prerendered to a static file (/api/search, ~1 MB) and searched client-side in the browser.

VitePress fully retired ✅ — deleted the old docs/ site, root scripts, .gitignore entries, and (after merging main's js-krauset fix unblocked the lockfile) the vitepress devDependency itself.

Review fixes (Copilot) — under the /supergrain/ subpath, the OG-image meta, per-page markdown URLs, and the static search index URL are now base-prefixed (they were domain-root absolute → 404); the per-page content.md endpoints are prerendered; the "view source" link points at packages/docs/content/docs/....

Architecture: isolated sub-project

packages/docs is excluded from the pnpm workspace (!packages/docs) with its own lockfile (pnpm install --ignore-workspace), so its bleeding-edge toolchain (Vite 8 / RR 8 / TS 6) never perturbs the core library's resolution. CI builds it via a dedicated docs-ci.yml; the Pages deploy (docs.yml) builds and uploads it.

Verification

• Docs: typecheck + production build + static prerender of all pages pass. Build output confirms: twoslash hover markup present, the static search index + all content.md/OG files emitted, and docs HTML references base-prefixed /supergrain/... URLs.
• Repo-wide (now runnable locally after merging main's landmine fix): test (784 passed), test:validate (5), typecheck, lint, format:check — all green.

Follow-up

• Live interactive demos — embed running @supergrain/kernel components in .mdx to show fine-grained re-rendering (tracked in packages/docs/README.md).

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (8b37557) to head (67f466b).

Additional details and impacted files

@@            Coverage Diff            @@
##              main      #116   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           41        41           
  Lines         1735      1735           
  Branches       391       391           
=========================================
  Hits          1735      1735           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[Copilot]

Pull request overview

This PR replaces the previous VitePress docs setup with a new Fumadocs-based documentation site (React Router + Vite + MDX), intended for GitHub Pages deployment under /supergrain/, and updates CI/workspace config to treat docs as an isolated sub-project.

Changes:

• Add a new isolated docs site at packages/docs (Fumadocs + React Router + Vite) with ported content pages.
• Update GitHub Pages workflow and add a Docs CI workflow to build/typecheck the isolated docs package.
• Remove the old VitePress-based docs/ site and update links + doc-test validation inputs.

Reviewed changes

Copilot reviewed 50 out of 58 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
README.md	Updates the comparison link to point at the new published docs route.
pnpm-workspace.yaml	Excludes packages/docs from the workspace to keep its toolchain isolated.
packages/kernel/README.md	Updates comparison guide links to the new docs site URL.
packages/docs/vite.config.ts	Configures Vite base path + plugins for the Fumadocs site.
packages/docs/tsconfig.json	Adds a TypeScript config for the isolated docs project.
packages/docs/source.config.ts	Configures fumadocs-mdx source processing.
packages/docs/scripts/prepare-pages.mjs	Flattens build output for GitHub Pages artifact layout.
packages/docs/README.md	Documents docs-site workflow, commands, and deployment assumptions.
packages/docs/react-router.config.ts	Sets basename + prerender list for the docs site.
packages/docs/package.json	Adds isolated docs dependencies/scripts (React Router build/dev/typecheck).
packages/docs/content/docs/silo.md	Adds the Silo docs page content.
packages/docs/content/docs/queries.md	Adds the Queries docs page content.
packages/docs/content/docs/mill.md	Adds the Mill docs page content.
packages/docs/content/docs/meta.json	Defines docs sidebar/page ordering.
packages/docs/content/docs/kernel.md	Adds the Kernel docs page content.
packages/docs/content/docs/index.mdx	Adds the new Introduction page content.
packages/docs/content/docs/husk.md	Adds the Husk docs page content.
packages/docs/content/docs/comparison.md	Ports the comparison guide into the new docs content tree.
packages/docs/app/routes/search.ts	Adds the server search route implementation.
packages/docs/app/routes/og.docs.tsx	Adds OG image generation route for docs pages.
packages/docs/app/routes/not-found.tsx	Adds a Not Found route/layout for the docs site.
packages/docs/app/routes/home.tsx	Adds a branded landing page route.
packages/docs/app/routes/docs.tsx	Adds the main docs route wiring + layout integration.
packages/docs/app/routes.ts	Registers app routes (home/docs/search/og/llms/fallback).
packages/docs/app/root.tsx	Adds app root layout + middleware for markdown negotiation/redirects.
packages/docs/app/llms/mdx.ts	Adds per-page markdown output route for LLM integrations.
packages/docs/app/llms/index.ts	Adds llms.txt route.
packages/docs/app/llms/full.ts	Adds llms-full.txt route.
packages/docs/app/lib/source.ts	Adds Fumadocs source loader + markdown/LLM helpers.
packages/docs/app/lib/shared.ts	Centralizes site constants (name/routes/repo).
packages/docs/app/lib/og.ts	Adds helper for OG image path generation.
packages/docs/app/lib/layout.shared.tsx	Adds shared layout options (nav/github URL).
packages/docs/app/lib/cn.ts	Adds Tailwind class merge helper.
packages/docs/app/components/mdx.tsx	Adds MDX component mapping/overrides.
packages/docs/app/app.css	Adds Tailwind + Fumadocs UI styling imports.
packages/docs/.gitignore	Adds docs-package ignores + re-includes app/lib/.
packages/doc-tests/tests/readme-validation.test.ts	Updates doc validation to include the new comparison guide path.
package.json	Removes VitePress scripts/dependency from the root package.
docs/silo.md	Removes old VitePress include stub.
docs/README.md	Removes old VitePress docs README.
docs/queries.md	Removes old VitePress include stub.
docs/public/mascot.svg	Removes old VitePress public asset.
docs/public/hero-grain.svg	Removes old VitePress public asset.
docs/mill.md	Removes old VitePress include stub.
docs/index.md	Removes old VitePress index page.
docs/husk.md	Removes old VitePress include stub.
docs/.vitepress/theme/index.js	Removes old VitePress theme entry.
docs/.vitepress/theme/custom.css	Removes old VitePress theme CSS.
docs/.vitepress/config.mts	Removes old VitePress site config.
.oxfmtrc.json	Ignores formatting for packages/docs/**.
.gitignore	Removes VitePress-specific cache/dist ignores.
.github/workflows/docs.yml	Updates Pages deployment to build/upload the new docs artifact.
.github/workflows/docs-ci.yml	Adds a PR workflow to typecheck/build the isolated docs package.

Files not reviewed (1)

• pnpm-lock.yaml: Generated file

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[scottmessinger]

@copilot Could you please attach screenshots of the new documentation site and resolve the merge conflicts?

[Copilot]

@copilot Could you please attach screenshots of the new documentation site and resolve the merge conflicts?

Addressed in 71fd2ba.

Merge conflicts are resolved, and I added two docs screenshots to the branch so they can be viewed directly here: