Docusaurus Overview

This content was generated with the assistance of AI and should be verified against the official documentation of each tool before being relied on in production.

This section’s bibliography lists the reference material consulted while preparing these pages.

This page was written against Docusaurus 3.10.2 (npm package @docusaurus/core, released 2026-07-10) and checked on 2026-10-26. Docusaurus 3.10 is the last minor release of the 3.x line; version 4 exists only as canary builds. Docusaurus 3.9 and later need Node.js 20 or newer, and the site generated by the 3.10.2 template depends on React 19. The explanations use the same running example as the rest of this section, Pocket Units, a small units-conversion library with C# and Python sources, documented here as a Docusaurus site with docs, a blog and versioned docs.

What Docusaurus is

Docusaurus is a static site generator built mainly for documentation. It is developed under the Meta open source umbrella (the official site carries a Meta Platforms copyright notice), its code is published on GitHub and the core package declares the MIT licence. It can also produce blogs, product sites and landing pages, because every page of the output is a React page and the documentation, blog and free-form pages are provided by separate plugins.

The key characteristics are:

  • React underneath. The site is a React application. Custom pages are React components, and the look of the site comes from a theme made of React components that you can replace one by one (swizzling).

  • MDX content. Documents are written in Markdown with MDX, which allows importing React components and writing JSX inside the text. The next section shows an example.

  • Static HTML plus a single-page application. The build writes one HTML file per route, which is good for search engines and for first load, and then the browser loads JavaScript that takes over navigation, so moving between pages does not reload the site.

  • Built-in features for documentation sites. Versioned documentation, internationalization (i18n), a blog, sidebars, search integration, light and dark themes and a plugin system.

  • Fast development loop. The development server reloads content and code as you edit.

Compared with the other tools of this section, Docusaurus has one configuration file written in TypeScript or JavaScript (docusaurus.config.ts) instead of a YAML playbook or a TOML file, and its source of truth is a single website project, not several repositories aggregated at build time.

MDX and React

MDX is Markdown that is compiled to JavaScript. A document can import a component and use it as an HTML-like tag. In the Pocket Units example a small React component lets readers try a conversion on the documentation page itself.

src/components/Converter.tsx
import {useState} from 'react';

export default function Converter(): React.JSX.Element {
  const [meters, setMeters] = useState(1);
  return (
    <p>
      <input type="number" value={meters} onChange={(e) => setMeters(Number(e.target.value))} />
      {' m = '}
      {(meters * 3.28084).toFixed(3)} ft
    </p>
  );
}

Source: Docusaurus docs: MDX and React

docs/pocket-units.mdx
---
sidebar_position: 0
---

import Converter from '@site/src/components/Converter';

# Pocket Units

Convert metres to feet:

<Converter />

Source: Docusaurus docs: MDX and React

This example was built in a site generated with create-docusaurus 3.10.2 (the classic template with TypeScript): npx tsc reported no errors and npm run build ended with the line below. In the generated file build/docs/pocket-units/index.html the component was already rendered as plain HTML, before any JavaScript runs.

[SUCCESS] Generated static files in "build".
<input type=number value=1 />
m = <!-- -->3.281<!-- --> ft

Strictness is the price of MDX. Version 3 of MDX (used by Docusaurus 3) fails the build on an invalid JSX tag or on a stray curly brace in prose, so text such as a bare < or an unescaped brace must be escaped or put in code. The page MDX and React Components covers this, together with the markdown.format setting that can treat files as plain CommonMark (md), as MDX (mdx, the default) or choose by file extension (detect).

The classic preset

Docusaurus is built from plugins and themes, and a preset is a bundle of them. Nearly every new site uses the classic preset, which is what create-docusaurus generates and what the 3.10.2 package @docusaurus/preset-classic declares as dependencies. Its package depends on the following packages, which were read from the installed copy:

Package Role

@docusaurus/plugin-content-docs

