# 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.
Raw data
{
"_id": null,
"home_page": "https://github.com/andrewyager/markdown-diagram-fixer",
"name": "markdown-diagram-fixer",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "Andrew Yager <andrew@realworldtech.com.au>",
"keywords": "diagram, ascii, markdown, pandoc, formatting, alignment",
"author": "Andrew Yager",
"author_email": "Andrew Yager <andrew@realworldtech.com.au>",
"download_url": "https://files.pythonhosted.org/packages/32/9c/d97956fe005baddbc7756af04449ecc707a01db011faeed1cf0d11d447f9/markdown_diagram_fixer-1.1.1.tar.gz",
"platform": null,
"description": "# Diagram Fixer\n\nA 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.\n\n## Features\n\n- **Precision Matrix-Based Detection**: Uses sophisticated matrix analysis to identify and fix diagram structural issues\n- **Box Alignment**: Automatically corrects misaligned box borders and inconsistent spacing\n- **Connection Line Fixing**: Repairs broken or misaligned connection lines between diagram elements \n- **Pandoc Integration**: Seamlessly integrates into pandoc preprocessing workflows\n- **Quiet Operation**: Clean, minimal output by default with optional verbose debugging\n- **Robust Algorithm**: Handles complex nested diagrams with stable convergence\n\n## Installation\n\n### Option 1: Install from PyPI (when available)\n```bash\npip install markdown-diagram-fixer\n```\n\n### Option 2: Install from Source\n```bash\ngit clone https://github.com/andrewyager/markdown-diagram-fixer.git\ncd markdown-diagram-fixer\npip install .\n```\n\n### Option 3: Development Install\n```bash\ngit clone https://github.com/andrewyager/markdown-diagram-fixer.git\ncd markdown-diagram-fixer\npip install -e .\n```\n\n### Requirements\n- Python 3.7 or higher\n- No external dependencies (uses only Python standard library)\n\n## Usage\n\n### Command Line\n\nAfter installation, use the `diagram-fixer` command:\n\n```bash\n# Fix a single diagram file\ndiagram-fixer input_diagram.txt\n\n# Enable verbose output for debugging\ndiagram-fixer input_diagram.txt --verbose\n```\n\nIf running directly from source without installation:\n```bash\npython3 src/precision_diagram_fixer.py input_diagram.txt\n```\n\n### Pandoc Integration\n\nThe diagram fixer can be used as a pandoc filter to automatically fix diagrams during document processing.\n\n#### Installation for Pandoc\n\nAfter installing the package (`pip install markdown-diagram-fixer`), add the filter to your pandoc workflow:\n\n**Option 1: Use in pandoc defaults file** (recommended)\n\nAdd to your pandoc defaults file (e.g., `~/.pandoc/defaults/pdf.yaml`):\n```yaml\nfilters:\n - pandoc-diagram-filter\n```\n\n**Option 2: Use direct path to installed binary**\n\nIf the above doesn't work due to PATH issues, use the full path:\n```yaml\nfilters:\n - /opt/homebrew/bin/pandoc-diagram-filter # On macOS with Homebrew\n # or find the path with: which pandoc-diagram-filter\n```\n\n**Option 3: Use with individual pandoc commands**\n```bash\n# Using pandoc defaults\npandoc -d pdf input.md -o output.pdf\n\n# Or specify filter directly\npandoc --filter pandoc-diagram-filter input.md -o output.pdf\n```\n\n#### Troubleshooting Pandoc Integration\n\nIf the filter doesn't work:\n\n1. **Check installation**: Verify the console script exists:\n ```bash\n which pandoc-diagram-filter\n ```\n\n2. **Test the filter directly**: \n ```bash\n echo '```\n \u250c\u2500\u2500\u2500\u2500\u2500\u2510\n \u2502 Box \u2502\n \u2514\u2500\u2500\u2500\u2500\u2500\u2518\n ```' | pandoc -f gfm -t json | pandoc-diagram-filter | pandoc -f json -t markdown\n ```\n\n3. **Use full path if needed**: In your pandoc defaults, use the full path from `which pandoc-diagram-filter`\n\nSee [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for detailed troubleshooting help.\n\n#### Command Line Integration\n\nYou can also use the preprocessor directly:\n\n```bash\n# Preprocess markdown then pass to pandoc\npandoc-diagram-fixer < input.md | pandoc -o output.pdf\n```\n\n## How It Works\n\nThe precision diagram fixer uses a matrix-based approach:\n\n1. **Detection**: Identifies diagram elements (boxes, connection lines) using Unicode box-drawing characters\n2. **Analysis**: Builds a solved/unsolved matrix to track which positions are correctly formatted\n3. **Problem Identification**: Finds misaligned borders, broken connections, and spacing issues\n4. **Targeted Fixing**: Applies minimal character injections to fix problems without disrupting correctly formatted areas\n5. **Convergence**: Iterates until the diagram reaches a stable, correctly formatted state\n\n## Supported Diagram Types\n\n- Box and line diagrams using Unicode box-drawing characters (\u250c\u2510\u2514\u2518\u251c\u2524\u252c\u2534\u253c\u2500\u2502)\n- Network topology diagrams\n- Flowcharts and organizational charts\n- System architecture diagrams\n- Any ASCII art using standard box-drawing conventions\n\n## Example\n\n**Before:**\n```\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502 Source \u2502\u2500\u2500\u2500\u2502 Target \u2502\n\u2502 Node \u2502 \u2502 Node \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n```\n\n**After:** (with proper alignment)\n```\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502 Source \u2502\u2500\u2500\u2500\u2500\u2502 Target \u2502\n\u2502 Node \u2502 \u2502 Node \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n```\n\n## Files\n\n- `src/precision_diagram_fixer.py` - Main diagram fixing tool with robust matrix-based algorithm\n- `src/pandoc_preprocessor.py` - Pandoc preprocessor for automatic diagram fixing in markdown workflows\n- `example_diagram.txt` - Sample diagram for testing\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\nCopyright (c) 2025 Andrew Yager, Real World Technology Solutions Pty Ltd\n\n## Contributing\n\nWe welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on:\n\n- Reporting issues and bugs\n- Submitting pull requests\n- Development setup and testing\n- Code style and best practices\n\n## Security\n\nIf you discover a security vulnerability, please report it privately through GitHub Security Advisories. See [SECURITY.md](SECURITY.md) for details.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A tool to automatically fix formatting and alignment issues in ASCII diagrams",
"version": "1.1.1",
"project_urls": {
"Bug Reports": "https://github.com/andrewyager/markdown-diagram-fixer/issues",
"Documentation": "https://github.com/andrewyager/markdown-diagram-fixer#readme",
"Homepage": "https://github.com/andrewyager/markdown-diagram-fixer",
"Source": "https://github.com/andrewyager/markdown-diagram-fixer"
},
"split_keywords": [
"diagram",
" ascii",
" markdown",
" pandoc",
" formatting",
" alignment"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "4c9605e2a9d09618ccc01e28e7cdc290ef79944bb457752d8f5936341a0234f6",
"md5": "ccf0159544e4b49ef3a4962ff08e60bf",
"sha256": "a0c8d16ef4d92a2172f5b6bbfd0605f6f13df37352982741c509fde2ac986350"
},
"downloads": -1,
"filename": "markdown_diagram_fixer-1.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ccf0159544e4b49ef3a4962ff08e60bf",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 4940,
"upload_time": "2025-08-08T12:48:22",
"upload_time_iso_8601": "2025-08-08T12:48:22.298597Z",
"url": "https://files.pythonhosted.org/packages/4c/96/05e2a9d09618ccc01e28e7cdc290ef79944bb457752d8f5936341a0234f6/markdown_diagram_fixer-1.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "329cd97956fe005baddbc7756af04449ecc707a01db011faeed1cf0d11d447f9",
"md5": "4098d022b46009d28ccc54ac18d381dd",
"sha256": "0a6e1cc75e605f6fc8ea2ce1a655b63b65ba57218aa4d43d1d247b1174e1ba63"
},
"downloads": -1,
"filename": "markdown_diagram_fixer-1.1.1.tar.gz",
"has_sig": false,
"md5_digest": "4098d022b46009d28ccc54ac18d381dd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 13257,
"upload_time": "2025-08-08T12:48:23",
"upload_time_iso_8601": "2025-08-08T12:48:23.582091Z",
"url": "https://files.pythonhosted.org/packages/32/9c/d97956fe005baddbc7756af04449ecc707a01db011faeed1cf0d11d447f9/markdown_diagram_fixer-1.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-08 12:48:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "andrewyager",
"github_project": "markdown-diagram-fixer",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "markdown-diagram-fixer"
}
JSON
