ADR-001 — Docs framework
Fumadocs picked over Docusaurus, Nextra, Astro Starlight, and a custom Next.js build for docs.bassclef.dev.
ADR-001 — Docs framework
Status. Accepted 2026-07-27.
Authors. kingofrock + claude opus 4.7.
Context
bassclef needs a docs site at docs.bassclef.dev to serve three
personas — Sam (evaluate in ≤90s), Louis (adopt in one tool-tuning
window), and Morgan (judge in a Sunday coffee hour). The site
targets ~30 static routes + ~40 dynamic skill pages. It ships from
this monorepo and deploys to Cloudflare Pages via static export.
Constraints: React + TypeScript (rest of repo is TS); MDX authoring (bassclef writers know Markdown); dark mode support; full-text search; fast build (docs iterate frequently). Preferred: minimum lock-in to any single framework's opinions.
Decision
Pick Fumadocs 16.15 (with fumadocs-mdx + fumadocs-ui + Next.js
16.3 + Tailwind v4). Static export target. Deployed as a second
Cloudflare Pages project reading from docs-site/ subdirectory.
Custom TSX components mount inline in MDX. Fumadocs handles sidebar,
search, dark mode, and route generation. Content lives under
docs-site/content/docs/.
Consequences
Easier: authoring MDX with custom components, mounting client components inline, dark-mode-per-OS defaults, full-text search out of the box.
Harder: any behavior Fumadocs does not expose as a slot needs a fork or a workaround. Migrating to a different framework later requires re-authoring the top-level layout and re-wiring components.
Unblocked: WU-4 Morgan judge flow (ADR components + Discoveries
- concept pages), WU-5 CF Pages deploy path.
Blocked: none.
Rejected alternatives
Docusaurus — mature, well-known, MDX support, plugins ecosystem. Rejected because: React 17 default (we want React 19), slower cold starts, opinions about sidebar structure that fight the concentric IA.
Nextra — Next.js + MDX + minimal opinions. Rejected because: smaller community, fewer plugins, sidebar UX weaker than Fumadocs default.
Astro Starlight — Astro-based, fast, great DX. Rejected because: Astro is a new stack for this repo (rest is Next.js), and inline React component mounting requires more ceremony than Fumadocs offers.
Custom Next.js build — full control, no framework lock-in. Rejected because: reinvents sidebar, search, MDX loader, dark mode — all the pieces Fumadocs already handles well. Time cost too high for the benefit.
Exit cost
Small. MDX content is portable — every .mdx file works in
Docusaurus, Nextra, Astro, or a custom build with minor
adjustments (mostly the component imports and frontmatter schema).
Custom components are portable — HeroSection, Tightest3Cards,
InstallCommandBlock, SubstackSignupForm, FailureClassCard,
SkillCatalogFilter, ConfigCallout, SourceCodeLink,
AdopterActivityFeed, and the ADR parts (Context, Decision, etc.)
depend only on React + @/lib/shared. Copy them to a new framework
with no rewrite.
Non-portable pieces: layout wiring (lib/layout.shared.tsx),
source loader (lib/source.ts), and search route
(app/api/search/route.ts). Around 100 lines of Fumadocs-specific
wiring. Estimated 1-2 days to re-wire in a different framework.
The exit cost is small because bassclef consciously kept business logic outside Fumadocs. See state-spine for the pattern (Hexagonal Architecture per spec § Patterns Used).