Documentation sites in 2026: revisit Docusaurus, Material for MkDocs and Starlight before you move another product manual into a wiki

A product team ships a new release on Friday. On Monday a customer support engineer opens the user manual and finds screenshots from two versions ago, an install page that still mentions a removed flag, and a search box that cannot find the word the customer is typing. The manual lives in a wiki that only three people edit. Nobody reviewed the change, nobody can tell which page matches which release, and the developer who changed the behaviour never touched the docs.

Writing a page is easy. The hard part is keeping product documentation in step with the product: reviewed in the same pull request as the code, built for each release, searchable, translated where needed, and published to a site that customers can trust. That is the promise of docs-as-code, and it is why static documentation site generators still matter.

This post revisits three of them: Docusaurus, Material for MkDocs and Starlight. All three take Markdown from a Git repository and produce a static site you can host almost anywhere. They are not drop-in replacements for each other. Docusaurus is a React and MDX framework from Meta. Material for MkDocs is a theme and plugin set on top of the Python tool MkDocs, and in 2026 it is in its end-of-life phase, with its team building a successor called Zensical. Starlight is the official documentation framework of the Astro project. All three are MIT licensed.

A wiki is still the right home for internal, fast-changing team knowledge. For that side of the problem, see the earlier comparison of BookStack, Wiki.js and Outline. This post is about the other side: documentation that ships with a product and must match a release.

The short version

• Docusaurus: MIT licence, maintained by Meta Open Source. A Node.js static site generator built on React and MDX, with docs, blog and pages plugins, built-in versioned docs, built-in i18n and first-class Algolia DocSearch support. The current line is 3.10.x, and the team has said 3.10 is the last minor release of v3 before v4. Best fit for product teams that already work in React and want versioning and translation out of the box.
• Material for MkDocs: MIT licence, from the squidfunk team. A theme and plugin collection for MkDocs, a Python tool that builds sites from Markdown and a mkdocs.yml file. It has client-side search built in, versioning through the separate mike tool, and a very large user base. The project announced end of life on 5 May 2027, with critical fixes and security updates until then. Best fit today for teams already on it who need a calm migration plan, not for brand-new sites that want a long runway.
• Starlight: MIT licence, from the Astro project. A documentation framework built as an Astro integration, with Pagefind search by default, built-in i18n with fallback content and right-to-left support, and versioning through a plugin. Still on a 0.x version line. Best fit for teams that want a fast, mostly static docs site with little client-side JavaScript and are comfortable with the Astro and npm toolchain.

What job is actually being done

“We need a docs site” hides several jobs.

• Author in plain files. Write Markdown in the same repository as the code, so a reviewer sees code and docs in one pull request.
• Build and publish. Turn those files into a static site in CI, then host it on any web server, object store or static host.
• Version. Keep the docs for 2.x readable after 3.x ships, and let a reader switch between them.
• Search. Let a reader find a page by the word they know, not the word the writer chose.
• Translate. Serve the same manual in more than one language without letting untranslated pages break the site.
• Extend. Add API reference pages, diagrams, tabs, admonitions or custom components without forking the theme.

A wiki solves a different set of jobs: quick editing in the browser, permissions per space, and comments. Many teams need both. Problems start when the product manual, which needs versions and review, is kept in a tool built for quick edits.

Why revisit this in 2026

Three things changed.

First, the MkDocs ecosystem split. MkDocs 1.6.1, released on 30 August 2024 at 5:53 PM IST, is still the latest stable release of the mkdocs package on PyPI. Its original maintainer started a ground-up rewrite as MkDocs 2.0, and pre-releases appeared on PyPI from 29 August 2026, with 2.0.dev6 on 15 September 2026 at 4:38 PM IST. According to the Material for MkDocs team’s own analysis, MkDocs 2.0 drops the plugin system, changes the theming model, moves configuration from YAML to TOML and cannot build Material for MkDocs sites. Alongside it, community forks appeared, including ProperDocs, started by a former MkDocs maintainer, and MkDocs NG. A plain pip install mkdocs still gives you 1.6.1, so nothing breaks by itself, but the ground under every MkDocs site has moved.

Second, Material for MkDocs set an end date. The team behind it released Zensical, a new MIT-licensed generator with a Rust core that reads existing mkdocs.yml files, and moved Material for MkDocs into maintenance. In September 2026 they extended critical maintenance by six months, to 5 May 2027. Zensical 0.1.0 shipped on 5 November 2026 and entered a three-month beta. The team also launched Zensical Studio, a closed-source authoring application with free and paid editions, and Spark, a paid membership for support. The generator itself stays MIT.

