feat(docs): migrate the docs site to Fumadocs + shared landing package#13
Merged
Conversation
Foundation for migrating docs from VitePress to a Mintlify-style Fumadocs site (the look identified across the ecosystem). - Scaffolded under website/ (Next.js 16 + fumadocs-mdx + Tailwind), static template (output: export), Orama static search. - Configured for GitHub Pages: basePath /light-runner, trailingSlash, images.unoptimized, so the export serves under the project sub-path. - Removed the AI-chat integration the scaffolder forces (openrouter route, component, layout wiring, deps): a server route is incompatible with static export and unwanted. - next build produces a clean static export (12/12 pages). Remaining (not in this commit): port the landing + 5 guides to MDX, wire the typedoc API reference, theme to the light-process palette, add the Pages deploy workflow, and remove the old VitePress docs. build with cc
- Convert docs/guides/*.md (quickstart, extract, detached, security, gvisor-kata) into website/content/docs/*.mdx, deriving the frontmatter title from each H1. - Replace the scaffold placeholder index.mdx with a real light-runner intro, drop the default test.mdx. - Add content/docs/meta.json to order the sidebar. - next build renders all 6 docs pages as a clean static export. build with cc
- Set the primary accent to Tailwind blue-600 (light) / blue-400 (dark) on the neutral gray scale, matching the light-process docs palette. - Generate the typedoc-markdown API reference into content/docs/api and rewrite it for Fumadocs (frontmatter titles + header stripped) via scripts/gen-fumadocs-api.mjs; Fumadocs auto-builds the API sidebar. - Order the api group into the docs nav. - Enrich the intro example (real fields entrypoint/dir/input/extract, with detached/networks as commented options). - next build renders 93 static pages (guides + full API reference). build with cc
typedoc-plugin-markdown emits relative `.md` cross-links (e.g. `../interfaces/RunRequest.md`); Fumadocs routes have no `.md`, so clicking them 404s. gen-fumadocs-api.mjs now rewrites internal `.md` links to absolute Fumadocs routes (`/docs/api/interfaces/RunRequest`), preserving anchors and leaving external https links untouched. Rebuild stays green (93 pages). build with cc
typedoc cleans its output dir on every run, deleting the hand-written content/docs/api/meta.json. gen-fumadocs-api.mjs now rewrites it after generation, so the API-reference group title and ordering survive a regen. build with cc
- Replace the scaffold placeholder home with a real landing (hero, primitives, quick start, security model, ecosystem, footer) on the blue/gray theme. - Set appName to light-runner and gitConfig to enixCode/light-runner (was the scaffold default My App / fuma-nama-fumadocs). - Add root metadata (title, description, metadataBase), which also clears the build metadataBase warning. build with cc
The default Fumadocs llms.txt emits `# Docs` with root-relative links. Per the llmstxt.org spec, set the H1 to the project name, add a blockquote summary, and rewrite links to absolute deployed URLs (domain + basePath) so they are followable. build with cc
Port the original VitePress landing to the Fumadocs home: the dark bespoke design (hero + banner, primitives, code window, security grid, ecosystem, footer) with the Fraunces / JetBrains Mono type, live GitHub version badges, and the copy button. - landing.css: the original bespoke stylesheet, with the three global selectors (code/pre, footer, focus rings) scoped to .bespoke-landing so it cannot leak into the docs pages; Google Fonts imported. - page.tsx: HTML ported to JSX as a client component; the script (GitHub release fetch + copy) ported to a useEffect; the code sample uses dangerouslySetInnerHTML to keep the syntax spans verbatim. - The home route drops Fumadocs HomeLayout chrome to render full-bleed. - Copy banner.webp into website/public. build with cc
The home now renders LandingPage data={lightRunnerData} from the shared
light-landing-page package (git dependency) instead of an in-repo copy. The
bespoke design, CSS and logic live in the package; only lightRunnerData (brand,
hero, primitives, security, ecosystem, links) is local. The local landing.css
is dropped. A design change now ships to every light-* site from one source.
build with cc
- Replace the VitePress docs with the Fumadocs static site under website/. - docs.yml now regenerates the API (docs:api), builds the Next.js static export and deploys website/out to Pages (was: VitePress build + dist). - package.json: drop vitepress and the vitepress docs scripts. docs:api, docs:dev and docs:build now drive the Fumadocs site; preversion and the pre-commit hook regenerate website/content/docs/api. - Remove the docs/ VitePress tree (landing, guides, api, .vitepress, public); all of it now lives in website/. - Update CLAUDE.md docs references. build with cc
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Migrates the documentation from VitePress to a Fumadocs static-export site, and extracts the bespoke landing into a shared package so the three light-* sites share one design.
What
website/(Next.js 16 + Fumadocs, static export,basePath: /light-runner, Orama search). The 5 guides are ported to MDX; the API reference is auto-generated fromsrc/byscripts/gen-fumadocs-api.mjs(typedoc-markdown + frontmatter + extensionless link rewrite) and auto-sidebarred.light-landing-pagepackage and is rendered as<LandingPage data={lightRunnerData} />. Design changes ship to all light-* sites from one source.docs.ymlregenerates the API then builds + deploys the Next.js static export (website/out);package.jsondrops vitepress and rewiresdocs:api/docs:dev/docs:build;preversionand the pre-commit hook regeneratewebsite/content/docs/api; the olddocs/VitePress tree is removed.Go-live
Merging deploys the Fumadocs site to GitHub Pages, replacing VitePress.
build with cc