Docusaurus Expert Advisor

Your specialized agent for building, configuring, and customizing documentation sites with Docusaurus v2/v3, covering site configuration, theming, content management, plugins, and deployment.

When to Use This Agent

Choose Docusaurus Expert Advisor when:

• Setting up a new Docusaurus documentation site from scratch
• Customizing Docusaurus themes, layouts, and CSS styling
• Configuring sidebars, navigation, search, and versioning
• Building custom Docusaurus plugins or Remark/Rehype extensions
• Deploying Docusaurus to GitHub Pages, Vercel, Netlify, or S3

Consider alternatives when:

• You need general documentation strategy — use a documentation engineer agent
• You prefer MkDocs, GitBook, or another doc platform — those need different agents
• You need blog-only sites — Docusaurus works but simpler tools may be better

Quick Start

Copy
# .claude/agents/docusaurus-expert.yml
name: Docusaurus Expert Advisor
model: claude-sonnet
tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
description: Docusaurus specialist for documentation site configuration, theming, plugins, and deployment

Example invocation:

claude "Configure our Docusaurus site with versioned docs, Algolia search, a custom dark mode theme, and automatic deployment to GitHub Pages on merge to main"

Core Concepts

Docusaurus Project Structure

my-docs/
├── docusaurus.config.js     # Main site configuration
├── sidebars.js              # Sidebar navigation structure
├── src/
│   ├── pages/               # Custom standalone pages
│   ├── components/          # React components
│   └── css/                 # Custom styles
├── docs/                    # Documentation markdown files
│   ├── intro.md
│   ├── guides/
│   └── api/
├── blog/                    # Blog posts (optional)
├── static/                  # Static assets (images, files)
└── versioned_docs/          # Versioned doc snapshots

Key Configuration Areas

Area	File	Purpose
Site Metadata	docusaurus.config.js → title, tagline, url	SEO and branding
Navigation	docusaurus.config.js → themeConfig.navbar	Top navigation bar
Sidebar	sidebars.js	Doc page sidebar structure
Search	docusaurus.config.js → themeConfig.algolia	Algolia DocSearch integration
Theming	src/css/custom.css	Custom colors, fonts, layout
Plugins	docusaurus.config.js → plugins	Extended functionality

Configuration

Parameter	Description	Default
docusaurus_version	Docusaurus version (v2, v3)	v3
typescript	Use TypeScript config and components	false
versioning	Enable versioned docs	false
search_provider	Search integration (algolia, local, none)	local
deploy_target	Deployment platform (github-pages, vercel, netlify)	github-pages

Best Practices

1. Use autogenerated sidebars with strategic overrides. Start with sidebars: { docs: [{type: 'autogenerated', dirName: '.'}] } to generate sidebar from directory structure. Override specific sections with manual ordering when the alphabetical default doesn't match your learning progression.

2. Implement doc versioning before your first breaking API change. Run npm run docusaurus docs:version 1.0 to snapshot current docs. Future readers on older versions get accurate documentation, and you can update current docs without breaking backward compatibility.

3. Customize theming through CSS variables, not component swizzling. Docusaurus exposes CSS custom properties for colors, fonts, and spacing. Modify these in src/css/custom.css before resorting to component swizzling, which creates upgrade friction between Docusaurus versions.

4. Add Algolia DocSearch for sites with more than 50 pages. Docusaurus's local search works for small sites, but Algolia provides instant, typo-tolerant search that scales to thousands of pages. Apply for the free DocSearch program for open-source projects.

5. Use MDX for interactive documentation. Docusaurus supports MDX natively, allowing you to embed React components in documentation pages. Use this for interactive code playgrounds, live API explorers, and tabbed content that shows examples in multiple languages.

Common Issues

Sidebar order doesn't match the learning progression. Autogenerated sidebars sort alphabetically, which rarely matches the ideal reading order. Use sidebar_position frontmatter in docs or create a manual sidebars.js configuration that orders pages by learning sequence.

Custom CSS breaks on Docusaurus version upgrade. Swizzled components and deeply-targeted CSS selectors break when Docusaurus changes its internal HTML structure. Prefer CSS custom properties and the official theming API. When swizzling, use the --wrap option instead of --eject for more upgrade resilience.

Build fails with "Module not found" after adding a plugin. Docusaurus plugins may require specific peer dependencies that aren't auto-installed. Check the plugin's documentation for required dependencies, install them explicitly, and ensure your Node.js version matches the plugin's requirements.