Documentation Framework Comparison
1. Executive Summary
SecurityV0's documentation currently uses MkDocs Material, which is entering maintenance mode (final version 9.7.0, Insiders repo deletion May 2026). The successor project Zensical is promising but pre-1.0 and unproven at scale.
This is two separate decisions, not one:
- Customer-facing/public docs — product narrative, getting started, API reference. Needs strong design, navigation, and Cloudflare Pages deployment. No Obsidian dependency.
- Internal/private engineering docs — ~238 Markdown files, ~446 wiki-link occurrences, active Dataview usage. Must stay AI-agent readable and Obsidian-compatible.
This document evaluates six frameworks against both surfaces. After detailed analysis, Starlight (Astro) emerges as the frontrunner for customer-facing docs, with Docusaurus 3 as a strong co-equal that should be prototyped alongside. Internal docs should remain on MkDocs Material until a migration gate is proven against the real vault. We explicitly do not recommend committing to a single framework for both surfaces at this time.
2. Comparison Matrix
| Criteria | MkDocs Material | Docusaurus 3 | Nextra 4 | Starlight (Astro) | Mintlify | VitePress |
|---|---|---|---|---|---|---|
| GitHub Stars | ~22k | ~63k | ~13k | ~8k (Starlight) / ~49k (Astro) | N/A (closed-source) | ~17k |
| License | MIT | MIT | MIT | MIT | Proprietary | MIT |
| Language | Python | TypeScript/React | TypeScript/Next.js | TypeScript/Astro | Proprietary | TypeScript/Vue |
| Pure .md support | Yes (native) | Partial (CommonMark opt-in) | No (MDX required) | Yes (native) | Partial (.md + .mdx) | Yes (native) |
| Obsidian wiki-links | Plugin (mkdocs-obsidian-bridge) | Plugin (docusaurus-plugin-obsidian-vault) | No known plugin | Plugin (starlight-obsidian) | No | Plugin (markdown-it-wikilinks-plus) |
| YAML frontmatter | Full support | Full support | Full support (exported as metadata) | Full support (typed validation) | Full support | Full support |
| Multi-site | Deprecated Projects plugin | Native multi-instance | Separate Next.js apps | Monorepo with multiple Starlight instances | Separate projects | Separate VitePress instances |
| Cloudflare Pages | Yes (static) | Yes (static, official guide) | Tricky (Next.js on CF) | Yes (first-class CF adapter) | No (hosted only) | Yes (static, official guide) |
| Dark mode | Built-in | Built-in | Built-in | Built-in | Built-in | Built-in |
| Search | lunr.js / Algolia | Algolia / Pagefind community | Pagefind (built-in v4) | Pagefind (built-in) | AI-powered (hosted) | MiniSearch (built-in) |
| Versioning | mike plugin | Native | Manual | Community plugin | Native | Manual |
| i18n | Plugin-based | Native | Native | Native (60+ languages) | Limited | Native |
| JS shipped to client | Minimal | Heavy (React SPA) | Heavy (Next.js) | Zero by default | N/A | Moderate (Vue) |
| Build speed | Moderate | Slow (large sites) | Moderate | Fast | N/A | Fast (Vite) |
| Migration effort | Baseline | Medium | High | Low-Medium | High | Medium |
| Pricing | Free/OSS | Free/OSS | Free/OSS | Free/OSS | $0-$600+/mo | Free/OSS |
| Maintenance status | Maintenance mode | Active | Active (The Guild) | Active (Astro team) | Active (VC-funded) | Active (Vue team) |
| AI agent friendliness | Excellent (.md files) | Good (.md/.mdx files) | Poor (MDX required) | Excellent (.md files) | Poor (hosted, no local files) | Excellent (.md files) |
Rating Legend
- Excellent / Native / Yes = full support, no workarounds needed
- Good / Partial / Plugin = works with minor configuration or community plugin
- Poor / No / Tricky = significant friction, workarounds, or not possible
3. Hard Requirements Checklist
Note (post-review): The original version of this section used a single pass/fail matrix for both internal and customer-facing docs. The review correctly identified that these are different problems with different requirements. The matrix is now split.
3a. Customer-Facing / Public Docs
| Requirement | MkDocs Material | Docusaurus 3 | Nextra 4 | Starlight | Mintlify | VitePress |
|---|---|---|---|---|---|---|
| 1. Markdown support (.md authoring) | PASS | PASS (experimental CommonMark) | WEAK (content dir supports .md, but MDX is primary path) | PASS | WEAK (.md accepted, proprietary schema) | PASS |
| 2. Cloudflare Pages deployment | PASS | PASS | WEAK (official CF guide exists, but added complexity via OpenNext/Workers) | PASS (first-class adapter) | FAIL (hosted only) | PASS |
| 3. Modern, enterprise UI | WEAK (functional but dated) | PASS | PASS | PASS | PASS (best out-of-box design) | PASS |
| 4. Navigation at 100+ pages | WEAK (wall of links, limited tabs) | PASS (tabs + sidebar) | PASS (sidebar groups) | PASS (groups + tabs) | PASS | PASS (sidebar groups) |
| 5. Theming / CSS customization | PASS (CSS variables) | WEAK (Infima lock-in, Tailwind conflicts) | PASS (Tailwind native) | PASS (CSS variables + Tailwind CLI) | N/A (hosted) | PASS (CSS variables) |
| 6. Multi-site separation | WEAK (possible via separate configs, but duplicated maintenance) | PASS (native multi-instance) | PASS (separate apps) | PASS (monorepo) | PASS (separate projects) | PASS (separate instances) |
3b. Internal / Private Engineering Docs
| Requirement | MkDocs Material | Docusaurus 3 | Nextra 4 | Starlight | Mintlify | VitePress |
|---|---|---|---|---|---|---|
| 1. Pure .md first-class (AI-readable) | PASS | WEAK (CommonMark experimental, MDX default) | WEAK (content dir .md, but MDX primary) | PASS | FAIL (hosted, no local files) | PASS |
| 2. Obsidian wiki-links | PASS (plugins) | PASS (community plugin) | No known plugin | PASS (starlight-obsidian, single maintainer) | No | PASS (markdown-it plugin) |
| 3. YAML frontmatter + Dataview | PASS (native) | Frontmatter yes, Dataview no | Frontmatter yes, Dataview no | Frontmatter yes (typed), Dataview via content collections | No | Frontmatter yes, Dataview via createContentLoader |
| 4. Vault scale (238 files, 446 wiki-links) | PASS (current, proven) | Unproven at this scale | Unproven | Unproven (starlight-obsidian untested on real vault) | N/A | Unproven |
| 5. AI agent readability (raw grep/read) | PASS | PASS (.md files in repo) | PASS (.md files in repo) | PASS (.md files in repo) | FAIL | PASS (.md files in repo) |
Assessment Summary
For customer-facing docs: Starlight, Docusaurus, and VitePress are all viable. Starlight and Docusaurus should be prototyped head-to-head on real content.
For internal docs: MkDocs Material is the only framework proven against our actual vault. Any migration requires testing against the real 238-file, 446-wiki-link corpus before committing.
Framework Notes (revised from original)
- Nextra 4: Originally marked as hard FAIL on Markdown and CF Pages. Revised: Nextra's
contentdirectory does support.mdfiles, and Cloudflare has an official Next.js Pages guide. However, MDX remains the primary authoring path, wiki-link support is absent, and CF deployment adds OpenNext/Workers complexity. Still the weakest candidate but not a categorical disqualification. - Mintlify: Hosted-only remains a hard constraint for CF Pages self-deployment. The custom-frontend docs should be rechecked but current evidence points to hosted-only for the docs surface. Not viable for our self-hosted requirement.
- MkDocs Material: Originally marked FAIL on multi-site. Revised: two separate
mkdocs.ymlconfigs can serve internal and customer sites. The real issue is duplicated configuration and maintenance burden, not impossibility. Still a weak choice for the customer site due to navigation limitations and maintenance-mode status. - Docusaurus CommonMark: Available via
markdown.format: 'commonmark', but Docusaurus docs explicitly mark this as experimental. Directionally fair for customer docs (where Obsidian compat is not needed), but carries migration risk for internal docs where pure .md fidelity is critical.
Remaining strong candidates: Starlight and Docusaurus (prototype both). VitePress as fallback.
4. Detailed Analysis
4.1 MkDocs Material (Current Baseline)
Version: 9.7.x (final release) Stack: Python, Jinja2 templates, lunr.js search Stars: ~22,000 on GitHub
What It Does Well
- Pure Markdown with zero friction; every
.mdfile is a page - Excellent YAML frontmatter support (our ~170 files work as-is)
- Rich plugin ecosystem (300+ community plugins)
- Mature, battle-tested across thousands of projects
- Obsidian compatibility via
mkdocs-obsidian-bridgeandmkdocs-wikilinks-plugin - Good Cloudflare Pages deployment (pure static output)
- AI agents (Claude Code) can grep and read all
.mdfiles natively
Critical Issues
Maintenance mode: Version 9.7.0 is the final feature release. Critical bugs and security fixes only for 12 months. The Insiders repository will be deleted on May 1, 2026. No new features.
Zensical successor: The team has launched Zensical (MIT-licensed, compatible with mkdocs.yml), promising 4-5x faster incremental builds and a new search engine (Disco). However:
- Pre-1.0, limited production deployments
- Module system not yet open to third-party developers (early 2026 target)
- Unknown timeline for feature parity with Material for MkDocs
- Community ecosystem (plugins) will need to be rebuilt or ported
Projects plugin deprecated: The multi-site Projects plugin is being dropped, leaving no official path for internal/customer-facing separation within a single build.
Navigation: The sidebar becomes a wall of links at 100+ pages. No native tabs, collapsible groups are limited, and custom nav requires manual nav: configuration in mkdocs.yml that becomes unwieldy.
Theming: The Material theme is recognizable and professional but increasingly dated. Limited component-level customization without forking the theme.
Verdict
MkDocs Material is a known quantity that works today but is a dead-end for new features. The Zensical transition introduces risk. The Projects plugin deprecation blocks our internal/customer-facing split requirement. Not recommended as the long-term choice, but acceptable for the internal site in the short term.
4.2 Docusaurus 3 (Meta / React)
Version: 3.9.2 (latest stable; v4.0 in planning) Stack: TypeScript, React 18, MDX 3, Webpack/Rspack Stars: ~63,000 on GitHub Backing: Meta Open Source
Markdown Support
Docusaurus uses MDX by default for all files (including .md), but you can opt into CommonMark mode via siteConfig.markdown.format: 'commonmark' or per-file via mdx.format frontmatter. This is critical: it means existing .md files can be used without conversion, though you lose JSX component embedding in CommonMark mode (acceptable for our use case).
YAML frontmatter is fully supported and used for page metadata, sidebar labels, descriptions, and custom fields.
Obsidian Compatibility
The docusaurus-plugin-obsidian-vault community plugin automatically transforms Obsidian-specific syntax (wiki-links, callouts) into Docusaurus-compatible markdown. This handles the [[doc-name]] syntax in our relates-to: frontmatter fields.
However, this is a build-time transformation, not a runtime feature. The raw .md files in the repo would still contain wiki-links (which is what we want for Obsidian browsing and AI agent access).
Dataview-style queries have no equivalent. Would need custom React components or build-time scripts to replicate Dataview functionality on the published site.
Multi-Instance (Internal/Customer-Facing)
Docusaurus has native multi-instance support for the docs plugin. You can run two separate docs plugin instances within a single Docusaurus site (e.g., /docs/ for customer-facing, /internal/ for architecture docs) with independent sidebars and versioning.
Alternatively, you can run two completely separate Docusaurus sites from the same monorepo, each with its own docusaurus.config.js. This is the cleaner approach for us since internal docs should not be publicly accessible.
Cloudflare Pages
Docusaurus generates static HTML. Cloudflare has an official deployment guide and a Docusaurus framework preset in the Pages dashboard. Build command: npm run build, output directory: build/. No known issues.
Navigation UX
- Top-level tabs (navbar items) for major sections
- Collapsible sidebar with auto-generated or manual categories
- Breadcrumbs
- Versioning dropdown (native)
- Search via Algolia DocSearch (free for OSS) or community Pagefind plugin
- Pagination (next/previous)
- Category index pages
Handles 100+ pages well through the combination of tabs + collapsible sidebar categories.
Theming & Enterprise Look
The default theme (classic) is clean and professional. Swizzling (component override system) allows deep customization. Dark mode is built-in. Custom CSS is straightforward. Several enterprise-quality documentation sites use Docusaurus (Supabase, Cloudflare Workers, Meta's own docs).
However, the React SPA model means heavier client-side JavaScript (~200-400KB). This affects initial load performance on slow connections.
Community & Maintenance
- 63k GitHub stars, 8.5k forks
- Backed by Meta with dedicated maintainers
- Very active ecosystem: 1000+ community plugins
- Regular releases (monthly patches, current stable 3.9.2)
- v4.0 in planning with open milestones
- Large adoption: used by thousands of companies (Supabase, Algolia, Hasura, Redux, React Native, Ionic)
Concerns
- MDX-first philosophy means some friction with pure Markdown workflows
- React SPA: heavier JS bundle than static-only generators (~200-400KB)
- Build times can be slow for very large sites (1000+ pages), though Docusaurus Faster (v3.6+) with Rspack and SWC improves this ~2x
- CommonMark mode, while available, is not the primary path and may have edge cases
4.3 Nextra 4 (Next.js / The Guild)
Version: 4.x (App Router) Stack: TypeScript, Next.js (App Router), MDX Stars: ~13,000 on GitHub Backing: The Guild (GraphQL ecosystem)
Markdown Support
Nextra requires MDX (.mdx files). All content files are processed through the MDX compiler. There is no opt-in for pure CommonMark mode. This is a hard blocker for our Markdown-first requirement.
Frontmatter is fully supported and exported as a metadata object in each MDX file.
Obsidian Compatibility
No known plugin or integration for wiki-links. MDX processing would break on [[wiki-link]] syntax (interpreted as JSX). Converting 125+ files with wiki-links in frontmatter would require a custom build-time transformer.
Dataview queries: no equivalent.
Multi-Site
Multiple Nextra apps can be created in a monorepo, each as a separate Next.js application. There is no built-in multi-instance feature like Docusaurus.
Cloudflare Pages
Next.js on Cloudflare Pages is problematic. The @cloudflare/next-on-pages package exists but has known limitations. Cloudflare is moving toward OpenNext for Workers, which adds complexity. Pure SSG (static export) from Next.js works on CF Pages but loses many Next.js features. This is unreliable for production use.
Navigation
Nextra provides file-system based routing with auto-generated sidebar, collapsible groups, and Pagefind search (built-in since v4). The sidebar handles large doc sets adequately.
Theming
Clean, modern design. The docs theme is professional. Dark mode built-in. Component customization through Next.js App Router layouts.
Verdict
Disqualified. MDX requirement breaks Markdown-first and Obsidian compatibility. Cloudflare Pages deployment is unreliable for Next.js apps. The framework is good for React/Next.js teams building API docs, but wrong for our use case.
4.4 Starlight (Astro)
Version: 0.x (latest, pre-1.0 but widely used in production) Stack: TypeScript, Astro 5, Vite, MDX + Markdoc Stars: ~8,000 (Starlight) / ~49,000 (Astro framework) Backing: Astro (funded startup, dedicated team)
Markdown Support
Starlight supports three content formats: Markdown (.md), Markdoc (.mdoc), and MDX (.mdx). Plain Markdown is a first-class citizen. You can mix formats within the same project. No MDX conversion required.
YAML frontmatter is fully supported with built-in TypeScript validation through Astro's content collections. Starlight defines a frontmatter schema and validates it at build time, catching errors early. Custom frontmatter fields (like our relates-to, source, priority) can be accessed in templates.
This is the strongest Markdown story of any framework evaluated.
Obsidian Compatibility
The starlight-obsidian plugin is purpose-built for publishing Obsidian vaults through Starlight. It:
- Reads vault contents and converts them to Starlight-compatible pages
- Transforms
[[wiki-links]]to proper HTML links - Handles Obsidian callout syntax
- Generates sidebar navigation from vault structure
- Optionally filters vault contents (include/exclude paths)
This is the most complete Obsidian integration of any framework evaluated. The raw .md files in the repo remain untouched (Obsidian-compatible), and the build-time transformation handles the conversion.
For our use case: the 125+ files with [[wiki-links]] in relates-to: frontmatter would be handled by the plugin. The files remain browsable in Obsidian as-is.
Dataview-style queries: no direct equivalent, but Astro's content collections API allows build-time queries by frontmatter fields (type, tags, status), which can replicate most Dataview functionality through custom components.
Multi-Site / Monorepo
Starlight supports multiple documentation sites in a monorepo. You can create separate Astro projects (one for internal, one for customer-facing) sharing common configuration. Each builds independently to its own static output.
Alternatively, a single Starlight site with route-based access control could serve both, but separate builds are cleaner for our public/private split.
The Astro monorepo story is well-documented and used by projects like Arcjet for multi-framework documentation.
Cloudflare Pages
Astro has a first-class Cloudflare adapter (@astrojs/cloudflare). For Starlight (pure static), you don't even need the adapter — just build to static HTML and deploy. Cloudflare has an official Astro deployment guide.
Build command: npm run build, output directory: dist/. Zero friction.
Navigation UX
- Sidebar with collapsible groups (auto-generated from file structure or manual)
- Tabbed navigation at the top level
- Breadcrumbs
- Search via Pagefind (built-in, zero-config, works offline)
- Previous/next page links
- Table of contents (right sidebar)
- Badge support for sidebar items (new, deprecated, etc.)
- Link cards and card grids for landing pages
Handles 100+ pages well. The sidebar grouping with collapse is specifically designed for large documentation sites.
Theming & Enterprise Look
Starlight's default theme is modern, clean, and professional. CSS custom properties allow deep theming without forking. Dark mode is built-in with automatic detection. Code blocks use Shiki (syntax highlighting at build time, zero runtime JS).
The zero-JavaScript-by-default approach means pages load instantly. This is the best performance story of any framework evaluated.
For a CISO/enterprise audience: the clean, fast, professional appearance is ideal. No "open-source project" feel.
Search
Pagefind is built-in and requires zero configuration. It builds a search index at build time and runs entirely client-side with a tiny (~5KB) JavaScript payload. Search quality is excellent for documentation sites.
Plugin Ecosystem
Starlight has a growing plugin ecosystem:
starlight-obsidian— Obsidian vault integrationstarlight-openapi— OpenAPI/Swagger docsstarlight-typedoc— TypeScript API referencestarlight-links-validator— Link checkingstarlight-blog— Blog support- 50+ community plugins listed on the Starlight site
The Astro integration ecosystem is larger (400+ integrations).
Community & Maintenance
- Astro: ~49k stars, well-funded startup, regular major releases
- Starlight: ~8k stars, actively maintained by the Astro core team
- Monthly releases with new features
- Growing adoption: Arcjet (security), Cloudflare, The Guild, Biome, Tinybird, Distr use Starlight
- Arcjet (AI runtime security -- bot detection, rate limiting, attack protection) is a directly relevant security industry reference case
- Companies have migrated from Docusaurus to Starlight citing better performance and easier PR reviews
Concerns
- Starlight is still pre-1.0. Breaking changes possible, though the Astro team has been conservative
- Smaller plugin ecosystem than Docusaurus or MkDocs
- Less familiar to teams with React/Vue experience (Astro has its own component model, though it supports React/Vue islands)
- starlight-obsidian plugin is maintained by a single developer (HiDeoo), though they are prolific in the Starlight ecosystem
4.5 Mintlify
Version: Proprietary (SaaS) Stack: Proprietary, MDX-based Stars: N/A (closed source) Backing: VC-funded startup
Markdown Support
Mintlify supports .md and .mdx files. Content lives in a Git repository and is synced to Mintlify's hosted platform. However, the files must conform to Mintlify's specific frontmatter schema and component syntax.
Every published page is accessible as Markdown by appending .md to the URL. Mintlify auto-generates /llms.txt for LLM indexing.
Obsidian Compatibility
No wiki-link support. No known integration with Obsidian vaults. Frontmatter must follow Mintlify's schema (different from our custom fields).
Multi-Site
Separate Mintlify projects for internal and customer-facing docs. Each project has its own configuration and deployment.
Cloudflare Pages
Not possible. Mintlify is a hosted-only platform. Your docs are built and served on Mintlify's infrastructure. You cannot self-host or deploy to Cloudflare Pages.
Pricing
- Hobby: Free (1 editor, basic features, Mintlify branding)
- Pro: $300/month ($212/mo with annual billing at ~15% off; 5 editors, AI search, custom domain, analytics)
- Enterprise/Custom: $600+/month (SSO, advanced access control, priority support)
- Extra editor seats: $20/month each
- SOC 2 Type II compliant
- AI agent can monitor codebase and propose doc updates via GitHub PRs
Strengths
- Excellent API documentation with auto-generated playground from OpenAPI specs
- Beautiful default design (arguably the best-looking out of the box)
- AI-powered search and chat
- Analytics dashboard
- Very fast setup
Verdict
Disqualified. Hosted-only (no Cloudflare Pages), no Obsidian compatibility, significant vendor lock-in, expensive at scale. The API playground is compelling for customer-facing docs but doesn't justify the constraints. If we ever need an API playground, Starlight's starlight-openapi plugin or Docusaurus's Swagger UI integration can fill this gap.
4.6 VitePress (Vue.js)
Version: 1.6.4 (stable; v2.0.0-alpha in development) Stack: TypeScript, Vue.js, Vite Stars: ~17,000 on GitHub Backing: Vue.js core team (Evan You)
Markdown Support
VitePress is strongly Markdown-first. All .md files are compiled to Vue components at build time, but the authoring experience is pure Markdown. No MDX or special syntax required. YAML frontmatter is fully supported.
Markdown extensions include custom containers, code groups, line highlighting, and import code snippets — all using standard Markdown-compatible syntax (no JSX).
Obsidian Compatibility
The markdown-it-wikilinks-plus plugin adds [[wiki-link]] support to VitePress's markdown-it pipeline. It handles [[Page]], [[Page#Section]], and [[Page|Label]] syntax.
YAML frontmatter works natively. Custom fields are accessible in Vue templates.
No Dataview equivalent, but VitePress's createContentLoader API allows build-time data loading from frontmatter, enabling similar functionality with custom Vue components.
Multi-Site / Monorepo
VitePress supports monorepos via the rewrites configuration, mapping files from multiple packages to output paths. However, this is a single-site solution with file remapping, not true multi-site.
For separate internal/customer-facing sites, you would run two VitePress instances with separate configs. This is well-supported in monorepo setups.
Cloudflare Pages
VitePress generates static HTML. Cloudflare has an official deployment guide. Build command: npm run docs:build, output directory: .vitepress/dist. Zero friction.
Navigation UX
- Sidebar with collapsible groups
- Top-level navbar with dropdown menus
- Search via MiniSearch (built-in, client-side, fast)
- Previous/next page links
- Table of contents (right sidebar, auto-generated)
- Markdown frontmatter controls sidebar label, order, and collapse state
Handles 100+ pages adequately through sidebar groups, though the UX is less polished than Starlight or Docusaurus for very large sites.
Theming & Enterprise Look
The default theme is clean and modern. Vue's Vite HMR provides instant development feedback. Custom CSS via CSS variables. Dark mode built-in with toggle. Component override via Vue slots and layout system.
The aesthetic is professional but has a "Vue ecosystem" feel. Less enterprise/security-oriented than Starlight's or Mintlify's defaults, but fully customizable.
Search
MiniSearch is built-in and performs well for documentation-sized sites. Client-side, zero-config. For larger sites, Algolia DocSearch integration is available.
Community & Maintenance
- 17k stars, backed by Vue.js core team
- Evan You is a listed maintainer
- Regular releases, stable API (v1 since 2024)
- Used by Vue.js, Vite, Vitest, Pinia, and many Vue ecosystem projects
- Smaller third-party plugin ecosystem than Docusaurus
Concerns
- Vue.js dependency: our team works in React (UI) and Python (connectors), adding Vue adds a new framework to the stack
- Plugin ecosystem is smaller than Docusaurus or MkDocs
- Multi-site story is less elegant than Docusaurus's native multi-instance
- Sidebar configuration is manual for complex hierarchies
- Less component-level customization than Docusaurus (no swizzling equivalent)
4.7 Notable Contenders
Fumadocs (Next.js)
Version: 16.x | Stars: ~3,000 | Stack: Next.js App Router, MDX, Tailwind CSS | License: MIT
Fumadocs is the most visually polished open-source Mintlify alternative. It provides a beautiful default theme, built-in search via Orama or Algolia, OpenAPI integration, and headless mode for full UI control. Used by Vercel, Unkey, and Orama.
Why not recommended: Smaller community (3k stars), individual maintainer risk, same Next.js/Cloudflare Pages caveats as Nextra. Worth monitoring as it matures but not production-ready for our needs.
Zensical (MkDocs Material Successor)
Version: Pre-1.0 | Stack: New static site generator by squidfunk | License: MIT
The official successor to MkDocs Material, built from the ground up. Promises 4-5x faster incremental builds, native mkdocs.yml compatibility, and a new module system. Zensical Spark is the professional offering.
Key timeline:
- Module system opening to third-party developers: early 2026
- MkDocs Material Insiders repo deletion: May 1, 2026
- MkDocs Material security fixes end: November 2026
Why not recommended yet: Pre-1.0, module ecosystem does not exist, limited production deployments. The lowest-friction migration path from MkDocs Material, but too early to bet on. Monitor through 2026.
5. Migration Path Analysis
5.1 Starlight (Recommended — Lowest Effort)
Estimated effort: 2-3 days for initial setup, 1 week for full migration
| Task | Effort | Notes |
|---|---|---|
| Project scaffolding | 2 hours | npm create astro@latest -- --template starlight |
| Install starlight-obsidian | 1 hour | Configure vault path, include/exclude patterns |
| Migrate mkdocs.yml nav to Starlight sidebar config | 4 hours | Manual but straightforward mapping |
| Custom frontmatter schema | 2 hours | Define Astro content collection schema for our fields |
| Theme customization (colors, fonts, logo) | 4 hours | CSS custom properties, minimal effort |
| Wiki-link handling validation | 4 hours | Test all 125+ files with [[wiki-links]] via starlight-obsidian |
| Cloudflare Pages deployment | 2 hours | Standard Astro static build |
| Search validation (Pagefind) | 1 hour | Zero-config, just verify results |
| Customer-facing site scaffold | 4 hours | Separate Astro/Starlight project in monorepo |
| Total | ~24-30 hours |
Why lowest effort: Starlight's starlight-obsidian plugin handles the most complex part (wiki-links, vault structure) automatically. Pure .md files work without conversion. Frontmatter is preserved.
Risks: starlight-obsidian plugin stability (single maintainer). Mitigation: the plugin is open-source and the transformation logic is straightforward enough to maintain ourselves if needed.
5.2 Docusaurus 3 (Runner-Up)
Estimated effort: 3-5 days for initial setup, 1.5 weeks for full migration
| Task | Effort | Notes |
|---|---|---|
| Project scaffolding | 2 hours | npx create-docusaurus@latest |
| Configure CommonMark mode | 1 hour | markdown.format: 'commonmark' in config |
| Install docusaurus-plugin-obsidian-vault | 2 hours | Configure wiki-link transformation |
| Migrate mkdocs.yml nav to sidebars.js | 6 hours | Different format, more verbose |
| Frontmatter adaptation | 4 hours | Map custom fields, ensure compatibility |
| Theme customization | 6 hours | Swizzle components, custom CSS |
| Wiki-link handling validation | 6 hours | Test plugin with all 125+ files |
| Cloudflare Pages deployment | 2 hours | Standard static build |
| Search setup (Algolia or Pagefind) | 4 hours | Algolia requires account setup; Pagefind needs community plugin |
| Customer-facing site (multi-instance) | 6 hours | Configure second docs plugin instance or separate site |
| Total | ~39-48 hours |
Why more effort: CommonMark mode is opt-in (not default), Obsidian plugin is less mature than starlight-obsidian, sidebar configuration is more complex, and React SPA theming requires more work for enterprise aesthetics.
5.3 VitePress (Third Option)
Estimated effort: 3-5 days for initial setup, 1.5 weeks for full migration
| Task | Effort | Notes |
|---|---|---|
| Project scaffolding | 2 hours | Standard VitePress init |
| Install markdown-it-wikilinks-plus | 2 hours | Configure in VitePress markdown-it pipeline |
| Migrate mkdocs.yml nav to VitePress sidebar config | 6 hours | Manual JSON config |
| Frontmatter handling | 3 hours | Access custom fields in Vue templates |
| Theme customization | 8 hours | Vue-based theming, new framework for the team |
| Wiki-link handling validation | 6 hours | Test all 125+ files |
| Cloudflare Pages deployment | 2 hours | Standard static build |
| Search validation (MiniSearch) | 1 hour | Built-in, verify results |
| Customer-facing site scaffold | 4 hours | Separate VitePress project |
| Total | ~34-42 hours |
Added cost: Team needs to learn Vue.js basics for any customization beyond CSS. This is an ongoing cost, not a one-time migration cost.
6. Internal vs Customer-Facing Architecture
The Two-Site Problem
SecurityV0 needs two distinct documentation surfaces:
| Aspect | Internal Docs | Customer-Facing Docs |
|---|---|---|
| Audience | Engineering team, AI agents | CISOs, security teams, integrators |
| Content | Architecture, ADRs, research, runbooks, plans | Product docs, API reference, getting started |
| File count | ~170 files (growing) | ~20-50 files (to be built) |
| Access | Private (GitHub repo) | Public (deployed site) |
| Obsidian usage | Heavy (vault, wiki-links, Dataview) | None (standard docs) |
| Update frequency | Daily | Weekly/release-aligned |
| AI agent access | Critical (Claude Code reads these) | Not required |
Architecture Options by Framework
Option A: Starlight (Recommended)
sv0-documentation/
├── docs/ # Internal docs (Obsidian vault)
│ ├── architecture/
│ ├── runbooks/
│ └── ...
├── internal-site/ # Starlight project for internal docs
│ ├── astro.config.mjs # Uses starlight-obsidian plugin
│ └── package.json
├── customer-site/ # Starlight project for customer docs
│ ├── src/content/docs/ # Customer-facing .md files
│ ├── astro.config.mjs
│ └── package.json
└── mkdocs.yml # Keep for backward compat during transition
- Internal site uses
starlight-obsidianto render the Obsidian vault - Customer site is a clean Starlight project with purpose-written docs
- Both deploy to separate Cloudflare Pages projects
- Raw
.mdfiles indocs/remain the source of truth for AI agents and Obsidian
Option B: Docusaurus
sv0-documentation/
├── docs/ # Internal docs (Obsidian vault)
├── internal-site/ # Docusaurus project
│ ├── docusaurus.config.js # CommonMark mode + obsidian-vault plugin
│ └── sidebars.js
├── customer-site/ # Docusaurus project
│ ├── docusaurus.config.js
│ ├── docs/ # Customer-facing .md files
│ └── sidebars.js
└── mkdocs.yml
- Similar structure but Docusaurus projects
- Multi-instance within a single site is also possible if internal docs become semi-public
Option C: Hybrid (Recommended Short-Term)
sv0-documentation/
├── docs/ # Internal docs — Obsidian vault, MkDocs/Zensical rendered
├── customer-site/ # Starlight project for customer docs
│ ├── src/content/docs/
│ ├── astro.config.mjs
│ └── package.json
└── mkdocs.yml # Internal site continues on MkDocs Material
- Internal docs stay on MkDocs Material (known, working, no migration risk)
- Customer-facing docs built fresh on Starlight (no migration, clean start)
- Migrate internal docs to Starlight later when starlight-obsidian and Zensical maturity are clearer
- Lowest risk, fastest time to customer-facing docs
7. Recommendation
Post-review note: The original version positioned Starlight as the likely single-framework end state. After review, we now treat customer-facing and internal docs as separate decisions with separate timelines.
Customer-Facing Docs: Prototype Both
Starlight (Astro) and Docusaurus 3 should be prototyped head-to-head on real content before a decision is made. Both pass all customer-facing requirements.
| Strength | Starlight | Docusaurus |
|---|---|---|
| Performance | Zero client JS, fastest loads | React SPA, 200-400KB bundle |
| CSS/theming | CSS variables + Tailwind CLI | Infima lock-in, Tailwind conflicts |
| Cloudflare Pages | First-class Astro adapter | Official guide, static output |
| Versioning | No built-in (community plugin) | Native, folder-based, mature |
| Ecosystem | Growing (50+ plugins) | Massive (1000+ plugins, Meta backing) |
| API docs | starlight-openapi plugin | Swagger UI, native MDX components |
| Risk | Pre-1.0, CSS specificity fights | Infima coupling, swizzle fragility |
VitePress is a credible fallback but adds Vue to our React/TS stack.
Not recommended for customer site: Nextra (MDX-primary, CF complexity), Mintlify (hosted-only, expensive), MkDocs Material (maintenance mode, navigation limitations).
Internal Docs: Stay on MkDocs, Gate Any Migration
MkDocs Material is the only framework proven against our actual vault (238 files, 446 wiki-links, active Dataview). Internal migration should not be committed to until explicit gates pass:
| Gate | Criteria |
|---|---|
| Wiki-link fidelity | All 446 [[wiki-link]] occurrences render correctly |
| Frontmatter handling | All custom fields (type, status, tags, source, priority, relates-to) preserved |
| Dataview parity | Equivalent query capability for type/tags/status browsing |
| Search/nav parity | Search quality and sidebar navigation at least equal to current |
| No frontmatter rewrites | Existing YAML frontmatter works without schema changes |
| Preview/deploy parity | CF Pages preview deploys work for internal site |
| Acceptable build time | Full vault builds in < 60 seconds |
Until these gates are met, internal docs remain on MkDocs Material.
Recommended Strategy
Phase 1 — Now: Keep internal docs on MkDocs Material. Prototype customer-facing docs in both Starlight and Docusaurus.
Phase 2 — After prototype: Choose the customer-facing framework based on real-content testing. Write ADR.
Phase 3 — Later (only if gates pass): Evaluate migrating internal docs. This is a separate decision, not an assumed outcome.
Stakeholder Review: The Case for Docusaurus
The following is a stakeholder counterpoint after reviewing the full 849-line research doc. The prototype bake-off is agreed, but Docusaurus should go in as co-equal, not runner-up.
While this document's technical analysis leans Starlight, stakeholder review identified four factors that tilt the customer-facing decision toward Docusaurus:
1. Stack alignment. The platform is React/TypeScript. Docusaurus lives in the same ecosystem. Custom components, landing pages, and theme modifications are written by people who already know React. Starlight adds Astro as a third framework (React for platform UI, Python for connectors, Astro for docs). Not disqualifying, but a real ongoing cost.
2. MCP as a product feature, not a technical detail. A CISO buying a security platform may want to connect their AI assistant to the vendor's docs. Docusaurus's docusaurus-plugin-mcp-server is a turnkey one-day implementation. On Starlight, the options are llms.txt (read-only, less interactive) or building a custom endpoint. For a company whose value prop is AI-assisted security operations, queryable docs are a product feature, not an afterthought. Section 9 acknowledges this but underweights it.
3. Maturity as a selling signal. Enterprise security buyers scrutinize vendor infrastructure. Docusaurus is Meta-backed, 63k stars, used by Supabase, Algolia, React Native — a reference list that builds credibility during sales cycles. Starlight at pre-1.0 and 8k stars doesn't send the same signal to a CISO evaluating the product. Actual stability may be fine, but optics matter in enterprise sales.
4. The Cloudflare migration argument has a conflict of interest. This doc cites "Cloudflare migrated from Docusaurus to Starlight" as a Starlight endorsement. Worth noting: Cloudflare is an Astro infrastructure partner. This makes them an invested party, not an independent reference.
Where Starlight genuinely wins (and where it doesn't matter for the customer site):
- Zero JS bundle — real for mobile, irrelevant for CISOs on corporate laptops
- CSS theming without Infima — real advantage, but manageable with Docusaurus swizzling
- starlight-obsidian plugin — best Obsidian integration, but the customer site has no vault dependency
Stakeholder conclusion: Run the bake-off as planned, but go in expecting Docusaurus to win on team familiarity and MCP. If Starlight loads noticeably better and themes more easily during testing, that changes the calculus. The MCP angle alone keeps Docusaurus firmly in contention.
8. Next Steps (Revised — Phased Plan)
Phase 1: Correct Research + Prototype (1 week)
Correct the research doc matrix(done — split into internal/customer, softened absolute calls)- Prototype bake-off: Build the same 5-page customer slice in both Starlight and Docusaurus
- Include: getting started, one product concept page, one API reference page, one integration guide, landing page
- Deploy both to Cloudflare Pages preview
- Small internal import test: Point starlight-obsidian at a 20-file subset of the real vault to test wiki-link/frontmatter handling (informational, not decision-driving)
Phase 2: Evaluate Prototypes (3 days)
Measure against these criteria on real content:
- Navigation and search quality
- Theming effort (dark mode, SecurityV0 branding, CISO aesthetics)
- Authoring friction (writing new pages, previewing locally)
- Cloudflare Pages deploy experience (build time, preview deploys)
- Redirect handling (old MkDocs URLs if needed)
- API reference path (OpenAPI rendering)
- Component customization ease
- Accessibility
Phase 3: Decide + ADR
- Choose customer-facing framework from prototype results
- Write ADR (
adr-NNN-documentation-framework.md) capturing the decision, prototype results, and rationale - Define content architecture for customer-facing site (pages, sections, navigation, information hierarchy)
Phase 4: Internal Docs (Deferred)
- Monitor Zensical maturity and starlight-obsidian stability
- Run full-vault gate test only when there is a reason to migrate (e.g., MkDocs becomes untenable, or customer framework proves excellent)
- Separate decision and ADR if/when internal migration is pursued
9. MCP, AI Agents, and Framework Tooling
Context: In the MCP (Model Context Protocol) era, documentation frameworks are increasingly evaluated not just for human readers but for AI agent consumption — both for authoring docs and for making published docs queryable by AI tools.
9.1 Docusaurus: MCP Plugin for Published Docs
Docusaurus has a purpose-built plugin — docusaurus-plugin-mcp-server — that turns your published documentation into an MCP-queryable endpoint:
- Build time: processes all rendered HTML, extracts content, converts to markdown, builds a FlexSearch index
- Runtime: exposes a stateless MCP JSON-RPC endpoint that AI agents can query
- Claude Code integration:
claude mcp add --transport http my-docs https://docs.example.com/mcp
This is a genuinely unique capability: customers or internal agents can query your published docs via MCP without needing repo access. For a security product where customers may want to reference docs from their own AI tools, this has real value.
Additionally, there are Claude Code skills for Docusaurus project management:
- Docusaurus Documentation Manager — Markdown formatting, MDX components, frontmatter, sidebar config
- Docusaurus Configuration Manager —
docusaurus.config.jsmanagement, plugin integration, validation
Docusaurus does not yet have an official "Build with AI" guide — this is at the feature request stage.
9.2 Starlight/Astro: Official MCP Server + llms.txt
Astro takes a different approach — instead of a plugin for your site, they provide AI tooling for building with the framework:
- Official Astro Docs MCP Server: maintained by the Astro team, uses kapa.ai API to index Astro/Starlight documentation. Claude Code can connect to get up-to-date framework docs while building your site.
- Official "Build with AI" guide: covers setup with Claude Code, VS Code Copilot, Windsurf, and Cursor.
- llms.txt generation: multiple plugins (astro-llms-txt, astro-llms-generate, @waldheimdev/astro-ai-llms-txt) auto-generate
/llms.txtand/llms-full.txtfiles — your entire docs in LLM-optimized markdown for AI consumption.
Claude Code skills for Starlight development:
- Astro & Starlight Development skill — implementation patterns, best practices for Starlight sites
- Publishing Astro Websites skill — comprehensive: SSG, Content Collections, Markdown/MDX, Pagefind, i18n, deployment
9.3 Comparison Matrix
| Capability | Docusaurus | Starlight/Astro | MkDocs Material |
|---|---|---|---|
| MCP server for YOUR published docs | Yes — docusaurus-plugin-mcp-server (turnkey) | No turnkey plugin — would need custom build | No |
| MCP server for framework docs | No official | Yes — official Astro Docs MCP | No |
| llms.txt auto-generation | No built-in | Yes — multiple plugins | No |
| Official "Build with AI" guide | Feature request stage | Yes — official guide | No |
| Claude Code skills | Doc manager + config manager | Starlight dev + publishing | None known |
| Raw .md readability by agents | Good (.md/.mdx in repo) | Excellent (.md in repo, no transform) | Excellent (.md in repo) |
| Automated doc generation | Claude Code + Docusaurus agent | Possible via Astro content collections | Possible via scripts |
9.4 Assessment: Does This Matter for Us?
For choosing the customer-facing framework: marginally.
- Claude Code already reads raw
.mdfiles from the repo — it doesn't need an MCP server to author or maintain docs. - The Claude Code skills for both frameworks are helpful but not critical. They assist with framework-specific config patterns, but Claude Code handles Markdown, frontmatter, and sidebar config without specialized skills.
- Both frameworks have comparable AI-assisted development stories.
The one scenario where it could matter:
Docusaurus's MCP plugin means our published customer docs could be queryable by AI agents without repo access. For a security product where customers and their AI tools may want to reference our docs programmatically, this is a real differentiator. If we build on Starlight, we'd need to either:
- Rely on llms.txt (simpler but less interactive than MCP)
- Build a custom MCP endpoint (more work)
- Wait for the ecosystem to catch up
Recommendation: This should be noted as a Docusaurus advantage in the prototype evaluation but should not be the deciding factor. The llms.txt approach on Starlight covers 80% of the AI consumption use case with less complexity.
Next Action
Status: research-complete. This document has been through initial research, Codex review, and stakeholder review. The research phase is closed.
Immediate next step: Run the prototype bake-off (Phase 1, Step 2 from Section 8).
- Build the same 5-page customer doc slice in both Starlight and Docusaurus
- Deploy both to Cloudflare Pages preview environments
- Evaluate against the criteria in Phase 2 (Section 8)
- Document results and write ADR
Owner: To be assigned when prototype work begins.
Depends on: No blockers. Research is sufficient to begin prototyping.
Decision output: ADR (adr-NNN-documentation-framework.md) after prototype evaluation.
Appendix: Sources
MkDocs Material / Zensical
- Insiders Now Free for Everyone
- Zensical Announcement
- Zensical GitHub
- Zensical Compatibility
- What MkDocs 2.0 Means
- mkdocs-obsidian-bridge
- mkdocs-wikilinks-plugin
Docusaurus
- Docusaurus Markdown Features
- Docusaurus Multi-Instance
- docusaurus-plugin-obsidian-vault
- Docusaurus CommonMark Discussion
- Cloudflare Pages Docusaurus Guide
Nextra
Starlight / Astro
- Starlight Documentation
- Starlight GitHub
- starlight-obsidian Plugin
- Astro Cloudflare Deployment
- Starlight Frontmatter Reference
- Multi-framework Docs with Starlight (Arcjet)
- Astro 2025 Year in Review
- Using Obsidian with Astro Starlight
Mintlify
VitePress
- VitePress Documentation
- VitePress GitHub
- markdown-it-wikilinks-plus
- Cloudflare Pages VitePress Guide
- VitePress Monorepo Discussion
Fumadocs
MCP, AI Agents, and Skills
- docusaurus-plugin-mcp-server
- Docusaurus MCP Plugin Discussion
- Docusaurus AI/LLM/MCP Feature Request
- Automated Docs with Claude Code + Docusaurus
- Docusaurus Documentation Manager Skill
- Astro Docs MCP Server
- Astro "Build with AI" Guide
- Astro llms.txt Plugin
- Astro LLM Integrations
- Astro & Starlight Development Skill
- Publishing Astro Websites Skill