Third, Astro changed hands. On 16 January 2026 the Astro Technology Company joined Cloudflare. Both sides stated that Astro stays MIT licensed, open to contributions and able to deploy to platforms other than Cloudflare. Starlight is part of the Astro project, so its future is now tied to that stewardship.

Docusaurus did not have a dramatic year, but it is at a turning point too: the 3.10 release notes say it is the last minor release of v3 and that it prepares sites for v4 through opt-in future flags.

Docusaurus

History and licence. Docusaurus was created at Facebook (now Meta) and is published under the MIT licence from the facebook/docusaurus repository. Version 2 rebuilt it around React and MDX, and version 3 moved to MDX v3, which is stricter about syntax than the old MDX v1.

Current versions (IST).

• 3.10.0 on 7 April 2026 at 7:58 PM IST, described by the team as the last v3 minor release.
• 3.10.1 on 30 April 2026 at 6:27 PM IST, a bundler bug fix.
• 3.10.2 on 11 July 2026 at 12:01 AM IST, a patch release with backported fixes.

What it gives you. A docs plugin with sidebars, a blog plugin, custom React pages, versioned docs through a CLI that snapshots the docs folder into versioned_docs, i18n with locale folders, and official support for Algolia DocSearch. For sites that are not eligible for the free hosted DocSearch, or that sit behind a firewall, the docs point to running your own crawler, Typesense DocSearch or community local search plugins.

Build performance. “Docusaurus Faster” swaps in Rspack, SWC and LightningCSS. In 3.10 it became stable under future.faster, it is already on for newly created v3 sites, and it will be the default in v4. The same release added an eager Git strategy that reads history in one git log call instead of one call per file, which the team says was a real bottleneck for large sites. Treat any speed figures as the project’s own measurements and time your own site before and after.

Operations. It is a Node.js and npm project, so the risk you manage is the dependency tree. The 3.10 notes spend real space on supply-chain security: npm Trusted Publishing for releases, a daily security workflow, and advice to use a lockfile and release cooldowns in your package manager. The team is also clear that their workflow does not protect your site; that is your job.

What to watch.

• v4 is coming. Turn on the v4 future flags one at a time in a branch, especially the stricter MDX one, because pages that relied on MDX v1 leniency may fail to build.
• The team recommends .mdx file extensions for MDX content, admonition titles in the :::note[Title] form and a new heading ID syntax. Old content keeps working in v3, but plan the cleanup.
• The versioning docs themselves warn that versioning increases build time and complexity, and suggest it only for docs that change a lot between versions. Take that advice seriously.
• Docs written as MDX with custom React components are less portable than plain Markdown. That is a feature when you need interactive pages and a cost when you migrate.

Material for MkDocs

History and licence. Material for MkDocs began as a theme for MkDocs and grew into a large set of features: navigation tabs, instant loading, built-in client-side search, social cards, a blog plugin, tags and many Markdown extensions through Python Markdown. It is MIT licensed. The team states that about 84,000 public GitHub repositories depend on it. Many features that were once only for paying sponsors were released to everyone over time.

Current versions (IST).

• 9.8.0 on 24 October 2026 at 3:19 PM IST, mainly a security release that raises dependency minimums and now requires Python 3.11 or newer.
• 9.8.1 on 7 November 2026 at 6:34 PM IST, with Docker image and build dependency updates.

Both release notes open with the same warning: end of life on 5 May 2027, with critical fixes and security updates until then, and a pointer to Zensical’s migration guide.

What it gives you. A mature, well-documented theme with search that runs in the browser, versioning through mike, which deploys each version into its own folder on a gh-pages branch and never rebuilds old versions, a language setting for UI strings, and a deep library of content features. For many Python projects it has been the default answer for years.

Operations. It is a Python package, usually pinned in requirements.txt with a few plugins. 9.8.0 removed mkdocs-rss-plugin and mkdocs-redirects from the recommended extra because their recent releases depend on ProperDocs, so if you rely on RSS or redirects, declare those plugins yourself. Check this before your next CI image rebuild, not after.

What to watch.

