Docusaurus

A guide to using Docusaurus for documentation sites.

What is Docusaurus?

Docusaurus is a static site generator built by Meta specifically for documentation websites. It's a complete framework that:

• Converts Markdown files into a fully functional website
• Provides a pre-built UI (navbar, sidebar, search, dark mode)
• Handles routing, bundling, and optimization
• Outputs static HTML/CSS/JS that can be hosted anywhere

Architecture

Not Next.js

Docusaurus is not built on Next.js - they're separate frameworks:

Framework	Purpose	Built On
Docusaurus	Documentation sites	React + custom SSG
Next.js	Full-stack web apps	React
Nextra	Docs (Next.js-based)	Next.js

---

Quick Start

Create a New Site

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

Project Structure

my-docs/
├── docs/                 # Markdown documentation
│   ├── intro.md
│   └── tutorial/
├── src/
│   ├── css/custom.css    # Custom styles
│   └── pages/            # Custom React pages
├── static/               # Static assets (images, etc.)
├── docusaurus.config.js  # Main configuration
├── sidebars.js           # Sidebar structure
└── package.json

---

Configuration

docusaurus.config.js

The main configuration file controls everything:

const config = {
  // Site metadata
  title: 'My Docs',
  tagline: 'Documentation for my project',
  url: 'https://docs.example.com',
  baseUrl: '/',

  // Build settings
  future: {
    v4: true,
    experimental_faster: true, // 2-5x faster builds
  },

  // Presets bundle common plugins
  presets: [
    [
      'classic',
      {
        docs: {
          sidebarPath: './sidebars.js',
          editUrl: 'https://github.com/user/repo/tree/main/',
        },
        theme: {
          customCss: './src/css/custom.css',
        },
      },
    ],
  ],

  // Theme configuration
  themeConfig: {
    navbar: { /* ... */ },
    footer: { /* ... */ },
    colorMode: {
      defaultMode: 'dark',
      respectPrefersColorScheme: true,
    },
  },
};

sidebars.js

Controls the sidebar navigation:

// Auto-generate from folder structure
const sidebars = {
  docs: [
    {
      type: 'autogenerated',
      dirName: '.',
    },
  ],
};

// Or define manually
const sidebars = {
  docs: [
    'intro',
    {
      type: 'category',
      label: 'Getting Started',
      items: ['installation', 'configuration'],
    },
  ],
};

---

Writing Content

Frontmatter

Every markdown file can have frontmatter:

---
sidebar_position: 1
sidebar_label: 'Custom Label'
title: 'Page Title'
description: 'SEO description'
tags: [guide, tutorial]
---

# Your Content Here

Admonitions

Built-in callout boxes:

:::note
This is a note.
:::

:::tip
This is a tip.
:::

:::warning
This is a warning.
:::

:::danger
This is dangerous!
:::

:::info
This is informational.
:::

Renders as:

note

This is a note.

tip

This is a tip.

warning

This is a warning.

Code Blocks

Syntax highlighting with titles and line highlighting:

```javascript title="example.js"
// highlight-next-line
const highlighted = true;

function example() {
  // highlight-start
  const multiLine = 'highlighted';
  return multiLine;
  // highlight-end
}
```

Tabs

Group related content:

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

<Tabs>
  <TabItem value="npm" label="npm" default>
    npm install package
  </TabItem>
  <TabItem value="yarn" label="yarn">
    yarn add package
  </TabItem>
</Tabs>

Mermaid Diagrams

Create diagrams in markdown (requires @docusaurus/theme-mermaid):

```mermaid
flowchart LR
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
```

Renders as:

---

Plugins

Local Search

Add offline search without Algolia:

npm install @easyops-cn/docusaurus-search-local

// docusaurus.config.js
plugins: [
  [
    '@easyops-cn/docusaurus-search-local',
    {
      hashed: true,
      language: ['en'],
      highlightSearchTermsOnTargetPage: true,
    },
  ],
],

Mermaid Diagrams

npm install @docusaurus/theme-mermaid

// docusaurus.config.js
markdown: {
  mermaid: true,
},
themes: ['@docusaurus/theme-mermaid'],
themeConfig: {
  mermaid: {
    theme: { light: 'neutral', dark: 'dark' },
  },
},

Faster Builds

npm install @docusaurus/faster

// docusaurus.config.js
future: {
  v4: true,
  experimental_faster: true,
},

---

Deployment

Build for Production

npm run build

Outputs to build/ directory.

Vercel

1. Push to GitHub
2. Import project in Vercel
3. Build settings are auto-detected
4. Add custom domain if needed

GitHub Pages

// docusaurus.config.js
const config = {
  url: 'https://username.github.io',
  baseUrl: '/repo-name/',
  organizationName: 'username',
  projectName: 'repo-name',
  deploymentBranch: 'gh-pages',
};

GIT_USER=username npm run deploy

---

Common Commands

Command	Description
npm start	Start dev server
npm run build	Build for production
npm run serve	Serve production build locally
npm run clear	Clear cache
npm run swizzle	Customize theme components

---

Tips

Organize with Categories

Use _category_.json in folders:

{
  "label": "Getting Started",
  "position": 1,
  "collapsed": false
}

Custom CSS

Override theme variables in src/css/custom.css:

:root {
  --ifm-color-primary: #2e8555;
  --ifm-code-font-size: 95%;
}

[data-theme='dark'] {
  --ifm-color-primary: #25c2a0;
}

Assets

Put images in static/img/ and reference them:

![Alt text](/img/screenshot.png)

---

Resources

• Docusaurus Documentation
• Docusaurus GitHub
• Showcase - Sites built with Docusaurus