VitePress to Docusaurus Migration Guide

This guide documents the migration from VitePress to Docusaurus for the MCP ADR Analysis Server documentation.

🎯 Migration Overview

From: VitePress v1.0.0
To: Docusaurus v3.1.0
Reason: Better React ecosystem integration, enhanced plugin system, superior MDX support, and more robust documentation features

📋 What Changed

1. Configuration Files

Removed (VitePress)

• .vitepress/config.js - VitePress configuration
• .vitepress/dist/ - VitePress build output

Added (Docusaurus)

• docusaurus.config.js - Main Docusaurus configuration
• sidebars.js - Sidebar navigation configuration
• src/css/custom.css - Custom styling
• static/img/ - Static assets directory
• build/ - Docusaurus build output (gitignored)
• .docusaurus/ - Docusaurus cache (gitignored)

2. Package Dependencies

Removed

{
  "vitepress": "^1.0.0",
  "vitepress-plugin-mermaid": "^2.0.17"
}

Added

{
  "@docusaurus/core": "^3.1.0",
  "@docusaurus/preset-classic": "^3.1.0",
  "@docusaurus/theme-mermaid": "^3.1.0",
  "@mdx-js/react": "^3.0.0",
  "react": "^18.2.0",
  "react-dom": "^18.2.0"
}

3. Scripts Updated

Old (VitePress)	New (Docusaurus)	Description
npm run dev	npm run start or npm run dev	Start development server
npm run build	npm run build	Build for production
npm run preview	npm run serve	Preview production build
N/A	npm run clear	Clear cache
N/A	npm run deploy	Deploy to GitHub Pages

4. Directory Structure

docs/
├── docusaurus.config.js          # Main config (was .vitepress/config.js)
├── sidebars.js                    # Sidebar config (new)
├── src/
│   └── css/
│       └── custom.css             # Custom styles (new)
├── static/
│   └── img/                       # Static assets (was public/)
├── tutorials/                     # Same structure
├── how-to-guides/                 # Same structure
├── reference/                     # Same structure
├── explanation/                   # Same structure
├── ide-rules/                     # Same structure
└── build/                         # Build output (was .vitepress/dist)

🚀 Migration Steps

Step 1: Install Dependencies

cd docs
npm install

This will install all Docusaurus dependencies specified in the updated package.json.

Step 2: Copy Assets

If you have custom images or assets in public/, move them to static/img/:

# If you have a public directory
cp -r public/* static/img/

Step 3: Update Markdown Files (if needed)

Most markdown files work as-is, but you may need to update:

1. Front matter - Docusaurus uses slightly different front matter:

   ---
   id: my-doc
   title: My Document
   sidebar_label: My Doc
   sidebar_position: 1
   ---

2. Internal links - Should work the same, but verify:

   [Link to tutorial](/tutorials/01-first-steps)

3. Mermaid diagrams - Already configured with @docusaurus/theme-mermaid

Step 4: Test Locally

cd docs
npm run start

Visit http://localhost:3000/mcp-adr-analysis-server/ to preview.

Step 5: Build for Production

npm run build

This creates an optimized production build in the build/ directory.

Step 6: Deploy

The GitHub Actions workflow (.github/workflows/deploy-docusaurus.yml) will automatically deploy to GitHub Pages when you push to main.

🔧 Configuration Details

Docusaurus Config (docusaurus.config.js)

Key configurations:

• Base URL: /mcp-adr-analysis-server/ (for GitHub Pages)
• Organization: tosin2013
• Project: mcp-adr-analysis-server
• Mermaid: Enabled via @docusaurus/theme-mermaid
• Search: Configured for Algolia (requires setup)

Sidebars Config (sidebars.js)

Multiple sidebars for different sections:

• mainSidebar - Complete documentation tree
• tutorialsSidebar - Tutorials only
• howToSidebar - How-to guides only
• referenceSidebar - Reference docs only
• explanationSidebar - Explanation content only

🎨 Customization

Theme Colors

Edit src/css/custom.css to customize:

:root {
  --ifm-color-primary: #646cff;
  /* ... other colors */
}

Logo and Favicon

Place files in static/img/:

• static/img/logo.png - Site logo
• static/img/favicon.ico - Favicon
• static/img/og-image.png - Social media preview

📊 Feature Comparison

Feature	VitePress	Docusaurus	Notes
Mermaid Diagrams	✅ Plugin	✅ Built-in theme	Better integration in Docusaurus
Search	✅ Local	✅ Algolia/Local	More options in Docusaurus
MDX Support	⚠️ Limited	✅ Full	React components in docs
Versioning	❌	✅	Built-in version management
i18n	⚠️ Basic	✅ Advanced	Better internationalization
Plugin System	⚠️ Limited	✅ Extensive	Rich plugin ecosystem
React Integration	❌	✅	Full React component support

🔍 Troubleshooting

Build Errors

1. Module not found errors: Run npm install in the docs/ directory
2. Port already in use: Change port with npm run start -- --port 3001
3. Cache issues: Run npm run clear to clear Docusaurus cache

Broken Links

Docusaurus has stricter link checking. Update broken links in:

• Internal links: Use relative paths from docs root
• External links: Ensure they're valid URLs

Styling Issues

1. Check src/css/custom.css for custom styles
2. Use browser DevTools to inspect and debug
3. Refer to Infima CSS framework docs

📚 Resources

• Docusaurus Documentation
• Docusaurus Migration Guide
• Mermaid Plugin
• MDX Documentation

✅ Post-Migration Checklist

• Install dependencies (npm install)
• Copy assets to static/img/
• Test locally (npm run start)
• Verify all pages load correctly
• Check internal links work
• Test Mermaid diagrams render
• Build for production (npm run build)
• Deploy to GitHub Pages
• Update repository settings for GitHub Pages
• Verify deployed site works
• Update README with new documentation links
• Archive or remove VitePress files

🎉 Benefits of Docusaurus

1. Better React Integration: Full MDX support for React components
2. Versioning: Built-in documentation versioning
3. Plugin Ecosystem: Rich plugin system for extended functionality
4. Better Search: Multiple search options including Algolia
5. Active Community: Large, active community and regular updates
6. Performance: Optimized for production with code splitting
7. Accessibility: Better a11y support out of the box
8. Customization: More flexible theming and customization options

📝 Notes

• The migration preserves all existing documentation structure
• All Diataxis framework organization remains intact
• Mermaid diagrams continue to work seamlessly
• GitHub Pages deployment is automated via GitHub Actions
• Search functionality can be enhanced with Algolia (requires API key setup)

---

Migration Date: 2025-10-04
Migrated By: Sophia (AI Assistant)
Status: ✅ Complete