English | 中文

🔧 High-performance AI-driven Mermaid diagram syntax fixer built with Rust

📊 Automatically detects and fixes syntax errors in Mermaid diagrams within Markdown files

🚀 Help me develop this software better by sponsoring on GitHub

Mermaid Fixer is a high-performance AI-driven tool that automatically detects and fixes syntax errors in Mermaid diagrams within Markdown files. Built with Rust for performance and reliability, Mermaid Fixer helps teams maintain accurate and valid Mermaid diagrams with minimal effort.

Mermaid Fixer employs a multi-stage workflow combining static syntax validation with AI-powered intelligent fixing. The system render mermaid in a JS sandbox environment to validate sytax correctness​ and integrates with large language models (LLMs) to intelligently repair broken diagrams while preserving their original intent and structure.

• Save hours on manual diagram debugging
• Keep Mermaid diagrams syntactically correct
• Maintain documentation quality automatically
• Fix complex syntax issues intelligently

🌟 For:

• Technical documentation teams
• Open source projects with diagrams
• Enterprise software developers
• Anyone who uses Mermaid in Markdown!

❤️ Like Mermaid Fixer? Star it 🌟 or Sponsor Me! ❤️

• Automated Scanning: Recursively scans directories for Markdown files
• Precise Detection: Uses JS sandbox environment for accurate syntax validation
• AI-Powered Fixing: Leverages LLMs to intelligently repair syntax errors
• Comprehensive Reporting: Provides detailed before/after comparisons
• Flexible Configuration: Supports multiple LLM providers and custom settings

• Dry-run mode for safe testing
• Verbose logging for detailed insights
• Configurable timeout and retry mechanisms
• Support for various Mermaid diagram types
• Intelligent node ID normalization
• Smart text label cleaning

The Mermaid diagram dilemma:

• Broken diagrams that don't render
• Time-consuming manual syntax debugging
• Inconsistent diagram formatting
• Complex syntax rules hard to remember

Mermaid Fixer solves this by:

• Automatically detecting syntax errors
• Intelligently fixing broken diagrams
• Maintaining diagram semantics while fixing syntax
• Providing clear feedback on changes made

Mermaid Fixer's processing workflow is divided into six distinct stages: scanning, extraction, validation, fixing, re-validation, and saving. Each stage is optimized for performance and accuracy.

1. Scanning Stage: Recursively discovers all Markdown files in the target directory
2. Extraction Stage: Parses Markdown files and extracts Mermaid code blocks
3. Validation Stage: Uses JS sandbox environment to validate each diagram's syntax
4. Fixing Stage: Employs AI to repair invalid diagrams while preserving intent
5. Re-validation Stage: Ensures fixed diagrams are syntactically correct
6. Saving Stage: Updates files with corrected diagrams

flowchart TD
    A[Directory Scanner] --> B[Markdown Parser]
    B --> C[Mermaid Extractor]
    C --> D[Syntax Validator]
    D --> E{Valid?}
    E -->|Yes| F[Skip Block]
    E -->|No| G[AI Fixer]
    G --> H[Re-validate]
    H --> I{Fixed?}
    I -->|Yes| J[Update Content]
    I -->|No| K[Log Error]
    F --> L[Next Block]
    J --> L
    K --> L
    L --> M{More Blocks?}
    M -->|Yes| D
    M -->|No| N[Save File]

graph LR
    subgraph Input Phase
        A[CLI Args] --> B[Config Loader]
        B --> C[Directory Scanner]
    end
    subgraph Processing Phase
        C --> D[Markdown Scanner]
        D --> E[Mermaid Extractor]
        E --> F[Syntax Validator]
        F --> G[AI Fixer]
    end
    subgraph Output Phase
        G --> H[File Writer]
        H --> I[Statistics Reporter]
    end

• Rust (version 1.70 or later)
• Cargo
• Internet connection (for LLM integration)
• LLM API key (OpenAI, etc.)

cargo install mermaid-fixer

After installation, you can use mermaid-fixer command directly:

mermaid-fixer --help

1. Clone the repository:

   git clone https://github.com/sopaco/mermaid-fixer.git

2. Navigate to the project directory:

   cd mermaid-fixer

3. Build the project:

   cargo build --release

4. The compiled binary will be available in the target/release directory.

