ADR-0012 — Documentation platform: mkdocs-material now, Fumadocs later
**Status.** Accepted.
Status. Accepted. Date. 2026-05-19.
Context
The Helios documentation site at docs.helios.mom started on
mkdocs-material: a Python static-site generator with a polished default
theme. It was the obvious choice for the first months — quick to set up,
opinionated, predictable.
Two pressures emerged once the project hit launch readiness:
-
The maintainer of mkdocs-material has announced upcoming backward-incompatible changes that drop the plugin system, break theme overrides, and offer no migration path (see the warning at build time linking to the Feb-2026 announcement). The library is becoming a moving target for projects that depend on its extensibility.
-
Brand direction. The product surface (Mini App, portal) leans into iOS-style glass morphism —
backdrop-filter, soft layered surfaces, warm orange accents on a neutral dark base. The default mkdocs-material chrome looks quite different from the rest of the product, and heavy CSS overrides only partially close the gap (mkdocs-material's Jinja templates emit class names and DOM structure tuned for its native themes, not for from-scratch glass surfaces).
We considered: stay on mkdocs-material; switch to GitBook (SaaS); switch to Docusaurus, VitePress, Astro Starlight, Nextra, or Mintlify; switch to Fumadocs (Next.js + MDX + Tailwind).
Decision
Two-phase migration.
Phase 1 — heavy CSS theming on mkdocs-material (shipped in this ADR)
docs/stylesheets/helios.css overrides the Material chrome to land roughly
70 % of the visual target:
- SF Pro / Inter font stack with antialiased rendering.
- Dark mode as the default; warm orange (
#D97757) brand accent. - Frosted-glass header, tabs, sidebar, search pill, code blocks, admonitions,
tables, buttons — every surface uses
backdrop-filter: blur()plus a semi-translucent fill. - Hero block component with an animated radial-gradient shimmer.
- Feature-card grid for the homepage (the four invariants render as four glass tiles).
- iOS-style spacing: large gutters, generous line-height, gradient text on H1.
- Reduced-motion respected via
@media (prefers-reduced-motion: reduce).
This unblocks the launch — the site at docs.helios.mom now visually
matches the rest of the brand surface, with zero dependency change.
Phase 2 — spike Fumadocs in parallel
Within the next sprint, create apps/docs-site/ containing a Fumadocs
Next.js project that renders one or two existing pages in MDX. Build it,
preview locally, share with the team. Decide whether the additional
fidelity justifies the migration cost.
If approved, Phase 3: migrate every .md page to .mdx, port custom
components, replace mkdocs build with pnpm build, point
docs.helios.mom at the Next.js static export, retire mkdocs.
Why Fumadocs specifically (over Docusaurus, VitePress, Starlight)
| Criterion | Fumadocs | Docusaurus | VitePress | Astro Starlight |
|---|---|---|---|---|
| MDX with React components | ✓ first-class | ✓ | ✗ (Vue) | ✓ |
| Tailwind + shadcn integration | ✓ designed for it | ⚠ via plugin | ⚠ manual | ⚠ manual |
| Built-in local search (no Algolia required) | ✓ Orama | ⚠ requires Algolia or extra plugin | ⚠ basic | ✓ Pagefind |
| OpenAPI-from-spec doc generation | ✓ official plugin | ⚠ community | ✗ | ⚠ community |
| Static export | ✓ Next.js output: 'export' | ✓ | ✓ | ✓ |
| Dark mode + theming primitives | ✓ Tailwind tokens | ✓ via CSS vars | ✓ via CSS vars | ✓ via CSS vars |
| Velocity of development | very high (2024-2026) | mature, slowing | mature | mature, fast |
Fumadocs is the only one that's designed for the Tailwind + shadcn +
Next.js stack the front-end already uses (apps/miniapp/). A migration
keeps the front-end and the docs site sharing tokens, fonts, and
deployment pipeline. The other options each force one trade-off we don't
want — either dropping Tailwind, accepting Vue, or paying for Algolia.
GitBook was ruled out because it is closed SaaS with limited customisation and a per-user fee that scales unfavourably as the team grows. Mintlify was ruled out for the same reasons, plus a hard dependency on their CDN.
Migration risk-box
| Risk | Mitigation |
|---|---|
| MDX is not 100 % Markdown-compatible | Run a one-off automated md → mdx conversion script (@fumadocs/cli); manually inspect admonition blocks and tables |
Loss of mkdocs-material features (e.g. pymdownx.tabbed) | Replace with Fumadocs Tabs and TabsContent components |
| Search index format changes | Reindex on each build; URL paths preserved, so external links survive |
| docs.helios.mom downtime during cutover | Build new site under a path prefix (docs.helios.mom/v2/), flip nginx root atomically |
| Team has to learn React/MDX | Fumadocs MDX feels like Markdown 90 % of the time; React components are only needed for custom layouts |
Status of Phase 1
Shipped as part of the launch. Files:
docs/stylesheets/helios.css— the override stylesheet.docs/javascripts/helios.js— IntersectionObserver-based fade-in.mkdocs.yml— switched dark-first; added font config; loaded the new extra CSS / JS; enabledmd_in_htmlfor the hero/card components.docs/index.md— rewritten to use the hero block and the feature grid.
What to do if Phase 2 doesn't happen
The current setup is sustainable indefinitely. The CSS override is self-contained (one file) and survives any mkdocs-material minor version upgrade. If the mkdocs-material 2.0 break happens before Fumadocs is adopted, the project pins to the last working pre-2.0 release.