Docusaurus Doctor 🏥

A comprehensive diagnostic and repair tool for Docusaurus projects. Automatically detects and fixes common issues in your Docusaurus documentation.

Real Example: This tool was used to fix the Carapis Documentation - a complex Docusaurus site with multiple plugins, broken links, and MDX syntax errors.

Features

• 🔍 Frontmatter Validation - Checks and fixes YAML frontmatter issues
• 🔗 Broken Link Detection - Finds and reports broken internal/external links
• 📝 MDX Syntax Checking - Validates markdown syntax and fixes common MDX issues
• 🏗️ Build Testing - Tests your Docusaurus build process with cache clearing
• 📁 Configuration Validation - Ensures proper Docusaurus configuration
• 🧹 Cache Management - Automatically clears build cache for better diagnostics
• 🔧 Automatic Fixes - Automatically fixes common issues
• 🛡️ Safe Mode - Dry run mode to preview changes without modifying files
• 🎯 Selective Diagnostics - Run only specific checks

Quick Start

# Install globally
npm install -g docusaurus-doctor

# Or use npx
npx docusaurus-doctor

# Run in your Docusaurus project
cd your-docusaurus-project
docusaurus-doctor

Installation

npm install -g docusaurus-doctor

Or use npx:

npx docusaurus-doctor

Usage

Interactive Mode

docusaurus-doctor

This will show an interactive menu with the following options:

• 🔍 Run all checks - Run comprehensive diagnostics
• 🔧 Fix all issues - Automatically fix detected issues
• 📋 Show issues - Display found issues
• 🧹 Clear cache - Clear Docusaurus build cache
• 🚀 Build verbose - Test build process with verbose output
• 🛡️ Safe mode (dry run) - Preview fixes without making changes
• ❌ Exit - Close the application

Command Line Options

# Dry run mode (shows what would be fixed without making changes)
docusaurus-doctor --dry-run

# CI mode (runs diagnostics and exits with code 1 if issues found)
docusaurus-doctor --ci

# Run specific diagnostics
docusaurus-doctor --diagnostics frontmatter,links

What It Checks

Frontmatter Issues

• Unescaped apostrophes in quoted strings
• Unnecessary quotes around simple values
• Invalid YAML syntax
• Missing required fields (title, id)

MDX Syntax Issues

• Unescaped < characters (e.g., <2 seconds>)
• Unescaped {id} variables in URLs
• Invalid JSX syntax in markdown

Link Issues

• Broken internal links
• Broken external links
• Invalid link formats
• Plugin routing mismatches

Build Issues

• Compilation errors
• Missing dependencies
• Configuration problems
• Cache-related issues

Configuration Issues

• Missing required fields (title, url, baseUrl)
• Disabled docs plugin without alternatives
• Invalid plugin configurations

Common Fixes

MDX Syntax Errors

Problem: <2 seconds> causes MDX compilation error Fix: Automatically wraps in code blocks: `<2 seconds>`

Problem: {id} in URLs causes "id is not defined" error Fix: Replaces with [id] or escapes properly

Link Routing Issues

Problem: /quick-start link broken Fix: Suggests moving file to correct plugin folder or updating link

Problem: /parsers link broken Fix: Updates to /parsers/info/intro based on plugin structure

Image Path Issues

Problem: Missing images with /img/ paths Fix: Creates placeholder images or suggests correct paths

Safety Measures

Automatic Cache Clearing

The tool automatically clears the .docusaurus cache before running diagnostics to ensure accurate results.

Dry Run Mode

Use --dry-run or "Safe mode" to preview all changes without modifying files.

Backup Recommendations

Before running fixes, consider backing up your docs folder:

cp -r docs docs.backup

Progressive Fixes

The tool fixes issues progressively, starting with the most critical ones (YAML errors, MDX syntax) before moving to less critical issues.

Real-World Example

This tool was successfully used to fix the Carapis Documentation, which had:

• Multiple broken links due to plugin routing issues
• MDX syntax errors with unescaped < and {id} characters
• Cache-related build failures
• Complex multi-plugin Docusaurus configuration

The tool automatically:

• Fixed 50+ broken links
• Resolved MDX compilation errors
• Cleared build cache
• Restructured file organization
• Result: Successful build with only minor anchor warnings

Examples

Fix MDX Syntax Issues

# Run frontmatter check (includes MDX syntax)
docusaurus-doctor --diagnostics frontmatter

# Fix all MDX issues automatically
docusaurus-doctor --fix-all

Check Build Process

# Test if your Docusaurus project builds successfully
docusaurus-doctor --diagnostics build

Safe Mode Testing

# Preview all fixes without making changes
docusaurus-doctor
# Then select "Safe mode (dry run)"

Configuration

The tool automatically detects your Docusaurus project structure:

• Standard docs structure: ./docs/
• i18n structure: ./i18n/en/docusaurus-plugin-content-docs/
• Nested structure: ./docs/docs/ (common in monorepos)

Troubleshooting

Build Still Fails After Fixes

1. Clear cache manually: npx docusaurus clear
2. Check for remaining MDX syntax issues
3. Verify plugin configurations in docusaurus.config.ts

Links Still Broken

1. Check if files exist in correct plugin folders
2. Verify _category_.json configurations
3. Ensure proper routeBasePath settings

Permission Errors

1. Ensure write permissions to docs folder
2. Run with appropriate user permissions
3. Check for file locks

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT

Author

Mark - Unrealos.com

• Email: [email protected]
• Website: https://unrealos.com
• GitHub: @markolofsen

Keywords: docusaurus, diagnostics, mdx, markdown, documentation, static-site, build-tool, link-checker, frontmatter, yaml, broken-links, syntax-checker, docs-generator, react, typescript, automation, ci-cd, development-tools