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

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

docalign-0.1.3.tar.gz (20.6 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

docalign-0.1.3-py3-none-any.whl (28.9 kB view details)

Uploaded Python 3

File details

Details for the file docalign-0.1.3.tar.gz.

File metadata

  • Download URL: docalign-0.1.3.tar.gz
  • Upload date:
  • Size: 20.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for docalign-0.1.3.tar.gz
Algorithm Hash digest
SHA256 7c077d9ff6c71410032f14af7b504c46ee8b7b976889fe723b457277d609d581
MD5 4966151b583140323e7401c62fb17992
BLAKE2b-256 0ea3108793a253631f149e6ce332722537e9322781f3d4792451452afba93638

See more details on using hashes here.

Provenance

The following attestation bundles were made for docalign-0.1.3.tar.gz:

Publisher: release.yml on lucasvtiradentes/doc-align

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file docalign-0.1.3-py3-none-any.whl.

File metadata

  • Download URL: docalign-0.1.3-py3-none-any.whl
  • Upload date:
  • Size: 28.9 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for docalign-0.1.3-py3-none-any.whl
Algorithm Hash digest
SHA256 b7a5ad29a8679834577ea413ac518661cdda9527ff312d7cfea8bf77af3c9c43
MD5 05d6738dad5f20a61f82b2e229aa0a20
BLAKE2b-256 205ff65fc5940572504360871e16d89c1e9e8a2675394f3252aba41ad329fc0c

See more details on using hashes here.

Provenance

The following attestation bundles were made for docalign-0.1.3-py3-none-any.whl:

Publisher: release.yml on lucasvtiradentes/doc-align

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.1.3 This release

2 files

0.1.1

2 files

0.1.0

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page