The documentation: versioned docs, sidebars, previous and next links.

@docusaurus/plugin-content-blog

The blog: posts, tags, authors, archive and RSS or Atom feeds.

@docusaurus/plugin-content-pages

Free-form pages from src/pages, written in React or in Markdown.

@docusaurus/theme-classic

The default theme: layout, navbar, footer, dark mode, code blocks, tabs, admonitions.

@docusaurus/theme-search-algolia

The Algolia DocSearch integration, active only when themeConfig.algolia is configured.

@docusaurus/plugin-sitemap

The sitemap.xml file.

@docusaurus/plugin-svgr

Importing SVG files as React components.

@docusaurus/plugin-css-cascade-layers

Support for CSS cascade layers, used by the Docusaurus 4 readiness flag useCssCascadeLayers.

@docusaurus/plugin-debug

The development-only /__docusaurus/debug pages.

@docusaurus/plugin-google-analytics, @docusaurus/plugin-google-gtag, @docusaurus/plugin-google-tag-manager

Optional analytics integrations, enabled by their option in the preset or themeConfig.

Source: Docusaurus docs: Using plugins

A Pocket Units site uses the preset like this (shortened to the relevant lines of the file that create-docusaurus writes):

docusaurus.config.ts
import type {Config} from '@docusaurus/types';
import type * as Preset from '@docusaurus/preset-classic';

const config: Config = {
  title: 'Pocket Units',
  tagline: 'Unit conversion for C# and Python',
  future: {
    v4: true,
  },
  url: 'https://your-docusaurus-site.example.com',
  baseUrl: '/',
  onBrokenLinks: 'throw',
  presets: [
    [
      'classic',
      {
        docs: {sidebarPath: './sidebars.ts'},
        blog: {showReadingTime: true},
        theme: {customCss: './src/css/custom.css'},
      } satisfies Preset.Options,
    ],
  ],
};

export default config;

Source: Docusaurus docs: docusaurus.config.js

The generated file already contains future: { v4: true } and onBrokenLinks: 'throw'; the 3.10.2 template also depends on @docusaurus/faster. The title and tagline above are Pocket Units values replacing the template defaults. Every key is explained on Configuration.

How a Docusaurus build works

docusaurus build runs the plugins, bundles the site with webpack, or with Rspack when the Docusaurus Faster flags are enabled, and then renders every route to HTML. The rendering step is static site generation (SSG): the React components are executed once in Node.js for each route, and the resulting markup is written to a file. At run time the browser shows that HTML immediately, downloads the JavaScript bundles listed in the page and hydrates the markup, which means React attaches event handlers to the existing elements instead of creating them again.

