Docusaurus Guide

This guide covers how to use and customize the Docusaurus documentation site in this template.

Quick Start

Prerequisites

Node.js 18.0 or higher
npm or yarn package manager

Installation

# Navigate to the docs folder
cd docs

# Install dependencies
npm install

# Start development server
npm run start

The site will be available at http://localhost:3000.

Build for Production

# Build the static site
npm run build

# Preview the production build
npm run serve

Project Structure

docs/
├── docs/                    # Documentation content (Markdown/MDX)
│   ├── intro.md            # Landing page for /docs
│   ├── guides/             # How-to guides
│   ├── reference/          # API/reference documentation
│   ├── community/          # Community guidelines
│   └── decisions/          # Architecture Decision Records
├── src/
│   ├── components/         # React components
│   ├── css/               # Custom styles
│   ├── pages/             # Custom pages (landing, etc.)
│   └── theme/             # Theme overrides
├── static/                 # Static assets (images, files)
├── i18n/                   # Internationalization files
├── docusaurus.config.js    # Main configuration
├── sidebars.js            # Sidebar navigation
└── package.json           # Dependencies

Writing Documentation

Basic Markdown

Create a new .md file in the docs/ folder:

---
id: my-doc
title: My Document
sidebar_label: My Doc
sidebar_position: 1
---

# My Document

Your content here...

Front Matter Options

Field	Description
`id`	Unique document ID (used in URLs and links)
`title`	Document title (shown in browser tab)
`sidebar_label`	Short label for sidebar
`sidebar_position`	Order in sidebar (lower = higher)
`description`	Meta description for SEO
`keywords`	SEO keywords array
`tags`	Document tags for grouping
`hide_title`	Hide the title heading
`hide_table_of_contents`	Hide the TOC
`draft`	Hide in production if `true`

Linking Between Documents

<!-- Relative link (recommended) -->
[Getting Started](./GETTING_STARTED.md)

<!-- By document ID -->
[Contributing](/docs/reference/contributing)

<!-- With anchor -->
[Installation Section](./GETTING_STARTED.md#installation)

Adding Images

Place images in static/img/ and reference them:

![Alt text](/img/my-image.png)

Or use relative paths for co-located images:

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

MDX Features

Docusaurus supports MDX, allowing React components in Markdown.

Admonitions (Callouts)

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

:::tip
Pro tip here!
:::

:::info
Informational content.
:::

:::warning
Be careful!
:::

:::danger
Critical warning!
:::

Code Blocks

```javascript title="example.js"
const greeting = 'Hello, World!';
console.log(greeting);
```

```python {2-3} showLineNumbers
def hello():
    # These lines are highlighted
    print("Hello, World!")
```

Tabs

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

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

Mermaid Diagrams

This template has Mermaid enabled. Create diagrams in Markdown:

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

Edit sidebars.js to customize navigation:

const sidebars = {
  docsSidebar: [
    // Single document
    {
      type: 'doc',
      id: 'intro',
      label: '🚀 Getting Started',
    },
    // Category with items
    {
      type: 'category',
      label: '📚 Guides',
      collapsed: false, // Start expanded
      items: [
        'guides/GETTING_STARTED',
        'guides/DOCUSAURUS_GUIDE',
        // Nested category
        {
          type: 'category',
          label: '⚙️ Advanced',
          items: ['guides/SEARCH_GUIDE'],
        },
      ],
    },
    // Auto-generated from folder
    {
      type: 'autogenerated',
      dirName: 'reference',
    },
    // External link
    {
      type: 'link',
      label: 'GitHub',
      href: 'https://github.com/your-repo',
    },
  ],
};

Configuration

docusaurus.config.js

Key configuration options:

const config = {
  title: 'Your Site Title',
  tagline: 'Your tagline',
  url: 'https://your-domain.com',
  baseUrl: '/',
  
  // Behavior on broken links
  onBrokenLinks: 'throw',
  onBrokenMarkdownLinks: 'warn',
  
  // Internationalization
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'zh-TW'],
  },
  
  // Theme configuration
  themeConfig: {
    navbar: { /* ... */ },
    footer: { /* ... */ },
    colorMode: {
      defaultMode: 'light',
      respectPrefersColorScheme: true,
    },
  },
};

