Mermaid Fixer

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

👋 What's Mermaid Fixer

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.

😺 Why use Mermaid Fixer

• 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! ❤️

👀 Snapshots

🌠 Features & Capabilities

Core Capabilities

• 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

Advanced Features

• 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

💡 Problem Solved

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

🧠 How it works

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.

Six-Stage Processing Pipeline

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

Processing Workflow

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]

Architecture Overview

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

🖥 Getting Started

Prerequisites

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

Installation

Option 1: Install from crates.io (Recommended)

cargo install mermaid-fixer

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

mermaid-fixer --help

Option 2: Build from Source

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.

🚀 Usage

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

Basic Commands

# 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

Configuration

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

Advanced Options

# 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

📋 Command Line Options

Basic Options

• -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 Configuration Options

• --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)

Mermaid Configuration Options

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

Help Options

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

🔄 Processing Workflow

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

📈 Output Statistics

After processing, Mermaid Fixer provides comprehensive statistics:

📊 Supported Fix Types

• ✅ 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)

🔧 Example Fixes

Before Fix

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

After Fix

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

More Examples

Node ID Issues

graph LR
    Astart --> Bprocess --> Cend

Arrow Label Issues

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

🚨 Important Notes

• 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

🔍 Troubleshooting

Debug Mode

Enable verbose logging for detailed troubleshooting:

mermaid-fixer -d ./docs --verbose

🤝 Contribute

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

Ways to Contribute

• 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

⚛️ Developed with

• 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

🪪 License

MIT.

👨 About Me

🚀 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