Docusaurus

Docusaurus is an open-source static site generator built by Meta that turns Markdown and MDX content into fast, production-ready documentation websites. It bundles routing, theming, versioning, search, and internationalization behind a plugin-and-preset architecture, so teams can focus on writing content instead of wiring up a build pipeline.

The @docusaurus/core package is the engine at the center of that ecosystem: it owns the CLI, the dev server, the static-site-generation pipeline, and the webpack/SSR build, orchestrating the plugins, themes, and presets that render the final site.

What You Get

• A CLI for developing, building, deploying, and swizzling your documentation site
• A hot-reloading development server with fast refresh for content and components
• A static-site-generation pipeline that pre-renders routes to HTML with client-side hydration
• A plugin, preset, and theme system for docs, blogs, versioning, search, and i18n
• First-class MDX support so you can embed React components directly in Markdown

Common Use Cases

• Building and hosting open-source project documentation
• Publishing versioned API and product documentation
• Running a company engineering blog or changelog alongside docs
• Creating localized, multi-language documentation sites
• Standing up a marketing or landing site backed by Markdown content

Under The Hood

Architecture — The core boots from the bin/docusaurus.mjs entry point into a Commander-based CLI (src/commands/cli.ts) that dispatches to start, build, deploy, serve, swizzle, and translation commands. src/server loads and validates docusaurus.config, resolves the plugin/preset/theme graph, and runs each plugin’s lifecycle (loadContent -> contentLoaded -> route creation), emitting generated code via src/server/codegen. The src/ssg pipeline then statically renders every route to HTML, while src/webpack builds separate client and server bundles that hydrate on the browser; src/client supplies the runtime, router, and theme fallbacks.

Tech Stack — Written in TypeScript (~96% of the repo) targeting Node.js, using React 18/19 for rendering, webpack 5 for bundling, and MDX for content compilation. Core dependencies include Commander for the CLI, react-router for routing, react-helmet-async for head management, boxen/chalk/cli-table3 for terminal output, eta for templating, and fs-extra for filesystem work. The repo is a pnpm + Lerna monorepo of ~40 scoped @docusaurus/* packages.

Code Quality — Strong. The monorepo carries roughly 185 test files exercised with Vitest, alongside strict TypeScript configs, ESLint, Prettier, and Argos visual regression testing. Core logic is organized into cohesive server, ssg, webpack, babel, and client layers with __tests__ directories co-located throughout, and typed public contracts live in the dedicated @docusaurus/types package.

API Design — The user-facing surface is deliberately small: most projects only touch docusaurus.config.js, the CLI, and content files, with presets bundling sensible defaults so a new site works out of the box. Plugin and theme authors get a well-documented lifecycle API and a swizzle command for safely ejecting and customizing theme components. Documentation is extensive and versioned on docusaurus.io, which keeps the learning curve gentle for site authors even though the internal build is sophisticated.