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

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

// 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

// 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

<!-- docs/intro.md -->

id: intro title: Introduction sidebar_position: 1 description: Introduction to My Project

Introduction

Welcome to My Project documentation!

Quick Example

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!');
}

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

Inline JSX

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

);

This is highlighted 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

<!-- 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

# 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

// 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)

// 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' },
    },
  },
};

# 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

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

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

11. Custom 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

# .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:
          node-version: 20
          cache: npm
      - run: npm ci
      - run: npm run build
      - uses: actions/upload-pages-artifact@v3
        with:
          path: build

  deploy:
    environment:
      name: github-pages
    runs-on: ubuntu-latest
    needs: build
    steps:
      - uses: actions/deploy-pages@v4

# Manual deployment
npm run build
npm run deploy

13. Vercel/Netlify Deployment

// vercel.json
{
  "buildCommand": "npm run build",
  "outputDirectory": "build",
  "framework": "docusaurus-2"
}

# netlify.toml
[build]
  command = "npm run build"
  publish = "build"

Integration Examples

Integration with TypeDoc

npm install typedoc docusaurus-plugin-typedoc

module.exports = {
  plugins: [
    ['docusaurus-plugin-typedoc', {
      entryPoints: ['../src/index.ts'],
      tsconfig: '../tsconfig.json',
      out: 'api',
    }],
  ],
};

Integration with OpenAPI

npm install docusaurus-plugin-openapi-docs docusaurus-theme-openapi-docs

module.exports = {
  plugins: [
    ['docusaurus-plugin-openapi-docs', {
      id: 'openapi',
      config: {
        petstore: {
          specPath: 'api/openapi.yaml',
          outputDir: 'docs/api',
        },
      },
    }],
  ],
  themes: ['docusaurus-theme-openapi-docs'],
};

Best Practices

1. Documentation Structure

docs/
├── intro.md
├── getting-started/
│   ├── _category_.json
│   ├── installation.md
│   └── quick-start.md
├── guides/
│   ├── _category_.json
│   ├── index.md
│   └── advanced.md
├── api/
│   └── reference.md
├── faq.md
└── changelog.md

// docs/getting-started/_category_.json
{
  "label": "Getting Started",
  "position": 1,
  "collapsible": true,
  "collapsed": false
}

2. SEO Optimization

---
title: My Page | Brand Name
description: Description for search engines (150-160 chars)
keywords: [keyword1, keyword2]
image: /img/og/my-page.png
---

3. Content Guidelines

---
id: unique-id
title: Clear Title
sidebar_label: Short Label
description: SEO description
---

# Page Title (H1 - only one)

## Section (H2)

### Subsection (H3)

:::tip Best Practice
Use admonitions appropriately.
:::

See also: [Related Page](./related.md)

Troubleshooting

Build Fails with Module Not Found

rm -rf node_modules .docusaurus build
npm install
npm run build

Hot Reload Not Working

npm run clear
npm run start

Broken Links

module.exports = {
  onBrokenLinks: 'warn', // Change from 'throw' for debugging
};

i18n Build Issues

npm run build -- --locale en
npm run write-translations -- --locale fr

Debug Mode

DEBUG=docusaurus* npm run build
npm run start -- --port 3001

Algolia Indexing Issues

// Check Algolia configuration
module.exports = {
  themeConfig: {
    algolia: {
      appId: 'YOUR_APP_ID',       // Not the API key
      apiKey: 'SEARCH_ONLY_KEY',  // Search-only API key
      indexName: 'your_index',
      debug: true,                // Enable debug mode
    },
  },
};

Version Dropdown Not Showing

// Ensure versions.json exists and navbar is configured
module.exports = {
  themeConfig: {
    navbar: {
      items: [
        { type: 'docsVersionDropdown', position: 'right' },
      ],
    },
  },
};

Advanced Configuration

Custom Homepage

// src/pages/index.js
import React from 'react';
import Layout from '@theme/Layout';
import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
import styles from './index.module.css';

function HomepageHeader() {
  const { siteConfig } = useDocusaurusContext();
  return (
    <header className={styles.heroBanner}>
      <div className="container">
        <h1 className="hero__title">{siteConfig.title}</h1>
        <p className="hero__subtitle">{siteConfig.tagline}</p>
        <div className={styles.buttons}>
          <a className="button button--primary button--lg" href="/docs/intro">
            Get Started
          </a>
        </div>
      </div>
    </header>
  );
}

export default function Home() {
  return (
    <Layout title="Home" description="Welcome to our documentation">
      <HomepageHeader />
      <main>
        <section className={styles.features}>
          <div className="container">
            <div className="row">
              <Feature title="Easy to Use" description="Simple setup and configuration" />
              <Feature title="Powerful" description="Full React and MDX support" />
              <Feature title="Fast" description="Optimized for performance" />
            </div>
          </div>
        </section>
      </main>
    </Layout>
  );
}

Plugin Development

// plugins/my-plugin/index.js
module.exports = function myPlugin(context, options) {
  return {
    name: 'my-plugin',

    async loadContent() {
      return { data: 'example' };
    },

    async contentLoaded({ content, actions }) {
      const { createData, addRoute } = actions;
      const dataPath = await createData('my-data.json', JSON.stringify(content));

      addRoute({
        path: '/custom-page',
        component: '@site/src/components/CustomPage',
        modules: { data: dataPath },
        exact: true,
      });
    },

    configureWebpack(config, isServer) {
      return {
        resolve: {
          alias: { '@data': path.resolve(__dirname, 'data') },
        },
      };
    },
  };
};

Version History

v1.0.0 (2026-01-17)

- Initial skill creation

- Project setup and configuration

- Documentation pages with MDX

- Blog functionality

- Sidebar configuration

- Theme customization

- Versioning setup

- Internationalization (i18n)

- Algolia search integration

- GitHub Pages deployment

- Best practices and troubleshooting

Related Resources

- Docusaurus Documentation

- Docusaurus GitHub

- MDX Documentation

- Algolia DocSearch

- Docusaurus Showcase

Build blazing-fast documentation websites with React and MDX.