Mermaid Fixer provides a command-line interface for fixing Mermaid diagrams. Here are some basic usage examples:

# Fix Mermaid diagrams in current directory
mermaid-fixer -d .

# Scan specific directory
mermaid-fixer -d /path/to/your/docs

# Dry run (detect only, no fixes)
mermaid-fixer -d ./docs --dry-run

# Verbose output
mermaid-fixer -d ./docs --verbose

Create a config.toml file in your project root:

[llm]
provider = "openai"
model = "gpt-4"
api_key = "your-api-key-here"  # or set via environment variable
max_tokens = 4000
temperature = 0.1

[mermaid]
timeout_seconds = 30
max_retries = 3

# Custom LLM configuration
mermaid-fixer -d ./docs --llm-provider openai --llm-model gpt-5-mini --max-tokens 8192

# Custom and retries
mermaid-fixer -d ./docs --max-retries 5

# Custom config file
mermaid-fixer -d ./docs --config custom-config.toml

• -d, --directory <DIR>: Target directory to scan (required)
• -c, --config <FILE>: Configuration file path (default: config.toml)
• --dry-run: Detect issues only, don't perform fixes
• -v, --verbose: Enable detailed logging output

• --llm-provider <PROVIDER>: LLM provider (openai)
• --llm-model <MODEL>: LLM model name
• --llm-api-key <KEY>: LLM API key
• --llm-base-url <URL>: LLM API base URL
• --max-tokens <NUM>: Maximum token count
• --temperature <NUM>: Temperature parameter (0.0-1.0)

• --timeout-seconds <NUM>: Mermaid validation timeout (seconds)
• --max-retries <NUM>: Maximum retry attempts

• -h, --help: Show help information
• -V, --version: Show version information

1. Scanning Stage: Recursively scan specified directory for .md and .markdown files
2. Extraction Stage: Extract Mermaid code blocks from Markdown files
3. Validation Stage: Validate each code block syntax using JS sandbox environment
4. Fixing Stage: Use AI to repair invalid code blocks
5. Re-validation: Verify that fixed code is syntactically correct
6. Saving: Write corrected content back to original files

After processing, Mermaid Fixer provides comprehensive statistics:

• ✅ Node ID normalization (remove special characters, ensure valid naming)
• ✅ Node text cleaning (remove special symbols in brackets)
• ✅ Arrow label normalization (quote Chinese labels)
• ✅ Syntax structure repair (diagram type declarations, arrow syntax)
• ✅ Style declaration fixes (color formats, property syntax)

graph TD
    A[获取数据] --> B{验证响应状态(status)}
    B -- "是" --> C[记录成本与耗时]
    B -- "否" --> D[错误处理]

graph TD
    A[获取数据] --> B{验证响应状态_Status}
    B -- "是" --> C[记录成本与耗时]
    B -- "否" --> D[错误处理]

graph LR
    Astart --> Bprocess --> Cend

flowchart TD
    A --> B
    B -- "成功" --> C
    B -- "失败" --> D

• Ensure stable internet connection for LLM API access
• Processing large numbers of files may incur API costs
• Recommend using --dry-run mode first on important documents
• Tool automatically skips common build directories (node_modules, target, etc.)
• Backup your files before running fixes on critical documentation

Enable verbose logging for detailed troubleshooting:

mermaid-fixer -d ./docs --verbose

Help improve Mermaid Fixer by reporting bugs or submitting feature requests through GitHub Issues.

• Syntax Pattern Enhancement: Improve detection of various Mermaid syntax errors
• AI Prompt Optimization: Enhance the AI fixing prompts for better results
• LLM Provider Support: Add support for additional LLM providers
• Performance Optimization: Enhance processing speed and memory usage
• Test Coverage: Add comprehensive test cases for various diagram types
• Documentation: Improve documentation and examples

• rust - Systems programming language for performance and safety
• headless_chrome - A high-level API to control headless Chrome or Chromium over the DevTools Protocol
• clap - Command line argument parser
• serde - Serialization framework
• tokio - Asynchronous runtime for Rust
• reqwest - HTTP client for LLM API calls

MIT.

🚀 Help me develop this software better by sponsoring on GitHub

An experienced software developer passionate about developer tools and automation. Currently focused on building high-performance tools that improve developer productivity and code quality.

GitHub: sopaco