navbar: {
  title: 'My Site',
  logo: {
    alt: 'Logo',
    src: 'img/logo.svg',
  },
  items: [
    // Link to docs
    {
      type: 'docSidebar',
      sidebarId: 'docsSidebar',
      label: 'Docs',
      position: 'left',
    },
    // External link
    {
      href: 'https://github.com/your-repo',
      label: 'GitHub',
      position: 'right',
    },
    // Language dropdown
    {
      type: 'localeDropdown',
      position: 'right',
    },
  ],
},

Internationalization (i18n)

Translating Documents

Copy the document to the locale folder:

docs/i18n/zh-TW/docusaurus-plugin-content-docs/current/

Translate the content while keeping the same filename.

Translating UI Strings

Edit i18n/zh-TW/code.json:

{
  "theme.common.editThisPage": {
    "message": "編輯此頁",
    "description": "The link label to edit the current page"
  }
}

Building for All Locales

# Build all locales
npm run build

# Start dev server with specific locale
npm run start -- --locale zh-TW

Customization

Custom CSS

Edit src/css/custom.css:

:root {
  --ifm-color-primary: #667eea;
  --ifm-code-font-size: 95%;
}

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

Custom Components

Create components in src/components/:

// src/components/MyComponent/index.js
import React from 'react';
import styles from './styles.module.css';

export default function MyComponent({ title, children }) {
  return (
    <div className={styles.container}>
      <h3>{title}</h3>
      {children}
    </div>
  );
}

Use in MDX:

import MyComponent from '@site/src/components/MyComponent';

<MyComponent title="Hello">
  Content here
</MyComponent>

Theme Overrides (Swizzling)

Override theme components:

# See available components
npm run swizzle @docusaurus/theme-classic -- --list

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

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

Plugins

Installed Plugins

This template includes:

Plugin	Purpose
`@docusaurus/theme-mermaid`	Diagram support
`@easyops-cn/docusaurus-search-local`	Offline search
`@docusaurus/plugin-pwa`	Progressive Web App

Adding Plugins

Install the package:

npm install @docusaurus/plugin-ideal-image

Add to docusaurus.config.js:

plugins: [
  ['@docusaurus/plugin-ideal-image', {
    quality: 70,
    max: 1030,
    min: 640,
  }],
],

Deployment

GitHub Pages

# Set environment variables
export GIT_USER=<your-github-username>

# Deploy
npm run deploy

Other Platforms

Build the static site and deploy the build/ folder:

Platform	Command
Vercel	Connect repo, auto-deploys
Netlify	Build command: `npm run build`, publish: `build`
Cloudflare Pages	Same as Netlify

Common Tasks

Add a New Guide

Create docs/guides/MY_NEW_GUIDE.md
Add front matter with title and position
Add to sidebars.js if not using autogenerated

Edit sidebars.js for sidebar, docusaurus.config.js for navbar/footer.

Add a Blog

Uncomment blog plugin in docusaurus.config.js:

presets: [
  ['classic', {
    blog: {
      showReadingTime: true,
      blogSidebarCount: 'ALL',
    },
  }],
],

Enable Search

This template uses local search. For production sites, consider Algolia DocSearch.

Troubleshooting

Common Issues

Issue	Solution
Broken links error	Check file paths, use relative links
Build fails	Run `npm run clear` then rebuild
Styles not updating	Clear browser cache, restart dev server
i18n not working	Ensure locale folder structure matches

Useful Commands

# Clear cache
npm run clear

# Type check
npm run typecheck

# Write translations
npm run write-translations

# Upgrade Docusaurus
npm update @docusaurus/core @docusaurus/preset-classic

Quick Start​

Prerequisites​

Installation​

Build for Production​

Project Structure​

Writing Documentation​

Basic Markdown​

Front Matter Options​

Linking Between Documents​

Adding Images​

MDX Features​

Admonitions (Callouts)​

Code Blocks​

Tabs​

Mermaid Diagrams​

Sidebar Configuration​

Configuration​

docusaurus.config.js​

Adding Navbar Items​

Internationalization (i18n)​

Translating Documents​

Translating UI Strings​

Building for All Locales​

Customization​

Custom CSS​

Custom Components​

Theme Overrides (Swizzling)​

Plugins​

Installed Plugins​

Adding Plugins​

Deployment​

GitHub Pages​

Other Platforms​

Common Tasks​

Add a New Guide​

Update Navigation​

Add a Blog​

Enable Search​

Troubleshooting​

Common Issues​

Useful Commands​

Resources​