docalign 0.1.0

Auto-fix alignment in markdown docs

Overview

CLI utility that auto-fixes alignment issues in markdown documentation files - tables, box-drawing diagrams, list descriptions, and more.

┌────────────────────────┐       ┌────────────────────────┐
│  ┌────┐   ┌────┐      │        │  ┌────┐   ┌────┐       │
│  │ A  │   │ B  │      │        │  │ A  │   │ B  │       │
│  └──┬─┘   └──┬─┘      │        │  └──┬─┘   └──┬─┘       │
│     │         │        │       │     │        │         │
│     └────┬───┘         │  -->  │     └────┬───┘         │
│           v            │       │          v             │
│     ┌──────┐           │       │     ┌──────┐           │
 │     │  C   │           │      │     │  C   │           │
│     └──────┘           │       │     └──────┘           │
└────────────────────────┘       └────────────────────────┘

More examples

Tables

| Service        | Usage                         |             | Service        | Usage                         |
|----------------|-------------------------------|             |----------------|-------------------------------|
| Linear API     | Status transitions, comments|        -->    | Linear API     | Status transitions, comments  |
| GitHub API| Repo clone, PR creation       |                  | GitHub API     | Repo clone, PR creation       |

List descriptions

- docs/repo.md - mirrors CI steps                       - docs/repo.md                    - mirrors CI steps
- docs/guides/testing-strategy.md - test suite  -->     - docs/guides/testing-strategy.md - test suite

Box widths

┌──────────────┐       ┌──────────────┐
│  Linear UI  │   -->  │  Linear UI   │
│  (userscript)│       │  (userscript)│
└──────────────┘       └──────────────┘

Rail alignment

┌──────┬──────┐       ┌──────┬──────┐
│      │      │       │      │      │
│       │     │  -->  │      │      │
│      │      │       │      │      │
└──────┴──────┘       └──────┴──────┘

Arrow alignment

┌──────┐                     ┌──────┐
│ step │                     │ step │
└──┬───┘                     └──┬───┘
   │           -->              │
     v                          v
┌──────┐                     ┌──────┐
│ next │                     │ next │
└──────┘                     └──────┘

Pipe continuity

┌──────┬──────┐              ┌──────┬──────┐
│ src  │ dest │              │ src  │ dest │
└──────┴──┬───┘              └──────┴──┬───┘
          │        -->                 │
            │                          │
          │                            │
┌─────────┴───┐              ┌─────────┴───┐
│   output    │              │   output    │
└─────────────┘              └─────────────┘

Box spacing

┌───────────┐       ┌────────────┐
│  errors[] │       │  errors[]  │
│  (strings)│  -->  │  (strings) │
└───────────┘       └────────────┘

Box walls

┌──────────────────┐       ┌──────────────────┐
│  content here    │       │  content here    │
│  more text       │  -->  │  more text       │
└────────────────┘         └──────────────────┘

Motivation

In the era of agentic engineering, documentation is the most critical artifact in any codebase. It guides both humans and AI agents. When docs are visually harmonious - with aligned columns, consistent box widths, and straight connector lines - they become easier to read, parse, and maintain by everyone.

Features

• 3 modes - check (default), auto-fix in place, or unified diff
• flexible paths - files, directories, or glob patterns (e.g. "docs/**/*.md")
• CI-friendly - exit code 0 when aligned, 1 when issues found
• 12 alignment checks:
  • Table columns - pads cells so every column matches the separator row width
  • Box widths - ensures all lines in a box group have the same total length
  • Box padding - normalizes left-padding of content lines inside boxes
  • Horizontal arrows - closes gaps between ─> / <─ arrow tips and box walls
  • Rail alignment - aligns vertically adjacent box chars to the same column
  • Arrow alignment - aligns standalone v/^ arrows; detects v/^ embedded in borders
  • Pipe continuity - traces from T-junctions to detect drifted connector pipes
  • Box spacing - ensures minimum right-side spacing between content and box wall
  • Box walls - verifies nested box right walls match their opening/closing borders
  • List descriptions - aligns the separator dash in list item descriptions
  • Definition lists - aligns the : separator in key: value list items
  • Wide chars - detects ambiguous/double-width Unicode chars in code blocks

Commands

docalign <path>                        # check-only (default) - detect issues, no writes
docalign --check <path>                # explicit check-only (same as default)
docalign --fix <path>                  # auto-fix files in place
docalign --diff <path>                 # show unified diff of what would change
docalign --verbose <path>              # show actionable hints with each error
docalign --ignore tables,pipes <path>  # skip specific checks
docalign --help                        # show help
docalign --version                     # show version

Paths can be files, directories, or glob patterns (e.g. "docs/**/*.md").

Check names for --ignore: tables, box-widths, box-padding, box-spacing, horiz-arrows, box-walls, rails, arrows, pipes, list-descs, def-lists, wide-chars.

Exit codes: 0 = all aligned, 1 = issues found.

Install

pipx install docalign
# pip install docalign

Update

pipx upgrade docalign
# pip install --upgrade docalign

Uninstall

pipx uninstall docalign
# pip uninstall docalign

Development

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest -v