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 │ │
│ └──────┘ │ │ └──────┘ │
└───────────────────┘ └───────────────────┘
See all 12 checks
Tables
Aligns columns and ensures | content | spacing in cells.
| 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
Aligns the separator dash in list item 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
Definition lists
Aligns the : separator in key-value list items.
- timeout: 30s - timeout: 30s
- retries: 3 --> - retries: 3
- max-connections: 100 - max-connections: 100
Box widths
Ensures all lines in a box group have the same total length.
┌──────────────┐ ┌───────────────┐
│ Linear UI │ --> │ Linear UI │
│ (userscript)│ │ (userscript) │
└──────────────┘ └───────────────┘
Rail alignment
Aligns vertically adjacent box chars to the same column.
┌──────┬──────┐ ┌──────┬──────┐
│ │ │ │ │ │
│ │ │ --> │ │ │
│ │ │ │ │ │
└──────┴──────┘ └──────┴──────┘
Arrow alignment
Aligns standalone v/^ arrows with their source pipes.
┌──────┐ ┌──────┐
│ step │ │ step │
└──┬───┘ └──┬───┘
│ --> │
v v
┌──────┐ ┌──────┐
│ next │ │ next │
└──────┘ └──────┘
Pipe continuity
Traces from T-junctions to detect drifted connector pipes.
┌──────┬──────┐ ┌──────┬──────┐
│ src │ dest │ │ src │ dest │
└──────┴──┬───┘ └──────┬──────┘
│ --> │
│ │
│ │
┌──────┴──────┐ ┌──────┴──────┐
│ output │ │ output │
└─────────────┘ └─────────────┘
Box spacing
Ensures minimum right-side spacing between content and box wall.
┌───────────┐ ┌────────────┐
│ errors[] │ │ errors[] │
│ (strings)│ --> │ (strings) │
└───────────┘ └────────────┘
Box walls
Verifies nested box right walls match their opening/closing borders.
┌──────────────────┐ ┌──────────────────┐
│ content here │ │ content here │
│ more text │ --> │ more text │
└────────────────┘ └──────────────────┘
Box padding
Normalizes left-padding of content lines inside boxes.
┌──────────────┐ ┌──────────────┐
│validateAuth │ │ validateAuth │
│ compare with │ --> │ compare with │
└──────────────┘ └──────────────┘
Horizontal arrows
Closes gaps between arrow tips and box walls.
┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐
│ Src │────────> │ Dest │ --> │ Src │─────────>│ Dest │
└──────┘ └──────┘ └──────┘ └──────┘
Wide chars
Detects ambiguous/double-width Unicode chars in code blocks.
┌──────────┐
│ ▶ start │ --> warning: wide char '▶' (U+25B6) at col 2
│ ● status │
└──────────┘
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 checks - tables, boxes, arrows, pipes, lists (see examples above)
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
# dev alias (mdalign)
ln -s $(pwd)/.venv/bin/docalign ~/.local/bin/docalignd # install
rm ~/.local/bin/docalignd # remove
Metadata
Release files for docalign 0.1.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| docalign-0.1.3.tar.gz | 20.6 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| docalign-0.1.3-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 49.4 kB
Release files / docalign-0.1.3.tar.gz
| Download URL | docalign-0.1.3.tar.gz |
|---|---|
| Size | 20.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7c077d9ff6c71410032f14af7b504c46ee8b7b976889fe723b457277d609d581
|
|
BLAKE2b-256 checksum How to use checksums |
0ea3108793a253631f149e6ce332722537e9322781f3d4792451452afba93638
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Feb 26, 2026.
Transparency logRelease files / docalign-0.1.3-py3-none-any.whl
| Download URL | docalign-0.1.3-py3-none-any.whl |
|---|---|
| Size | 28.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b7a5ad29a8679834577ea413ac518661cdda9527ff312d7cfea8bf77af3c9c43
|
|
BLAKE2b-256 checksum How to use checksums |
205ff65fc5940572504360871e16d89c1e9e8a2675394f3252aba41ad329fc0c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Feb 26, 2026.
Transparency log