---

name: docusaurus-initializer version: 1.0 description: This skill should be used when initializing a new Docusaurus documentation site with TypeScript and custom dark mode theme. Provides basic setup with pnpm, theme installation, and configuration templates for technical documentation.

Docusaurus Initializer

Initialize and configure Docusaurus documentation sites with TypeScript and custom dark mode theme.

What This Skill Does

1. Project Initialization - Scaffold new Docusaurus projects with pnpm and TypeScript
2. Custom Theme Installation - Apply dark mode optimized theme for technical content
3. Configuration Templates - Provide annotated configuration files for quick setup

When to Use This Skill

Initialize a new Docusaurus site when:

• Starting a new documentation project
• Need a dark mode optimized theme for technical content
• Want TypeScript setup with proper configuration
• Prefer pnpm as the package manager

How to Use This Skill

Follow the 4-step initialization workflow:

Step 1: Initialize Docusaurus Project with pnpm

Create a new Docusaurus project:

Copypnpm create docusaurus@latest my-website classic --typescript
cd my-website

This creates:

Copymy-website/
├── docs/                    # Documentation files
├── blog/                    # Blog posts
├── src/                     # Custom pages
├── static/                  # Static assets
├── docusaurus.config.ts     # Main configuration
├── sidebars.ts             # Navigation structure
└── package.json            # Dependencies

Verify installation:

Copypnpm install
pnpm run build

For detailed setup guidance, see references/initialization-guide.md.

Step 2: Install Custom Theme

Apply the dark mode optimized custom theme:

Copybash scripts/install-robotics-theme.sh

This:

• Copies custom CSS from assets/robotics-theme/custom.css
• Creates src/css/ directory if needed
• Applies theme to development server

Step 3: Configure Site Settings

Copy the configuration template:

Copycp assets/config-templates/docusaurus.config.template.ts docusaurus.config.ts

Edit docusaurus.config.ts with your site details:

Copyexport default {
  title: 'Your Site Title',           // Change this
  url: 'https://example.com',        // Your domain
  baseUrl: '/',                       // / for root, /project/ for subdirectory
  favicon: 'img/favicon.ico',        // Your favicon
  // ... other config
};

Key configuration options:

For detailed configuration help, see references/theming-guide.md.

Step 4: Test and Verify

Build and test locally:

Copy# Type check
pnpm run typecheck

# Build production bundle
pnpm run build

# Start development server
pnpm run start

Expected results:

• ✅ Build completes in < 30 seconds
• ✅ Development server starts on http://localhost:3000
• ✅ Dark theme applied correctly
• ✅ All pages load without errors

Bundled Resources

Scripts

• scripts/install-robotics-theme.sh - Theme installer script

Theme

• assets/robotics-theme/custom.css - Dark mode optimized stylesheet with:
  • Color palette for dark mode
  • Typography configuration
  • Code block styling
  • Table and list formatting
  • Responsive design
  • Admonition styles (note, warning, danger)

Configuration Template

• assets/config-templates/docusaurus.config.template.ts - Fully annotated configuration with:
  • Required fields (title, url, baseUrl)
  • Optional metadata
  • Theme configuration
  • Navbar and footer setup
  • Search configuration
  • Deployment target examples

Reference Guides

• references/initialization-guide.md - Complete Docusaurus setup walkthrough
• references/theming-guide.md - Custom CSS and theme customization
• references/troubleshooting-init.md - Common issues and solutions

Customization

Change Color Scheme

Edit src/css/custom.css:

Copy:root {
  --primary-color: #3b82f6;      /* Change to your brand color */
  --primary-dark: #1e40af;
  --primary-light: #60a5fa;
}

Then rebuild:

Copypnpm run clear
pnpm run start

Add Navigation Links

Edit docusaurus.config.ts navbar section:

Copynavbar: {
  items: [
    { to: '/docs/intro', label: 'Docs', position: 'left' },
    { href: 'https://github.com', label: 'GitHub', position: 'right' },
  ],
}

Enable Search

Option 1: Local search (no setup needed)

Copyplugins: [
  [
    require.resolve("@easyops-cn/docusaurus-search-local"),
    { hashed: true },
  ],
],

Option 2: Algolia DocSearch (requires API key)

Copyalgolia: {
  appId: 'YOUR_APP_ID',
  apiKey: 'YOUR_API_KEY',
  indexName: 'YOUR_INDEX',
},

Next Steps

After initialization:

1. Add Content - Create documentation files in docs/
2. Customize Navigation - Update sidebars.ts for your structure
3. Adjust Theme - Modify src/css/custom.css for your branding
4. Deploy - Use docusaurus-deployer skill to publish to GitHub Pages

Troubleshooting

Common issues:

Port 3000 already in use

Copypnpm start -- --port 3001

Changes not reflecting

Copypnpm run clear
pnpm start

Build fails

Copypnpm run typecheck        # Check for TypeScript errors
rm -rf node_modules       # Reinstall if corrupted
pnpm install
pnpm run build

For more solutions, see references/troubleshooting-init.md.

Performance Targets

• Initialization time: < 2 minutes
• Development server start: < 10 seconds
• Build time: < 30 seconds
• Page load: < 3 seconds

Tools Used

• Node.js (v18+) - JavaScript runtime
• pnpm (v8+) - Fast package manager
• TypeScript (v5+) - Type safety
• Docusaurus (v3.x) - Static site generator
• Bash - Script execution

Integration with docusaurus-deployer

This skill prepares your site for deployment with docusaurus-deployer:

1. Initialize with this skill
2. Add your content
3. Use docusaurus-deployer to publish to GitHub Pages

Workflow:

Copydocusaurus-initializer → Add content → docusaurus-deployer
        ↓                                       ↓
    Setup + Theme                        Live on GitHub Pages

Resources

• Docusaurus Official Docs
• MDX Documentation
• See bundled reference guides for detailed help