Choosing a Documentation Platform

Purpose

Several projects I am running will need their own dedicated documentation sites. The first is the Digital Solution Lifecycle Model — a structured framework for designing and operating digital solutions. The second is its companion tooling. Others will follow.

Rather than make this decision separately for each project, I wanted to establish a platform approach I could reuse: fast, accessible, versioned, and maintainable over the long term. The choice of platform is more than a hosting decision. It determines how content is written, how readers navigate it, whether historical versions stay accessible, and how much time I spend maintaining infrastructure rather than writing.

Requirements

One constraint applies before any of the others: I am looking for a ready-made platform, not a framework to build upon. The time should go into writing documentation, not engineering the site it runs on.

The Contenders

Before comparing features, I mapped the landscape by the framework or language each option is built on. That grouping shapes what comes for free, what the surrounding ecosystem looks like, and how well each option fits with tools I already work with. This is not an exhaustive survey — platforms like Jekyll, Eleventy, and Hexo are not covered here. I am familiar with them but did not find them offering meaningful advantages over the options below for my specific requirements.

React

React is the most widely adopted JavaScript framework and the foundation for several mature documentation platforms.

Vue

Vue’s documentation ecosystem is anchored by VitePress, which is the official documentation tool for the Vue framework itself and many other major open-source projects.

Astro

Astro’s documentation ecosystem is anchored by Starlight, which is built specifically on top of the framework. I already work with Astro, which lowers the starting cost considerably.

Svelte

The Svelte documentation ecosystem is thinner than the JavaScript-first alternatives. Kit-docs is the most established ready-made option, positioned as a VitePress equivalent for Svelte.

Hugo

Hugo is a Go-based static site generator rather than a JavaScript framework. It is one of the fastest build tools available and has a mature ecosystem of documentation themes.

Python

MkDocs is a Python-based static site generator with a large ecosystem of documentation-focused plugins. Material for MkDocs is its most widely used theme and has grown into a comprehensive documentation platform in its own right.

Antora

Antora is a dedicated documentation site generator built in Node.js, designed from the ground up for versioned, multi-repository documentation. It is the most opinionated option in this comparison — its native content format is AsciiDoc rather than Markdown, which means adopting a different authoring toolchain entirely.

Working Through the Contenders

With the landscape mapped, I scored each contender against the four requirement areas. The goal was not to pick a winner but to make the trade-offs visible before the analysis begins.

Legend: ✅ Strong built-in support or straightforward configuration · ⚠️ Requires an extension, theme, or custom implementation · ❌ Unsupported or impractical

Hosting, Performance, and Authoring

Documentation and Versioning

Search, Content Features, and SEO

Ecosystem and Long-Term Viability

First cut — options that do not stand on their own

Running the requirements across the four tables quickly separated the field. Some gaps are not missing features that can be added — they are structural mismatches with what I need.

Nuxt Content is a content layer for Nuxt, not a documentation platform. It scores ⚠️ on nearly every documentation-specific criterion. I would need to assemble navigation, versioning, search, and RSS independently — more work than a custom build, without the payoff.

Nextra sits in an awkward middle position. It is less opinionated than Docusaurus but does not bring built-in versioning, blogging, or a strong ecosystem. It would add Next.js overhead without giving me what Docusaurus gives me.

Kit-docs is the main ready-made option in the Svelte ecosystem. Its ecosystem scores tell the story: ⚠️ on maintenance, community, and stability across the board. For a long-running documentation platform, ecosystem health is not a nice-to-have — it determines whether the platform is still viable in two years. Kit-docs does not clear that bar.

Material for MkDocs is a capable platform, but it entered maintenance mode in November 2025 — no new features, critical fixes only for at least twelve months — as its author shifted focus to a successor project called Zensical. Long-term viability is now an open question, and the Python dependency chain would add complexity I would rather avoid in any case.

Hugo Book is the weaker of the two ready-made Hugo options. It has a smaller community and less active development than Doks, without offering anything that compensates for those gaps. It does not survive this stage.

Doks is technically strong and its Hugo foundation produces extremely fast builds. However, the community is smaller than the JavaScript-based alternatives, there is no ready-made versioning solution for Hugo documentation sites, and I would need to build or maintain that myself.

Antora has arguably the strongest built-in versioning of any option on the list, and its multi-repository content aggregation is genuinely powerful for large documentation projects. However, it is a documentation-only platform — I cannot add a blog to it in any practical way. One of my hard requirements is to host both documentation and editorial content on the same site, and that eliminates Antora here regardless of how strong its versioning is.

