Skip to main content

Docusaurus

note

You are reading this on Docusaurus. The configuration, sidebar structure, and MDX patterns used throughout this site are all live examples of what you can build.

What is Docusaurus​

Docusaurus is a React-based static site generator for documentation sites, maintained by Meta and a large open-source community. It is MIT licensed and currently at version 3.9.2. With ~1.5M weekly npm downloads and ~60k GitHub stars, it is one of the most widely adopted documentation frameworks in the JavaScript ecosystem.

Why we recommend it​

  • First-class versioning — snapshot a documentation version for each release and maintain multiple versions in parallel. This is the single most important differentiator over lighter-weight alternatives.
  • Swizzling — override or wrap any built-in React component (nav, footer, sidebar, etc.) without forking the theme. Gives teams surgical UI control at the component level.
  • MDX 3 — write JSX and React components directly in Markdown pages. Import data, embed interactive demos, and use Docusaurus admonitions (:::note, :::tip, :::caution, :::danger) out of the box.
  • Plugin architecture — official plugins for sitemap, PWA, Google Tag (GA4), and a documented API for building custom plugins.
  • Built-in blog — first-class blog section with author pages, tags, RSS/Atom feeds, and paginated archives. Runs alongside the docs section with no extra setup.
  • i18n — built-in localisation framework supporting RTL languages; translation files mirror the docs directory structure.
  • Search — Algolia DocSearch integration for production, plus @easyops-cn/docusaurus-search-local for zero-dependency offline search. The Aliz Web Hub uses the local search theme.

When to use​

  • Developer portals and internal knowledge bases
  • Product documentation sites that need multiple versioned releases maintained in parallel
  • Projects where a dedicated blog alongside the docs is desirable
  • Sites where fine-grained React-level control over the theme via swizzling is needed
  • Teams already working in the React ecosystem

When NOT to use​

  • Documentation embedded in an existing Astro project — use Astro Starlight instead
  • Projects with strict bundle-size or performance constraints where shipping the React runtime on every page is unacceptable
  • Simple single-version reference docs that need no versioning, blog, or heavy customisation — Astro Starlight is a leaner option

Resources​