• The end-of-life date. After 5 May 2027 you should assume no more fixes. Put a migration decision on the calendar now.
• The MkDocs base. Pin mkdocs below 2.0 in your requirements so a future stable 2.0 cannot reach your build by accident, since it will not build this theme.
• The successor. Zensical reads mkdocs.yml, offers a classic theme variant that keeps the Material look, and reimplements many popular plugins natively instead of running MkDocs plugins. It is at 0.1.0 and in beta until about February 2027 by its own plan. Test your real site, including every plugin, before you commit.
• The forks. ProperDocs and MkDocs NG aim to keep MkDocs 1.x plugins and themes working. They are younger, smaller projects. If you choose one, you are choosing a new upstream, so look at its release history and maintainers first.
• Speed comparisons between these options exist, including a 1,000-page build table on the MkDocs NG site. Read that as one project’s own run on its own test, not as a neutral benchmark.

Starlight

History and licence. Starlight was first published to npm in May 2023 as @astrojs/starlight, and is MIT licensed in the withastro/starlight repository. It is an Astro integration, so a Starlight site is an Astro project with Markdown, MDX or Markdoc content in a content collection.

Current versions (IST).

• 0.42.0 on 2 September 2026 at 4:43 PM IST. It ships compiled JavaScript with type declarations instead of TypeScript source, uses the browser Popover API so the mobile menu works without JavaScript, and includes some potentially breaking markup changes for theme plugins and component overrides.
• 0.42.10 on 6 November 2026 at 11:43 PM IST, the latest patch at the time of writing, with a peer dependency on Astro 7.2.10 or newer in the 7.x line.

What it gives you. Pagefind full-text search by default, which builds a static index at build time and needs no external service. An official plugin swaps in Algolia DocSearch if you have access to it. Built-in i18n handles routing, a root locale without a path prefix, right-to-left languages and fallback content: if a French page is missing, readers see the default language page with a notice. Versioning is not built in; the plugin list points to the community starlight-versions plugin. The Starlight team says a typical Starlight site ships 3 to 13 times less JavaScript than comparable tools. That is the project’s own claim.

Operations. Like Docusaurus, it is a Node.js project with an npm dependency tree to keep tidy. Because it rides on Astro, an Astro major upgrade can arrive together with a Starlight minor. The project provides the @astrojs/upgrade tool for that, but you should still read the release notes.

What to watch.

• The 0.x version line. Minor releases can carry breaking changes, as 0.42.0 did for some overrides. Pin versions and upgrade on purpose.
• Versioning through a community plugin is a different promise from versioning built into the core. If several live versions are a hard requirement, test the plugin with your real structure.
• Stewardship. Astro’s statements after joining Cloudflare are reassuring, but they are statements. Watch the public roadmap and release rhythm, as you would with any project.

Side by side

Licence and stewardship

• Docusaurus: MIT, Meta Open Source.
• Material for MkDocs: MIT, squidfunk team; end of life on 5 May 2027. Zensical, its successor, is MIT, with optional paid products around it.
• Starlight: MIT, Astro project; the Astro company joined Cloudflare in January 2026.

Toolchain

• Docusaurus: Node.js, React, MDX v3.
• Material for MkDocs: Python 3.11 or newer for 9.8.x, MkDocs 1.x, Python Markdown.
• Starlight: Node.js, Astro 7.x, Markdown, MDX or Markdoc.

Versioned docs

• Docusaurus: built in, through docs:version snapshots in the repository.
• Material for MkDocs: through mike, which keeps each built version on a branch.
• Starlight: through the community starlight-versions plugin.

Search

• Docusaurus: Algolia DocSearch as the official option; Typesense or community local search otherwise.
• Material for MkDocs: built-in client-side search.
• Starlight: Pagefind by default; Algolia DocSearch through an official plugin.

Internationalisation

• Docusaurus: built in, with locale folders and translation files.
• Material for MkDocs: UI language setting built in; multi-language sites usually need extra plugins or separate builds.
• Starlight: built in, with root locale, right-to-left support and fallback pages.

Upgrade pressure in the next year

• Docusaurus: v4 migration, prepared through future flags.
• Material for MkDocs: a move to Zensical, a fork or another tool before May 2027.
• Starlight: 0.x minors and Astro majors.

How to choose

Start from your team and your content, not from a feature list.

• If your engineers already write React and you need several live versions and two or three languages, Docusaurus is the safest default. Plan for v4 now, while the flags are optional.
• If you already run Material for MkDocs and it works, do not panic and do not rush. Pin your versions, add the end date to your risk list, and test Zensical with your real mkdocs.yml during its beta. Decide by early 2027.
• If you are starting a new Python project docs site today, compare Zensical and Starlight honestly. Zensical keeps the familiar Markdown and YAML style but is young. Starlight is more mature as a docs framework but brings a Node.js toolchain.
• If page weight, accessibility and search without an external service matter most, Starlight with Pagefind is a strong fit.
• If your docs are mostly internal how-tos that change daily, you may not need a docs site generator at all. A wiki may be the honest answer.

