---
id: ascii-guard
version: "2.3.0"
license: Apache-2.0
license_treatment: permissive
maintenance: active
---

# ascii-guard — A minimal-dependency Python linter for detecting and fixing misaligned ASCII art boxes in documentation

License: permissive · Maintenance: active · Downloads: 125.2K/mo

## What it is and what it does

ascii-guard is a linter and auto-fixer for ASCII art boxes commonly found in documentation. It detects misalignments where box borders (drawn with Unicode box-drawing characters like ─, │, ┌, ┐, └, ┘) are off by 1–2 characters, which is a frequent artifact in AI-generated diagrams. The tool validates vertical alignment of │ characters, horizontal alignment of ─ characters, corner correctness, width consistency across top/middle/bottom borders, and content fit within boxes.

It runs as both a CLI tool (lint and fix modes, with dry-run preview) and a Python library with functions like lint_file(), fix_file(), detect_boxes(), and validate_box(). The package has minimal dependencies—zero for Python 3.11+, one (tomli) for Python 3.10—and is built on the standard library, making it lightweight and fast to install and run.

Use it for:

- Validate ASCII flowcharts and diagrams in markdown documentation before publishing to catch subtle alignment errors introduced by AI tools
- Auto-fix misaligned boxes in bulk across a documentation directory using the CLI or Python API in a CI/CD pipeline
- Integrate into a documentation build process to enforce consistent ASCII art formatting without manual review
- Show intentionally broken boxes in tutorials or before/after examples using ignore markers to skip validation on specific blocks
- Detect and report all ASCII boxes in a file programmatically for custom processing or metrics collection

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Detects and fixes misaligned ASCII art boxes in documentation by validating box-drawing character alignment and automatically correcting width, corner, and border inconsistencies.

Yes. The package solves a real problem (AI-generated ASCII art misalignment) with minimal supply-chain risk, zero dependencies on modern Python, active maintenance, and a stable API. No known vulnerabilities. Install if you maintain documentation with ASCII diagrams or generate them programmatically.

## Install

pip install ascii-guard
uv add ascii-guard
poetry add ascii-guard

## Installing ascii-guard

Before you install: Low friction: pure wheel install with one optional runtime dependency (tomli) only for Python 3.10; Python 3.11+ requires no external dependencies. Active maintenance with recent commits and stable production status.

License in practice: Apache-2.0 permissive license allows use in commercial and open-source projects with minimal restrictions; attribution required but no copyleft obligations.

Quickstart:

# Install
pip install ascii-guard

# CLI: lint a file
ascii-guard lint README.md

# CLI: auto-fix with preview
ascii-guard fix --dry-run README.md

# Python API
from ascii_guard import lint_file
result = lint_file("README.md")
if result.has_errors:
    for error in result.errors:
        print(f"Line {error.line + 1}: {error.message}")

Requires Python 3.10 or later; Python 3.10 requires tomli as a runtime dependency (automatically installed).

Verify before relying:

- Whether the package handles all edge cases in nested or overlapping ASCII box structures beyond the documented flowchart examples
- Performance characteristics on large documentation files with hundreds of boxes

## Package facts

- License: Apache-2.0 (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 125.2K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

ascii art box alignment checker, documentation ascii linter, box drawing validator, ascii diagram fixer, text box alignment tool, documentation formatting linter, unicode box drawing checker, documentation-tooling, ascii-art, linting

[View on SkillFed](https://skillfed.io/packages/ascii-guard) · [View on PyPI](https://pypi.org/project/ascii-guard/)