mdtf — Markdown Table Formatter

A Rust CLI tool that normalizes markdown tables in-place, padding every column to equal width.

Installation

Download a pre-built binary (recommended)

Grab the latest release for your platform from the releases page:

macOS (Apple Silicon)

curl -L https://github.com/paradise-runner/markdown-table-formatter/releases/latest/download/mdtf-macos-aarch64 -o mdtf
chmod +x mdtf
sudo mv mdtf /usr/local/bin/

macOS (Intel)

curl -L https://github.com/paradise-runner/markdown-table-formatter/releases/latest/download/mdtf-macos-x86_64 -o mdtf
chmod +x mdtf
sudo mv mdtf /usr/local/bin/

Linux (x86_64)

curl -L https://github.com/paradise-runner/markdown-table-formatter/releases/latest/download/mdtf-linux-x86_64 -o mdtf
chmod +x mdtf
sudo mv mdtf /usr/local/bin/

Windows (x86_64)

Download mdtf-windows-x86_64.exe from the releases page and add it to a directory on your PATH.

Build from source

Requires Rust (edition 2024).

git clone https://github.com/paradise-runner/markdown-table-formatter.git
cd markdown-table-formatter
cargo install --path .

This compiles and installs mdtf into ~/.cargo/bin/, which is on your PATH if you installed Rust via rustup.

Usage

mdtf <markdown-file>
mdtf --watch <markdown-file>
mdtf --watch --watch-delay <ms> <markdown-file>

One-shot

mdtf README.md

Reads the file, formats all tables, writes it back in-place, and prints a confirmation message.

Watch mode

mdtf --watch notes.md

Watches the file for changes and re-formats on every save. The default debounce delay is 500ms; override it with --watch-delay:

mdtf --watch --watch-delay 1000 notes.md

What it does

Given a messy table like:

| Name | Age |
| --- | --- |
| Alice | 30 |
| Bob | 25 |

mdtf rewrites it as:

| Name  | Age |
| ----- | --- |
| Alice | 30  |
| Bob   | 25  |

Rules:

• Cell content is trimmed of surrounding whitespace
• Each column is padded to the width of its widest cell (header or data)
• The separator row is rewritten with dashes filling the column width
• Non-table lines pass through unchanged
• Multiple tables in the same file are all formatted

Validation

mdtf exits with code 1 (without modifying the file) if any table is malformed:

• Separator row is missing or contains unexpected characters
• Separator row has a different column count than the header
• Any data row has a different column count than the header

The error message includes the line number of the offending table.

Development

cargo build --release   # binary at target/release/mdtf
cargo test

License

MIT — see LICENSE.

Dependencies

• notify-debouncer-mini — file watching in --watch mode