Skip to main content

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)

Source distribution for docalign 0.1.3
File Size Uploaded
docalign-0.1.3.tar.gz 20.6 kB Details

Built distribution (wheel)

Table of built distributions (wheels) for docalign 0.1.3
File Interpreter ABI Platform
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 log

Release 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

Release history Release notifications | RSS feed

This release

0.1.3 This release

2 release files

0.1.1

2 release files

0.1.0

2 release files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page