Overview

Docusaurus is Meta’s battle-tested documentation framework used by projects like React, Jest, Redux, and Prettier. It turns Markdown/MDX files into a fast, SEO-optimized docs site with features teams actually need: versioning for multiple release branches, i18n for translated docs, and Algolia search.

Quick Start

npx create-docusaurus@latest my-docs classic --typescript
cd my-docs
npm start

Configuration

// docusaurus.config.ts
import type { Config } from '@docusaurus/types';

const config: Config = {
  title: 'My Project',
  tagline: 'Documentation',
  url: 'https://docs.myproject.com',
  baseUrl: '/',

  presets: [
    ['classic', {
      docs: {
        sidebarPath: './sidebars.ts',
        editUrl: 'https://github.com/org/repo/tree/main/',
        versions: {
          current: { label: '2.0.0-beta' },
        },
      },
      blog: { showReadingTime: true },
      theme: { customCss: './src/css/custom.css' },
    }],
  ],

  themeConfig: {
    algolia: {
      appId: 'YOUR_APP_ID',
      apiKey: 'YOUR_SEARCH_API_KEY',
      indexName: 'my-project',
    },
  },
};

export default config;

MDX with Components

---
title: API Reference
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import ApiExample from '@site/src/components/ApiExample';

## Authentication

<Tabs>
  <TabItem value="bearer" label="Bearer Token">
    ```http
    Authorization: Bearer <token>
    ```
  </TabItem>
  <TabItem value="apikey" label="API Key">
    ```http
    X-API-Key: <your-key>
    ```
  </TabItem>
</Tabs>

<ApiExample endpoint="/users" method="GET" />

Versioning

# Create a new docs version snapshot
npm run docusaurus docs:version 1.0.0

# Resulting structure:
# versioned_docs/version-1.0.0/   ← snapshot
# docs/                            ← next (current)

Deployment

# GitHub Pages
npm run build
npm run deploy  # Uses gh-pages branch

# Vercel: zero config — auto-detects Docusaurus
# Set output directory to: build

Tips & Best Practices

Use admonitions for callouts, not raw HTML. Docusaurus renders :::note, :::warning, :::tip, :::danger, and :::info blocks natively with correct styling in both light and dark modes. Raw <div> callouts break when you switch themes or upgrade Docusaurus versions.
Keep sidebars auto-generated for simple sites, explicit for complex ones. The auto-generated sidebar (sidebarPath: require.resolve('./sidebars.js') with autogenerated) is great for getting started, but once you have 50+ docs pages, manually defining the sidebar order in sidebars.js prevents unexpected ordering surprises when adding new files.
Set trailingSlash: false in docusaurus.config.ts if you’re deploying to Vercel or Netlify. These platforms handle trailing slashes differently from GitHub Pages, and the wrong setting causes 404s on direct URL navigation.
Use the @docusaurus/plugin-ideal-image for documentation with screenshots or diagrams. It automatically generates responsive images with lazy loading, dramatically reducing page weight for docs-heavy sites. Install it once and add ![] image tags as normal — the optimization is automatic.
Swap Algolia for local search on private or intranet docs. Algolia DocSearch requires your site to be publicly crawlable. For internal documentation, use @easyops-cn/docusaurus-search-local instead — it generates a client-side search index at build time with no external service dependency.

Best For

Open-source projects needing professional documentation with versioning, search, and internationalization — Meta uses it for React, Redux, and dozens of other major projects
Developer tools and SDKs that need to document multiple API versions simultaneously and let users switch between them
Multilingual documentation — Docusaurus i18n support is production-ready and used by projects serving global developer communities
Teams comfortable with React who want to embed interactive demos, live code editors, or custom React components directly in documentation pages

Docusaurus vs. Alternatives

	Docusaurus	MkDocs	GitBook	Nextra
Framework	React	Python (mkdocs)	SaaS	Next.js
Versioning	✅ Built-in	✗ (plugin)	✅	✗
MDX/React	✅	✗	✗	✅
Search	Algolia/local	Algolia/local	✅ Built-in	Algolia
Self-hosted	✅	✅	Optional ($)	✅
Best for	Open-source, OSS SDKs	Python projects	Non-technical teams	Next.js sites

Docusaurus is the best choice for technical documentation that needs versioning and React integration. Use MkDocs for Python projects. Use GitBook for non-technical writers who don’t want to manage Markdown and GitHub.

Docusaurus

✅ Pros

⚠️ Cons