// the take
Docusaurus is Meta's static site generator for documentation and project websites, built on React and MDX. It's aimed at open-source maintainers and companies who want a docs site with versioning, i18n, and a blog without hand-rolling one.
MDX lets you drop live React components into markdown docs, which is genuinely useful for interactive examples rather than just syntax-highlighted code blocks. Docs versioning and the swizzling mechanism (ejecting a theme component to customize it without forking the whole theme) are both well thought out. It's used across thousands of real OSS projects at Meta's own scale, so the rough edges in routing, build caching, and SEO metadata generation have mostly been found and fixed already.
Build times degrade noticeably on large doc sets (thousands of pages) since it still bundles through webpack/rspack rather than doing true incremental builds. Swizzled components are tied to internal theme internals, not a stable public API, so they can silently break on a Docusaurus version bump. It's a full React app under the hood, so you're paying for client-side hydration and a heavier toolchain even for a simple docs site — if you just want markdown-to-HTML, this is a lot of machinery. Multi-locale plus multi-version configuration gets complicated fast, and debugging why a given locale/version combination isn't resolving the way you expect is a common pain point.
We read the README, the directory tree and a key source file in October 2026. Nobody pays to be listed. How we judge →