docusaurus

What this skill does

# Docusaurus Documentation Skill

Build fast, optimized documentation websites with Docusaurus. This skill covers project setup, versioning, internationalization, and search integration.

## When to Use This Skill

### USE When

- Building documentation for open source projects
- Need React components in documentation
- Require multi-version documentation
- Need internationalized documentation
- Want blog functionality alongside docs
- Building developer portals
- Need fast, SEO-optimized static sites
- Want MDX for interactive examples

### DON'T USE When

- Simple single-page documentation (use basic HTML)
- Python-specific API docs with autodoc (use Sphinx)
- No React experience and simple needs (use MkDocs)
- Need real-time collaborative editing (use GitBook)
- Building slide presentations (use Marp)

## Prerequisites

### Installation

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

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

cd my-website
npm start
```

### System Requirements

- Node.js 18.0 or higher
- npm 8 or yarn 1.22+
- Git (for versioning features)

## Core Capabilities

### 1. Project Structure

```
my-website/
├── blog/                    # Blog posts
├── docs/                    # Documentation
│   ├── intro.md
│   └── tutorial-basics/
├── src/
│   ├── components/          # React components
│   ├── css/                 # Custom styles
│   └── pages/               # Custom pages
├── static/                  # Static assets
├── docusaurus.config.js     # Main configuration
└── sidebars.js              # Sidebar configuration
```

### 2. Main Configuration

```javascript
// docusaurus.config.js
/** @type {import('@docusaurus/types').Config} */
const config = {
  title: 'My Project',
  tagline: 'A powerful documentation framework',
  favicon: 'img/favicon.ico',
  url: 'https://myproject.github.io',
  baseUrl: '/',
  organizationName: 'myorg',
  projectName: 'my-project',

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

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

  presets: [
    ['classic', {
      docs: {
        sidebarPath: './sidebars.js',
        editUrl: 'https://github.com/myorg/my-project/tree/main/',
        showLastUpdateTime: true,
      },
      blog: {
        showReadingTime: true,
        postsPerPage: 10,
      },
      theme: {
        customCss: './src/css/custom.css',
      },
    }],
  ],

  themeConfig: {
    navbar: {
      title: 'My Project',
      logo: { alt: 'Logo', src: 'img/logo.svg' },
      items: [
        { type: 'docSidebar', sidebarId: 'tutorialSidebar', label: 'Docs' },
        { to: '/blog', label: 'Blog' },
        { type: 'docsVersionDropdown' },
        { href: 'https://github.com/myorg/my-project', position: 'right' },
      ],
    },
    footer: {
      style: 'dark',
      links: [
        { title: 'Docs', items: [{ label: 'Getting Started', to: '/docs/intro' }] },
        { title: 'Community', items: [{ label: 'Discord', href: 'https://discord.gg/xxx' }] },
      ],
      copyright: `Copyright ${new Date().getFullYear()} My Project.`,
    },
    prism: {
      theme: require('prism-react-renderer').themes.github,
      darkTheme: require('prism-react-renderer').themes.dracula,
      additionalLanguages: ['bash', 'python', 'yaml'],
    },
  },
};

module.exports = config;
```

### 3. Sidebar Configuration

```javascript
// sidebars.js
const sidebars = {
  tutorialSidebar: [
    'intro',
    {
      type: 'category',
      label: 'Getting Started',
      collapsed: false,
      items: [
        'getting-started/installation',
        'getting-started/quick-start',
      ],
    },
    {
      type: 'category',
      label: 'Guides',
      link: { type: 'doc', id: 'guides/index' },
      items: ['guides/basic-usage', 'guides/advanced'],
    },
    {
      type: 'category',
      label: 'Examples',
      items: [{ type: 'autogenerated', dirName: 'examples' }],
    },
  ],
};

