Introduction to Docusaurus

Docusaurus is an open-source static site generator built by Meta for documentation-heavy products. It renders to plain HTML, CSS, and JavaScript at build time, so the result can be hosted on any static host or object storage, and it is fast by default because a reader pays for the bytes of a page rather than for a rendering server. The first public release was an early React-based tool for versioned documentation; the second major generation was a full rewrite that kept the React component model but replaced the internals, and the current 3.x line continues that model with MDX-based content, a plugin API, and a theme system that is designed to be extended rather than replaced.

The tool is built around a simple pipeline. A set of content plugins reads folders of Markdown and MDX files and turns them into routes. A theme provides the React components that render those routes — the navbar, the sidebar, the documentation layout, the blog list, the footer. The surrounding application glues the two together with client-side routing, the search integration, and the handful of interactive pieces a documentation site needs. A single configuration file names the plugins, selects the themes, and supplies the theme options, which is why that file is where nearly all of your time will go.

LayerResponsibilityExamples
Content pluginsRead a source folder, validate frontmatter, emit routes and metadatadocusaurus-plugin-content-docs, docusaurus-plugin-content-blog, docusaurus-plugin-content-pages
ThemesProvide the React components and styling that render those routes@docusaurus/theme-classic, @docusaurus/theme-search-algolia
ApplicationClient-side routing, search, and the glue between plugins and themesThe generated app in docusaurus.config.js

Two design decisions explain most of what follows. The first is MDX. Because the content format is MDX rather than plain Markdown, a document is a React component tree, not just a string of text. You can import a chart, a pricing table, or a live demo at the top of a file and use it inline, and the file still renders perfectly on the server because MDX components are ordinary React components. The second is the folder convention. A file’s path, its frontmatter, and the sidebars file together determine its URL, its position in the navigation, and its neighbors, so reorganizing a documentation set is a matter of moving files and editing one JavaScript file.

A minimal configuration looks like this:

// docusaurus.config.js
/** @type {import('@docusaurus/types').Config} */
const config = {
  title: 'Acme Docs',
  url: 'https://docs.acme.dev',
  baseUrl: '/',
  onBrokenLinks: 'throw',
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'zh-cn'],
  },
  presets: [
    [
      'classic',
      {
        docs: {
          routeBasePath: 'docs',
          sidebarPath: require.resolve('./sidebars.js'),
        },
        blog: {
          routeBasePath: 'blog',
          blogTitle: 'Acme Blog',
        },
      },
    ],
  ],
  themeConfig: {
    navbar: {
      title: 'Acme',
      items: [
        { type: 'docSidebar', sidebarId: 'docs', position: 'left', label: 'Docs' },
        { to: '/blog', label: 'Blog', position: 'left' },
      ],
    },
    footer: {
      style: 'dark',
      copyright: `Acme, ${new Date().getFullYear()}`,
    },
  },
};

module.exports = config;

Everything the tool offers beyond that skeleton exists to remove a specific kind of friction. Documentation changes are frequently accompanied by code changes, so a live code block that executes a snippet in the browser is available as an optional theme. Reference material ages, so the version system snapshots the entire docs folder into a numbered directory and keeps the old one online. Product teams publish release notes, so a blog plugin with authors, tags, pagination, and an RSS feed is included in the same preset. Non-English audiences are the norm rather than the exception, so the translation workflow and the locale-aware routes are built in. And because a stale link in a reference manual is a real cost, the build can be configured to fail when a link does not resolve.

The features that come with the classic preset cover most projects:

CapabilityWhere it livesWhat it gives you
MDX authoringdocs/, blog/, src/pages/Markdown plus React components in one file
Versioningdocusaurus docs:versionArchived snapshots of the docs at a release boundary
Blogdocusaurus-plugin-content-blogAuthors, tags, pagination, RSS
SearchAlgolia theme or a local pluginIndexed, typo-tolerant full-text search
Internationalizationi18n plus docusaurus write-translationsLocale-prefixed routes and translated strings
Live code blocks@docusaurus/theme-live-codeblockRunnable React examples embedded in a page
Diagrams@docusaurus/theme-mermaidMermaid-rendered flowcharts and sequence diagrams
Broken link checkingonBrokenLinksThe build fails instead of shipping a dead link

Docusaurus is not the right tool for every documentation set. If you have a small README and no product surface, a static site generator is unnecessary overhead. If your content is genuinely dynamic — user-specific pages, live account data, a catalogue that changes per request — a static build is the wrong shape, and a framework with a server runtime will serve you better. Docusaurus also asks you to accept React and a JavaScript configuration file, which is a real cost if your team is otherwise a Python or a Rust shop, and its build times are heavier than those of the lightest generators because it compiles a full React application.

Where it does fit, the trade is usually obvious. A company shipping a product with several released versions, a changelog, a public landing page, and a React frontend will get all of that from one configuration file and one deployment, with search, translations, and version switching handled rather than bolted on. The chapters that follow make that concrete: first a working project, then the content model, then the MDX and component model, then the extension points.

Found an issue with this content?

Tell us what could be improved.