Common mistakes

• Versioning by default. Every version you keep is another build to maintain. Version only the docs that genuinely differ between supported releases.
• Unpinned builds. A docs build that pulls the latest of everything will break on the day you need to publish a hotfix note. Pin generator, theme and plugins, and keep a lockfile.
• Treating the theme as the product. Your content in plain Markdown is the asset. Heavy custom components and shortcodes make the next migration expensive.
• Search as an afterthought. Check that search works for the words customers actually use, including product names and error codes, and that private sites do not rely on a hosted crawler that cannot reach them.
• Translating everything at once. Without fallback content, a half-translated locale shows broken links. Start with the pages people read most.
• Ignoring the MkDocs split. Assuming mkdocs will just keep working is the quiet risk of 2026. Make the choice deliberately.

A practical starting plan

1. List your current docs: where they live, who edits them, how many versions and languages you support, and which pages get the most traffic.
2. Move the product manual, not the team wiki, into the code repository as Markdown. Make docs changes part of the definition of done for a feature pull request.
3. Pick one generator using the questions above, and build a pilot with ten real pages, real search and one real version switch.
4. Pin everything, build in CI on every pull request, and fail the build on broken links.
5. Publish to a static host behind your normal domain, and keep the old manual read-only for one release cycle.
6. If you are on Material for MkDocs, open a branch that builds the same site with Zensical, compare navigation, search and plugins page by page, and record the gaps.
7. Review the choice after two releases, and again before May 2027 if MkDocs is anywhere in your stack.

Take a made-up example. A 40-person port logistics software company in Kochi publishes a user manual for its terminal booking product, an API guide for shipping lines, and a Malayalam quick-start for gate staff. The manual sits in a wiki, and support keeps sending customers screenshots from the old release. The team moves the manual and API guide into the product repository, picks Starlight because they want Pagefind search without an external service and fallback pages for the Malayalam locale, and adds the versions plugin only for the two releases customers still run. Their internal runbooks stay in the wiki. Nothing about this is exotic. It is mostly a decision about where each kind of document belongs.

No hands-on drill was run for this post. The versions, dates and claims come from the projects’ own release notes, documentation and announcements listed below.

Closing

Learn what each tool actually is: a React framework, a theme on a tool that is splitting, and an Astro integration. Unlearn the idea that the product manual belongs wherever editing is quickest. Re-learn docs-as-code as a review habit, not a tool choice. Practise by moving ten real pages and running one release with them. Apply the result to the documents your customers read, and leave the rest where they work best.

Sources

• Docusaurus releases: https://github.com/facebook/docusaurus/releases
• Docusaurus 3.10 release blog: https://docusaurus.io/blog/releases/3.10
• Docusaurus search docs: https://docusaurus.io/docs/search
• Docusaurus versioning docs: https://docusaurus.io/docs/versioning
• Material for MkDocs releases: https://github.com/squidfunk/mkdocs-material/releases
• Material for MkDocs versioning setup: https://squidfunk.github.io/mkdocs-material/setup/setting-up-versioning/
• What MkDocs 2.0 means for your documentation projects (Material for MkDocs blog): https://squidfunk.github.io/mkdocs-material/blog/2026/02/18/mkdocs-2.0/
• MkDocs on PyPI: https://pypi.org/project/mkdocs/
• MkDocs releases: https://github.com/mkdocs/mkdocs/releases
• Zensical November update: https://zensical.org/upcoming-changes/
• Zensical 0.1.0 release: https://github.com/zensical/zensical/releases/tag/v0.1.0
• Zensical MkDocs migration guide: https://zensical.org/docs/compatibility/mkdocs/migration/
• ProperDocs releases: https://github.com/ProperDocs/properdocs/releases
• MkDocs NG comparison page: https://mkdocs-ng.org/about/comparison/
• Starlight releases: https://github.com/withastro/starlight/releases
• Starlight 0.42 announcement: https://astro.build/blog/starlight-042/
• Starlight site search guide: https://starlight.astro.build/guides/site-search/
• Starlight i18n guide: https://starlight.astro.build/guides/i18n/
• Starlight plugins and integrations: https://starlight.astro.build/resources/plugins/
• The Astro Technology Company joins Cloudflare: https://astro.build/blog/joining-cloudflare/
• Astro is joining Cloudflare (Cloudflare blog): https://blog.cloudflare.com/astro-joins-cloudflare/