Docusaurus Cheat Sheet

Overview

Docusaurus is an open-source static site generator built by Meta, designed specifically for creating documentation websites. It is built on React and provides features like versioned documentation, blog support, internationalization, search integration, and a plugin ecosystem. Docusaurus generates fast, accessible static HTML that can be hosted anywhere.

Docusaurus v3 uses MDX (Markdown with JSX) for content, supports multiple documentation instances, and offers extensive theming and customization through React components. It includes built-in support for Algolia DocSearch, dark mode, and sidebar generation from filesystem structure.

Installation

# Create a new Docusaurus site
npx create-docusaurus@latest my-docs classic

# With TypeScript
npx create-docusaurus@latest my-docs classic --typescript

# Navigate and start dev server
cd my-docs
npm run start

# Build for production
npm run build

# Serve production build locally
npm run serve

# Clear build cache
npm run clear

Project Structure

my-docs/
├── blog/                    # Blog posts
│   └── 2024-01-01-post.md
├── docs/                    # Documentation pages
│   ├── intro.md
│   └── tutorial/
│       ├── _category_.json
│       └── getting-started.md
├── src/
│   ├── components/
│   ├── css/
│   └── pages/
├── static/
│   └── img/
├── docusaurus.config.js
├── sidebars.js
└── package.json

Configuration

docusaurus.config.js

const config = {
  title: 'My Documentation',
  tagline: 'Easy to use docs',
  url: 'https://docs.example.com',
  baseUrl: '/',
  onBrokenLinks: 'throw',
  onBrokenMarkdownLinks: 'warn',
  favicon: 'img/favicon.ico',

  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'fr', 'es'],
  },

  presets: [
    ['classic', {
      docs: {
        sidebarPath: require.resolve('./sidebars.js'),
        editUrl: 'https://github.com/my-org/my-docs/edit/main/',
        showLastUpdateTime: true,
        showLastUpdateAuthor: true,
      },
      blog: {
        showReadingTime: true,
        blogSidebarCount: 'ALL',
      },
      theme: {
        customCss: require.resolve('./src/css/custom.css'),
      },
    }],
  ],

  themeConfig: {
    navbar: {
      title: 'My Docs',
      logo: { alt: 'Logo', src: 'img/logo.svg' },
      items: [
        { type: 'docSidebar', sidebarId: 'tutorialSidebar', label: 'Docs' },
        { to: '/blog', label: 'Blog' },
        { type: 'localeDropdown', position: 'right' },
        { type: 'docsVersionDropdown', position: 'right' },
      ],
    },
    prism: { theme: require('prism-react-renderer').themes.github },
    algolia: {
      appId: 'YOUR_APP_ID',
      apiKey: 'YOUR_SEARCH_KEY',
      indexName: 'my-docs',
    },
  },
};

module.exports = config;

Sidebar Configuration (sidebars.js)

module.exports = {
  tutorialSidebar: [
    'intro',
    {
      type: 'category',
      label: 'Getting Started',
      items: ['tutorial/installation', 'tutorial/configuration'],
      collapsed: false,
    },
    {
      type: 'category',
      label: 'Advanced',
      items: [{ type: 'autogenerated', dirName: 'advanced' }],
    },
    { type: 'link', label: 'GitHub', href: 'https://github.com/my-org' },
  ],
};

Document Frontmatter

---
id: my-doc-id
title: My Document Title
description: SEO description for the page
slug: /custom-url-path
sidebar_label: Short Label
sidebar_position: 3
tags:
  - getting-started
  - configuration
hide_title: false
hide_table_of_contents: false
draft: false
---

MDX Features

Admonitions

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

:::tip
Helpful tip content here.
:::

:::info
Informational content.
:::

:::warning
Warning content.
:::

:::danger
Dangerous action warning.
:::

Tabs

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

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

Versioning

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

# Creates versioned_docs/version-1.0.0/ and versions.json

Internationalization

# Initialize translation files
npm run write-translations -- --locale fr

# Start dev server in French
npm run start -- --locale fr

Advanced Usage

Swizzling Components

# List swizzlable components
npm run swizzle -- --list

# Wrap a component (safe)
npm run swizzle @docusaurus/theme-classic Footer -- --wrap

# Eject a component (full control)
npm run swizzle @docusaurus/theme-classic Footer -- --eject

Custom React Pages

// src/pages/custom.js
import React from 'react';
import Layout from '@theme/Layout';

export default function CustomPage() {
  return (
    <Layout title="Custom Page" description="A custom page">
      <div style={{ padding: '2rem' }}>
        <h1>Custom Page</h1>
        <p>This is built with React.</p>
      </div>
    </Layout>
  );
}

Deployment

# Deploy to GitHub Pages
GIT_USER=<username> npm run deploy

# Build static files for any host
npm run build
# Output in build/ directory

Troubleshooting

Issue	Solution
Broken links error on build	Fix or set onBrokenLinks: 'warn' in config
MDX compilation error	Check JSX syntax; escape < and { in Markdown
Sidebar not updating	Clear cache with npm run clear then rebuild
Version dropdown not showing	Ensure versions.json exists and has entries
Algolia search returning no results	Verify API keys and index name; recrawl if needed
CSS changes not reflecting	Hard refresh browser; check CSS specificity
Build OOM error	Increase Node memory: NODE_OPTIONS=--max-old-space-size=8192
Plugin conflict	Check plugin compatibility with your Docusaurus version