That leaves three options: Docusaurus, VitePress, and Starlight.

Second cut — versioning as the deciding factor

Documentation versioning with permanent historical URLs and automatic old-version warnings is my hardest requirement. This is where the field narrows sharply.

Of the remaining options, only Docusaurus provides formal versioning out of the box. For VitePress and Starlight I would need a plugin or a custom content structure to achieve the same.

VitePress is excellent as a lightweight documentation site but was designed for single-version technical documentation. Blogging is not a first-class feature either, which conflicts with my requirement to host documentation and editorial content on the same site. The table scores for VitePress and Starlight look similar on these two points — both show ⚠️ for versioning and blogging — but what ⚠️ means differs. For Starlight, both gaps are covered by actively maintained plugins from the same author (starlight-versions and starlight-blog). For VitePress, a blog requires a fully custom implementation and versioning is an unsupported custom content structure with no equivalent plugin. The toolchain also differs: Starlight runs on Astro, which I already work with; VitePress is Vue.

The finalists

Two options survived both cuts. They approach the core trade-off differently: one with versioning built into the platform itself, one that asks me to rely on a community plugin for the hardest requirement but offers everything else I need without ceremony.

Docusaurus makes sense if I want versioning to be a core platform feature backed by a major organisation — handled entirely out of the box, with no community plugin dependencies for the requirement that matters most. The trade-offs are a larger React client-side footprint, local search requiring a plugin, and tighter coupling to MDX conventions.

Starlight makes sense if the priority is getting productive quickly on familiar ground. The toolchain is one I already work with, the defaults cover the most important features, and versioning — while not built-in — is an achievable extension through an actively maintained community plugin.

With two options left, the decision comes down to specifics.

Docusaurus’s extra plugin count is lower but that does not reflect the full picture: its three extra packages cover search and diagrams — well-understood, stable add-ons. Starlight’s five to six extra plugins include starlight-versions, which covers the single most important requirement as a community dependency rather than a core platform feature. That is the key trade-off.

Verdict

Starlight. The toolchain is already familiar, so there is no new ecosystem to learn before the first page goes live. The defaults are strong: search, navigation, SEO, and broken link checking are all built in. The two community dependencies on the critical path are starlight-versions and starlight-blog — both actively maintained and well-documented by the same author. Less to configure, less to maintain, more time to write.

Docusaurus was the runner-up, and not an easy one to set aside. Built-in versioning with no community plugin on the critical path, backed by Meta, battle-tested across thousands of projects. But the trade-offs — a heavier React footprint, a new ecosystem to learn, tighter coupling to MDX conventions — outweigh the single advantage of platform-level versioning certainty. The goal is to publish and grow these projects, not to maintain the platforms they run on.

The Plan

Day one

Core: @astrojs/starlight on a new Astro project

Each documentation site — the Model, the tooling, future projects — will be a separate Cloudflare Pages project, but they all share the same toolchain, conventions, and deployment patterns.

Built into Starlight — no extra installation:

• Sidebar navigation, breadcrumbs, and previous/next page links
• Local search powered by Pagefind — fully static, no external service, generated at build time
• Accessible defaults, dark mode, and responsive layout
• SEO, canonical URLs, and OpenGraph metadata
• Broken link detection at build time

Additional packages:

• Mermaid and PlantUML diagrams — rendered externally and embedded as static images; no build-time browser or server dependency needed
• @astrojs/sitemap — XML sitemap; official Astro integration

Deployment: New Cloudflare Pages project. Most _headers and _redirects patterns used on this site carry over, with some trimming for things specific to this site.

Later

Blog and versioning are requirements, but not day-one requirements. The first version of any new documentation site does not need them to be useful — it needs to be written, structured, and published. Both can be added incrementally once the content is stable enough to warrant them.

Blog — add when editorial content is ready:

• starlight-blog — blog section with RSS feed integrated into the Starlight layout; community plugin maintained by HiDeoo
• @astrojs/rss — RSS feed generation; official Astro integration

Versioning — add when the project has its first stable release:

• starlight-versions — documentation versioning with a version selector, old-version banner, and permanent versioned URLs; community plugin maintained by the same author

Deferring the versioning plugin has a practical benefit: by the time versioning becomes necessary, the plugin will have had more time to mature and the content structure of the site will be stable enough to introduce it cleanly.