Documentation Tool

Docusaurus

Overview

Docusaurus is a React-based static site generator developed by Facebook (Meta). It specializes in OSS documentation and is a modern documentation site building platform that integrates MDX support, versioning, and internationalization features.

Details

Docusaurus was developed by Facebook (now Meta) in 2017 and brought innovation to open source project documentation creation. Its React foundation enables generating beautiful and functional websites from Markdown files. MDX (Markdown + JSX) support allows embedding React components directly in documentation. The plugin system enables feature extensions and flexible customization. Versioning functionality allows parallel management of multiple document versions. Internationalization (i18n) features enable efficient construction of multilingual sites. Search functionality, SEO optimization, and fast static site generation provide excellent user experience. The theme system enables complete customization of design and layout. As of 2025, it has been adopted by notable OSS projects including React, Vue.js, Node.js, Babel, Jest, and others, establishing itself as the standard documentation platform for technical communities. Developer-friendly design easily enables Git-based workflows and CI/CD integration.

Advantages and Disadvantages

Advantages

• React-based Flexibility: Advanced interactive content through MDX React component integration
• OSS-specialized Design: Standard features for versioning, release notes, and API documentation generation
• Multilingual Support: Efficient multilingual site construction through internationalization features
• High Performance: Fast loading and excellent SEO through static site generation
• Rich Plugins: Integration with Algolia search, Mermaid diagrams, Google Analytics, etc.
• Git Integration: Version control and collaboration through Markdown files
• Customizability: Infinite design and layout adjustments with React knowledge

Disadvantages

• Learning Curve: React/JSX knowledge required, complex initial setup
• Node.js Dependency: Essential Node.js dependency for development environment and build process
• OSS-focused: Feature-heavy for internal enterprise documentation or wiki use
• Build Time: Increased build time for large-scale sites
• Complexity: Too feature-rich for small projects
• React Learning Curve: React development skills required for advanced customization

Key Links

• Docusaurus Official Site
• Docusaurus Documentation
• GitHub Repository
• Plugin Marketplace
• Community
• Showcase

Usage Examples

Basic Project Structure

# Create Docusaurus project
npx create-docusaurus@latest my-website classic

# Project structure
my-website/
├── docusaurus.config.js    # Site configuration
├── sidebars.js             # Sidebar configuration
├── src/
│   ├── components/         # Custom React components
│   ├── css/               # Global styles
│   └── pages/             # Custom pages
├── docs/                  # Documentation files
├── blog/                  # Blog posts
├── static/                # Static files
└── i18n/                  # Internationalization files

docusaurus.config.js Configuration

// @ts-check
import { themes as prismThemes } from 'prism-react-renderer';

/** @type {import('@docusaurus/types').Config} */
const config = {
  title: 'Project Name',
  tagline: 'Project Description',
  favicon: 'img/favicon.ico',

  // Site URL and base URL
  url: 'https://your-docusaurus-site.example.com',
  baseUrl: '/',

  // GitHub pages deployment configuration
  organizationName: 'your-github-org',
  projectName: 'your-repo-name',

  onBrokenLinks: 'throw',
  onBrokenMarkdownLinks: 'warn',

  // Internationalization configuration
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'ja'],
  },

  presets: [
    [
      'classic',
      /** @type {import('@docusaurus/preset-classic').Options} */
      ({
        docs: {
          sidebarPath: require.resolve('./sidebars.js'),
          editUrl: 'https://github.com/your-org/your-repo/tree/main/',
          versions: {
            current: {
              label: 'v3.x (Development)',
              path: 'next',
            },
          },
          lastVersion: 'current',
          showLastUpdateAuthor: true,
          showLastUpdateTime: true,
        },
        blog: {
          showReadingTime: true,
          editUrl: 'https://github.com/your-org/your-repo/tree/main/',
        },
        theme: {
          customCss: require.resolve('./src/css/custom.css'),
        },
        gtag: {
          trackingID: 'G-XXXXXXXXXX',
          anonymizeIP: true,
        },
      }),
    ],
  ],

  themeConfig:
    /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
    ({
      image: 'img/docusaurus-social-card.jpg',
      navbar: {
        title: 'Project Name',
        logo: {
          alt: 'Logo',
          src: 'img/logo.svg',
        },
        items: [
          {
            type: 'docSidebar',
            sidebarId: 'tutorialSidebar',
            position: 'left',
            label: 'Documentation',
          },
          { to: '/blog', label: 'Blog', position: 'left' },
          {
            type: 'docsVersionDropdown',
            position: 'right',
          },
          {
            type: 'localeDropdown',
            position: 'right',
          },
          {
            href: 'https://github.com/your-org/your-repo',
            label: 'GitHub',
            position: 'right',
          },
        ],
      },
      footer: {
        style: 'dark',
        links: [
          {
            title: 'Documentation',
            items: [
              {
                label: 'Tutorial',
                to: '/docs/intro',
              },
            ],
          },
          {
            title: 'Community',
            items: [
              {
                label: 'Discord',
                href: 'https://discordapp.com/invite/docusaurus',
              },
              {
                label: 'Twitter',
                href: 'https://twitter.com/docusaurus',
              },
            ],
          },
        ],
        copyright: "Copyright © " + new Date().getFullYear() + " My Project, Inc. Built with Docusaurus.",
      },
      prism: {
        theme: prismThemes.github,
        darkTheme: prismThemes.dracula,
        additionalLanguages: ['java', 'php', 'rust', 'elixir'],
      },
      algolia: {
        appId: 'YOUR_APP_ID',
        apiKey: 'YOUR_SEARCH_API_KEY',
        indexName: 'YOUR_INDEX_NAME',
        contextualSearch: true,
      },
    }),

  plugins: [
    '@docusaurus/theme-mermaid',
    [
      '@docusaurus/plugin-content-docs',
      {
        id: 'api',
        path: 'api',
        routeBasePath: 'api',
        sidebarPath: require.resolve('./sidebarsApi.js'),
      },
    ],
  ],

  themes: ['@docusaurus/theme-mermaid'],

  markdown: {
    mermaid: true,
  },
};

