Skip to main content

Docusaurus Conversion Checklist

Use this checklist to track your Docusaurus migration progress.

📋 Pre-Migration (Completed ✅)​

  • VitePress configuration analyzed
  • Documentation structure reviewed
  • Docusaurus configuration files created
  • Package.json updated
  • GitHub Actions workflow created
  • Migration guides written
  • Setup script created

🚀 Installation & Setup​

Step 1: Install Dependencies​

  • Navigate to docs directory: cd docs
  • Run automated setup: ./setup-docusaurus.sh
    • OR manually: npm install
  • Verify no installation errors

Step 2: Create Favicon (Optional)​

Step 3: Local Testing​

✅ Verification Tests​

Documentation Pages​

  • Home page (/) loads
  • Documentation Navigator (/diataxis-index) works
  • Quick Start (/README) displays correctly

Tutorials Section​

  • Your First MCP Analysis (/tutorials/01-first-steps)
  • Working with Existing Projects (/tutorials/02-existing-projects)
  • Advanced Analysis Techniques (/tutorials/03-advanced-analysis)

How-To Guides​

  • Troubleshoot Issues (/how-to-guides/troubleshooting)
  • Generate ADRs from PRD (/how-to-guides/generate-adrs-from-prd)
  • Work with Existing ADRs (/how-to-guides/work-with-existing-adrs)
  • Bootstrap Architecture Docs (/how-to-guides/bootstrap-architecture-docs)
  • Deploy Your Own Server (/how-to-guides/deploy-your-own-server)

Reference Documentation​

  • Complete API Reference (/reference/api-reference)
  • Usage Examples (/reference/usage-examples)

Explanation Content​

  • Understanding MCP (/explanation/mcp-concepts)
  • Server Architecture (/explanation/server-architecture)
  • Architecture Flow Diagrams (/explanation/mcp-architecture-flow)
  • AI Workflow Concepts (/explanation/ai-workflow-concepts)

IDE Rules​

  • Overview (/ide-rules/README)
  • Quickstart Guide (/ide-rules/quickstart-guide)
  • IDE-specific sections load

Features Testing​

  • Search functionality works (try searching for "ADR")
  • Dark/light theme toggle works
  • Code blocks have syntax highlighting
  • Mermaid diagrams render correctly (if any)
  • Internal links navigate correctly
  • External links open in new tabs
  • Edit on GitHub links work

🏗️ Build Testing​

Production Build​

  • Run build command: npm run build
  • Build completes without errors
  • Check build output in build/ directory
  • Verify no broken link warnings (or document them)

Preview Production Build​

  • Run serve command: npm run serve
  • Preview site loads correctly
  • Test navigation in production build
  • Verify assets load properly

🚢 Deployment​

GitHub Repository Setup​

  • Commit all Docusaurus files to git
  • Push to GitHub repository
  • Verify .github/workflows/deploy-docusaurus.yml is in repo

GitHub Pages Configuration​

  • Go to repository Settings → Pages
  • Set Source to "GitHub Actions"
  • Save settings

Deployment Verification​

🎨 Customization (Optional)​

Branding​

  • Update theme colors in src/css/custom.css
  • Replace logo if needed (static/img/logo.png)
  • Update OG image for social sharing (static/img/og-image.png)

Search Configuration​

  • Sign up for Algolia DocSearch (if desired)
  • Get API keys from https://docsearch.algolia.com/
  • Update docusaurus.config.js with Algolia credentials
  • Test Algolia search functionality

Advanced Features​

  • Set up documentation versioning (if needed)
  • Configure internationalization (if needed)
  • Add custom React components (if needed)
  • Set up blog (if desired)

🧹 Cleanup (After Successful Migration)​

Remove VitePress Files​

  • Backup VitePress config: cp -r .vitepress .vitepress.backup
  • Remove VitePress directory: rm -rf .vitepress
  • Remove VitePress from package.json devDependencies (if any)
  • Remove old deployment workflow (if exists): .github/workflows/deploy-docs.yml
  • Remove public/ directory (assets moved to static/)
  • Update .gitignore to remove VitePress entries

Update Documentation​

  • Update main README.md with new documentation URL
  • Update CONTRIBUTING.md with Docusaurus instructions
  • Create ADR for documentation platform change
  • Notify team of new documentation system

📊 Post-Migration Validation​

Performance​

  • Test page load speed
  • Verify mobile responsiveness
  • Check accessibility (a11y) with browser tools
  • Test on different browsers (Chrome, Firefox, Safari, Edge)

Monitoring​

  • Set up analytics (Google Analytics, Plausible, etc.)
  • Monitor for broken links
  • Check GitHub Actions for deployment failures
  • Review user feedback

🐛 Troubleshooting​

If you encounter issues, check:

📝 Notes & Issues​

Use this space to track any issues or notes during migration:

Date: ___________
Issue: 
Solution:

Date: ___________
Issue:
Solution:

✅ Migration Complete!​

When all items are checked:

  • All documentation pages verified
  • Production build successful
  • Deployed to GitHub Pages
  • Team notified
  • VitePress files cleaned up
  • Documentation updated

Congratulations! Your Docusaurus migration is complete! 🎉

Quick Commands Reference:

# Development
npm run start              # Start dev server
npm run build             # Build for production
npm run serve             # Preview production build
npm run clear             # Clear cache

# Deployment
git add .
git commit -m "feat: Migrate documentation to Docusaurus"
git push origin main      # Triggers auto-deployment

Documentation URLs: