Docusaurus Initializer

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

What This Skill Does

Project Initialization - Scaffold new Docusaurus projects with pnpm and TypeScript
Custom Theme Installation - Apply dark mode optimized theme for technical content
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:

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

This creates:

my-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:

pnpm 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:

bash 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:

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

Edit docusaurus.config.ts with your site details:

export 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:

| Option | Purpose | Example | |--------|---------|---------| | title | Browser tab title | "My Documentation" | | url | Production domain | "https://docs.example.com" | | baseUrl | URL path | "/" or "/docs/" | | favicon | Tab icon | "img/favicon.ico" |

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

Step 4: Test and Verify

Build and test locally:

# 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:

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

Then rebuild:

pnpm run clear
pnpm run start

Add Navigation Links

Edit docusaurus.config.ts navbar section:

navbar: {
  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)

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

Option 2: Algolia DocSearch (requires API key)

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

Next Steps

After initialization:

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

Troubleshooting

Common issues:

Port 3000 already in use

pnpm start -- --port 3001

Changes not reflecting

pnpm run clear
pnpm start

Build fails

pnpm 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:

Initialize with this skill
Add your content
Use docusaurus-deployer to publish to GitHub Pages

Workflow:

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

Resources

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