Diagram Fixer

A Python tool designed to automatically fix formatting and alignment issues in ASCII diagrams, particularly those generated by AI tools like Claude. This tool is especially useful in pandoc workflows for cleaning up diagrams before converting to other formats.

Features

• Precision Matrix-Based Detection: Uses sophisticated matrix analysis to identify and fix diagram structural issues
• Box Alignment: Automatically corrects misaligned box borders and inconsistent spacing
• Connection Line Fixing: Repairs broken or misaligned connection lines between diagram elements
• Pandoc Integration: Seamlessly integrates into pandoc preprocessing workflows
• Quiet Operation: Clean, minimal output by default with optional verbose debugging
• Robust Algorithm: Handles complex nested diagrams with stable convergence

Installation

Option 1: Install from PyPI (when available)

pip install markdown-diagram-fixer

Option 2: Install from Source

git clone https://github.com/andrewyager/markdown-diagram-fixer.git
cd markdown-diagram-fixer
pip install .

Option 3: Development Install

git clone https://github.com/andrewyager/markdown-diagram-fixer.git
cd markdown-diagram-fixer
pip install -e .

Requirements

• Python 3.7 or higher
• No external dependencies (uses only Python standard library)

Usage

Command Line

After installation, use the diagram-fixer command:

# Fix a single diagram file
diagram-fixer input_diagram.txt

# Enable verbose output for debugging
diagram-fixer input_diagram.txt --verbose

If running directly from source without installation:

python3 src/precision_diagram_fixer.py input_diagram.txt

Pandoc Integration

The diagram fixer can be used as a pandoc filter to automatically fix diagrams during document processing.

Installation for Pandoc

After installing the package (pip install markdown-diagram-fixer), add the filter to your pandoc workflow:

Option 1: Use in pandoc defaults file (recommended)

Add to your pandoc defaults file (e.g., ~/.pandoc/defaults/pdf.yaml):

filters:
  - pandoc-diagram-filter

Option 2: Use direct path to installed binary

If the above doesn't work due to PATH issues, use the full path:

filters:
  - /opt/homebrew/bin/pandoc-diagram-filter  # On macOS with Homebrew
  # or find the path with: which pandoc-diagram-filter

Option 3: Use with individual pandoc commands

# Using pandoc defaults
pandoc -d pdf input.md -o output.pdf

# Or specify filter directly
pandoc --filter pandoc-diagram-filter input.md -o output.pdf

Troubleshooting Pandoc Integration

If the filter doesn't work:

1. Check installation: Verify the console script exists:

   which pandoc-diagram-filter
   

2. Test the filter directly:

   echo '```
   ┌─────┐
   │ Box │
   └─────┘
   ```' | pandoc -f gfm -t json | pandoc-diagram-filter | pandoc -f json -t markdown
   

3. Use full path if needed: In your pandoc defaults, use the full path from which pandoc-diagram-filter

See TROUBLESHOOTING.md for detailed troubleshooting help.

Command Line Integration

You can also use the preprocessor directly:

# Preprocess markdown then pass to pandoc
pandoc-diagram-fixer < input.md | pandoc -o output.pdf

How It Works

The precision diagram fixer uses a matrix-based approach:

1. Detection: Identifies diagram elements (boxes, connection lines) using Unicode box-drawing characters
2. Analysis: Builds a solved/unsolved matrix to track which positions are correctly formatted
3. Problem Identification: Finds misaligned borders, broken connections, and spacing issues
4. Targeted Fixing: Applies minimal character injections to fix problems without disrupting correctly formatted areas
5. Convergence: Iterates until the diagram reaches a stable, correctly formatted state

Supported Diagram Types

• Box and line diagrams using Unicode box-drawing characters (┌┐└┘├┤┬┴┼─│)
• Network topology diagrams
• Flowcharts and organizational charts
• System architecture diagrams
• Any ASCII art using standard box-drawing conventions

Example

Before:

┌─────────┐    ┌──────────┐
│ Source  │───│ Target   │
│ Node    │    │ Node     │
└─────────┘    └──────────┘

After: (with proper alignment)

┌─────────┐    ┌──────────┐
│ Source  │────│ Target   │
│ Node    │    │ Node     │
└─────────┘    └──────────┘

Files

• src/precision_diagram_fixer.py - Main diagram fixing tool with robust matrix-based algorithm
• src/pandoc_preprocessor.py - Pandoc preprocessor for automatic diagram fixing in markdown workflows
• example_diagram.txt - Sample diagram for testing

License

MIT License - see LICENSE file for details.

Copyright (c) 2025 Andrew Yager, Real World Technology Solutions Pty Ltd

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines on:

• Reporting issues and bugs
• Submitting pull requests
• Development setup and testing
• Code style and best practices

Security

If you discover a security vulnerability, please report it privately through GitHub Security Advisories. See SECURITY.md for details.