module.exports = sidebars;
```

### 4. Documentation Pages

```markdown
<!-- docs/intro.md -->
---
id: intro
title: Introduction
sidebar_position: 1
description: Introduction to My Project
---

# Introduction

Welcome to **My Project** documentation!

## Quick Example

```javascript
import { MyProject } from 'my-project';
const project = new MyProject();
```

:::tip Did you know?
You can use admonitions for callouts!
:::
```

### 5. MDX and React Components

```jsx
// docs/interactive-example.mdx
---
id: interactive-example
title: Interactive Example
---

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

# Interactive Example

<Tabs>
  <TabItem value="js" label="JavaScript" default>

```javascript
function hello() {
  console.log('Hello!');
}
```

  </TabItem>
  <TabItem value="py" label="Python">

```python
def hello():
    print("Hello!")
```

  </TabItem>
</Tabs>

## Inline JSX

export const Highlight = ({children, color}) => (
  <span style={{ backgroundColor: color, padding: '0.2rem', borderRadius: '4px' }}>
    {children}
  </span>
);

This is <Highlight color="#25c2a0">highlighted</Highlight> text.
```

### 6. Admonitions

```markdown
:::note
This is a note.
:::

:::tip Pro Tip
Use tips for helpful suggestions.
:::

:::info
Informational content.
:::

:::caution
Warnings about potential issues.
:::

:::danger Critical
Critical warnings.
:::

:::note Custom Title
Admonition with custom title.
:::
```

### 7. Blog Posts

```markdown
<!-- blog/2024-01-15-release-v2.md -->
---
slug: release-v2
title: Releasing Version 2.0
authors:
  - name: John Doe
    title: Lead Developer
    image_url: https://github.com/johndoe.png
tags: [release, announcement]
image: /img/blog/v2-release.png
---

# Releasing Version 2.0

We are excited to announce v2.0!

<!-- truncate -->

## What's New

- Feature 1
- Feature 2

## Migration Guide

See our [migration guide](/docs/migration/v2).
```

### 8. Versioning

```bash
# Create a new version
npm run docusaurus docs:version 1.0

# Creates:
# - versioned_docs/version-1.0/
# - versioned_sidebars/version-1.0-sidebars.json
# - versions.json
```

```javascript
// docusaurus.config.js
module.exports = {
  presets: [['@docusaurus/preset-classic', {
    docs: {
      lastVersion: 'current',
      versions: {
        current: { label: '2.0 (Next)', path: 'next' },
        '1.0': { label: '1.0', path: '1.0' },
      },
    },
  }]],
};
```

### 9. Internationalization (i18n)

```javascript
// docusaurus.config.js
module.exports = {
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'fr', 'de'],
    localeConfigs: {
      en: { label: 'English', htmlLang: 'en-US' },
      fr: { label: 'Francais', htmlLang: 'fr-FR' },
    },
  },
};
```

```bash
# Generate translation files
npm run write-translations -- --locale fr

# Copy docs to translate
mkdir -p i18n/fr/docusaurus-plugin-content-docs/current
cp -r docs/* i18n/fr/docusaurus-plugin-content-docs/current/

# Start in French
npm run start -- --locale fr
```

### 10. Search with Algolia

```javascript
// docusaurus.config.js
module.exports = {
  themeConfig: {
    algolia: {
      appId: 'YOUR_APP_ID',
      apiKey: 'YOUR_SEARCH_API_KEY',
      indexName: 'your_index_name',
      contextualSearch: true,
    },
  },
};
```

```bash
# Alternative: Local search plugin
npm install @easyops-cn/docusaurus-search-local
```

### 11. Custom CSS

```css
/* src/css/custom.css */
:root {
  --ifm-color-primary: #2e8555;
  --ifm-code-font-size: 95%;
  --ifm-font-family-base: 'Inter', sans-serif;
}

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

.navbar { box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1); }
```

### 12. GitHub Pages Deployment

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

on:
  push:
    branches: [main]

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

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with