export default config;

Creating MDX Files

---
id: getting-started
title: Getting Started
sidebar_label: Quick Start
sidebar_position: 1
description: Project introduction guide
keywords: [setup, installation, quickstart]
---

# Getting Started with Project

Welcome to the project! This guide explains everything from setup to basic usage.

## Installation

```bash
npm install your-package

Basic Usage

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

graph TD
    A[User] --> B[API Gateway]
    B --> C[Authentication Service]
    B --> D[Business Logic]
    D --> E[Database]
    D --> F[External Services]

### Creating Custom React Components
```jsx
// src/components/FeatureList.js
import React from 'react';
import clsx from 'clsx';
import styles from './styles.module.css';

const FeatureList = [
  {
    title: 'Easy to Use',
    Svg: require('@site/static/img/undraw_docusaurus_mountain.svg').default,
    description: (
      <>
        Docusaurus was designed from the ground up to be easily installed and
        used to get your website up and running quickly.
      </>
    ),
  },
  {
    title: 'Focus on What Matters',
    Svg: require('@site/static/img/undraw_docusaurus_tree.svg').default,
    description: (
      <>
        Docusaurus lets you focus on your docs, and we&apos;ll do the chores. Go
        ahead and move your docs into the <code>docs</code> directory.
      </>
    ),
  },
  {
    title: 'Powered by React',
    Svg: require('@site/static/img/undraw_docusaurus_react.svg').default,
    description: (
      <>
        Extend or customize your website layout by reusing React. Docusaurus can
        be extended while reusing the same header and footer.
      </>
    ),
  },
];

function Feature({Svg, title, description}) {
  return (
    <div className={clsx('col col--4')}>
      <div className="text--center">
        <Svg className={styles.featureSvg} role="img" />
      </div>
      <div className="text--center padding-horiz--md">
        <h3>{title}</h3>
        <p>{description}</p>
      </div>
    </div>
  );
}

export default function HomepageFeatures() {
  return (
    <section className={styles.features}>
      <div className="container">
        <div className="row">
          {FeatureList.map((props, idx) => (
            <Feature key={idx} {...props} />
          ))}
        </div>
      </div>
    </section>
  );
}

// plugins/custom-plugin.js
module.exports = function (context, options) {
  return {
    name: 'custom-plugin',
    configureWebpack(config, isServer, utils) {
      return {
        resolve: {
          alias: {
            '@components': path.resolve(__dirname, '../src/components'),
          },
        },
      };
    },
    getThemePath() {
      return path.resolve(__dirname, './theme');
    },
    contentLoaded({content, actions}) {
      const {addRoute, createData} = actions;
      // Add custom routes
      addRoute({
        path: '/custom-page',
        component: '@theme/CustomPage',
        exact: true,
      });
    },
  };
};

// i18n/en/docusaurus-plugin-content-docs/current.json
{
  "version.label": {
    "message": "Next",
    "description": "The label for version current"
  },
  "sidebar.tutorialSidebar.category.Tutorial - Basics": {
    "message": "Tutorial - Basics",
    "description": "The label for category Tutorial - Basics in sidebar tutorialSidebar"
  }
}

// i18n/en/code.json
{
  "theme.common.edit": {
    "message": "Edit this page",
    "description": "The edit button label on doc pages"
  },
  "theme.common.next": {
    "message": "Next",
    "description": "The next button label on doc pages"
  }
}

# .github/workflows/deploy.yml
name: Deploy to GitHub Pages

on:
  push:
    branches:
      - main

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 18
          cache: npm

      - name: Install dependencies
        run: npm ci
      - name: Build website
        run: npm run build

      - name: Setup Pages
        uses: actions/configure-pages@v4
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: build

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

# Create new version
npm run docusaurus docs:version 1.0

# Version structure
website/
├── versioned_docs/
│   ├── version-1.0/
│   └── version-2.0/
├── versioned_sidebars/
│   ├── version-1.0-sidebars.json
│   └── version-2.0-sidebars.json
└── versions.json

// Algolia DocSearch configuration
module.exports = {
  themeConfig: {
    algolia: {
      appId: 'YOUR_APP_ID',
      apiKey: 'YOUR_SEARCH_API_KEY',
      indexName: 'YOUR_INDEX_NAME',
      contextualSearch: true,
      searchParameters: {},
      searchPagePath: 'search',
    },
  },
};