flowchart LR A["Content
docs, blog, pages
Markdown and MDX"] --> B["Plugins
docs, blog, pages,
sitemap, search"] C["Config
docusaurus.config.ts
sidebars.ts"] --> B B --> D["Routes and data
one route per page"] E["Theme and components
React, CSS"] --> F D --> F["Bundle
webpack or Rspack"] F --> G["React SSG
render each route in Node.js"] G --> H["Static HTML
build folder"] H --> I["Browser
shows HTML, loads JS,
hydrates as an SPA"]

Figure: the Docusaurus build. Markdown and MDX content is handed to the plugins, which create routes; the bundler combines them with the theme, and React renders each route to a static HTML file that the browser later hydrates.

The output of npm run build in the checked site is a plain folder that any static host can serve. These are the entries found at the top of build/:

404.html
assets/        (hashed JavaScript and CSS bundles)
blog/          (posts, tags, authors, archive, atom.xml and rss.xml)
docs/          (one folder with index.html per document)
img/
index.html
markdown-page/
sitemap.xml
.nojekyll

Source: Docusaurus docs: Deployment

The development server (npm run start) does not use this pipeline: it serves the site without static rendering and reloads changes. The commands are listed on CLI and TypeScript.

Who uses Docusaurus

The official showcase lists 274 sites that people build with Docusaurus (count read on 2026-10-26). The entries marked as favourites include Algolia DocSearch, Hasura, Ionic, Jest, React Native, Refine, Relay, Verdaccio and WebdriverIO, and the list also contains projects such as Redux, Tauri, pnpm, Metro and Gulp. The showcase is self-service, so it shows adoption, not an audited list.

Some figures taken on 2026-10-26 give a sense of size: the repository has about 66,600 GitHub stars and about 10,100 forks, and the @docusaurus/core package had roughly 900,000 npm downloads in the week of 2026-10-16 to 2026-10-22. Stack Overflow carries about 515 questions under the docusaurus tag.

When to choose Docusaurus

Choose Docusaurus when:

  • your team knows React and wants to add interactive components to documentation, or to build a landing page and the docs with the same technology;

  • you want one site that combines documentation, a blog and free-form pages, with versioned docs and translations out of the box;

  • you document a single product or monorepo and the content lives in one project;

  • you want a large plugin and theme ecosystem and the option to override any theme component.

Consider the other tools of this section when:

  • the content is spread over many repositories that must be aggregated at build time, with versions taken from git branches: Antora;

  • the project is a Python project written in Markdown with API reference generated from docstrings: Zensical;

  • the main need is API reference generated from .NET assemblies and XML comments: DocFX.

The trade-offs of Docusaurus are the Node.js and React toolchain (a docs-only contributor edits Markdown but the project is a JavaScript project), the MDX strictness described above, and a major version change ahead: the project has announced that 3.10 is the last 3.x minor and offers future flags to prepare for version 4, covered on Docusaurus Faster and v4 Readiness. OpenAPI documentation is not part of Docusaurus itself: it comes from a community plugin, see OpenAPI Docs. A side-by-side view of all four tools is in Comparison.

Subsection map

The Docusaurus subsection has the following pages.

Page Covers

Installation and Project Structure

Creating a site, the folders and the npm scripts.

Configuration

docusaurus.config.ts: metadata, url and baseUrl, presets, themeConfig, markdown, future.

Docs and Front Matter

The docs plugin, ids, slugs and front matter fields.

Sidebars

Item types, categories and autogenerated sidebars.

Blog and Pages

Posts, authors, tags, feeds and pages in src/pages.

MDX and React Components

JSX in Markdown, imports, MDXComponents and MDX strictness.

Markdown Features

Admonitions, code blocks, tabs, links and head metadata.

Diagrams and Math

Mermaid, ELK layout, KaTeX.

Versioning

Version snapshots and the version dropdown.

Internationalization

Locales, translations and per-locale URLs.

Search

Algolia DocSearch, Typesense and local search.

Styling, Theming and Swizzling

Infima, CSS variables, dark mode and swizzling.

Plugins and Presets

Using and writing plugins, remark and rehype plugins.

SEO and Static Assets

Metadata, sitemap, robots and the static folder.

Deployment

GitHub Pages, Netlify, Vercel, trailingSlash.

CLI and TypeScript

Every CLI command and TypeScript support.

Docusaurus Faster and v4 Readiness

future.faster, future.v4, syntax being phased out and migration.

OpenAPI Docs

The community OpenAPI plugin.

Version notes

  • Docusaurus 3.9 dropped Node.js 18 (the minimum is Node.js 20), moved to DocSearch v4 with an opt-in Ask AI feature, added per-locale url and baseUrl, and added Mermaid ELK layout.

  • Docusaurus 3.10 added TypeScript 6 support and made Docusaurus Faster stable, with the option key renamed from future.experimental_faster to future.faster.

  • The Algolia theme of 3.10.2 declares @docsearch/react as ^3.9.0 || ^4.3.2, and the installed copy in the checked site was 4.7.1. DocSearch v5 exists, but this theme release does not use it.

References