markdown-diagram-fixer 1.1.1
A tool to automatically fix formatting and alignment issues in ASCII diagrams
License: MIT
Requires Python: >=3.7
Keywords: diagram, ascii, markdown, pandoc, formatting, alignment

# 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)
```bash
pip install markdown-diagram-fixer
```

### Option 2: Install from Source
```bash
git clone https://github.com/andrewyager/markdown-diagram-fixer.git
cd markdown-diagram-fixer
pip install .
```

### Option 3: Development Install
```bash
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:

```bash
# 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:
```bash
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`):
```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:
```yaml
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**
```bash
# 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:
   ```bash
   which pandoc-diagram-filter
   ```

2. **Test the filter directly**: 
   ```bash
   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](TROUBLESHOOTING.md) for detailed troubleshooting help.

#### Command Line Integration

You can also use the preprocessor directly:

```bash
# 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](LICENSE) file for details.

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

## Contributing

We welcome contributions! Please see [CONTRIBUTING.md](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](SECURITY.md) for details.