mdreview

Terminal UI for reviewing markdown documents with inline comments. Built with Python and Textual.

Features

• Inline comments — select line ranges and add comments, stored in sidecar .review.json files
• Review workflow — approve or request changes on each file, with exit codes for CI integration
• Diff between rounds — see what changed since your last review decision
• Mermaid diagrams — ASCII rendering in the terminal, or open in mermaid.live
• Anchor drift — comments follow content when lines are added, removed, or moved
• Live reload — files reload automatically when modified externally
• Multi-file — review multiple files or an entire directory in one session

Installation

# From PyPI
pip install mdreview

# Or with uv
uv tool install mdreview

# Or with pipx
pipx install mdreview

# From source
uv tool install git+https://github.com/lazyoft/mdreview.git

Usage

# Review a single file
mdreview document.md

# Review multiple files
mdreview chapter1.md chapter2.md chapter3.md

# Review all markdown files in a directory
mdreview --dir docs/

Keybindings

Customizing Keybindings

All keybindings can be customized via a TOML config file. Run:

mdreview --config

This creates ~/.config/mdreview/keys.toml (pre-populated with all defaults) and opens it in your $EDITOR. Edit any key and save — changes take effect next time you launch mdreview.

Example customization:

[keys]
quit = "x"
approve = "a"
cursor_up = "k"
cursor_down = "j"

Exit Codes

Development

# Clone and install in dev mode
git clone https://github.com/lazyoft/mdreview.git
cd mdreview
uv venv && uv pip install -e ".[test]"

# Run tests
uv run pytest

# Lint
uv run ruff check src/

See CONTRIBUTING.md for more details.

License

MIT