Termdown

中文文档

Render Markdown with large-font headings in the terminal using the Kitty graphics protocol.

Motivation

Inspired by glow and mdfried.

glow is a great terminal Markdown renderer, but headings are only distinguished by ANSI bold/color -- they can't actually be displayed at a larger size. mdfried supports image-rendered headings, but requires entering a TUI.

termdown rasterizes H1-H3 headings as PNG and paints them via the Kitty graphics protocol. Two modes share the same renderer:

• Interactive TUI (default when a file is given) -- vim-style browser with search, Table of Contents, and link-follow navigation for longer documents.
• Direct output (--cat, or automatic when stdout is piped / input comes from stdin) -- dump rendered Markdown straight into your terminal.

H4-H6 headings always fall back to ANSI bold text.

Installation

From crates.io (recommended, requires Rust)

cargo install termdown

Installs into ~/.cargo/bin/. Requires Rust 1.95+.

Prebuilt binary (no Rust toolchain needed)

curl -fsSL https://raw.githubusercontent.com/rrbe/termdown/master/install.sh | bash

Defaults to /usr/local/bin. Override the target directory with TERMDOWN_INSTALL_DIR.

Manual download (no script)

TARGET=aarch64-apple-darwin
BASE="https://github.com/rrbe/termdown/releases/latest/download"

curl -LO "${BASE}/termdown-${TARGET}.tar.gz"
curl -LO "${BASE}/SHA256SUMS"
grep "termdown-${TARGET}.tar.gz" SHA256SUMS | shasum -a 256 -c -

tar xzf "termdown-${TARGET}.tar.gz"
sudo mv termdown /usr/local/bin/

From git (latest development snapshot)

cargo install --git https://github.com/rrbe/termdown

Uninstall

curl -fsSL https://raw.githubusercontent.com/rrbe/termdown/master/uninstall.sh | bash

Manual uninstall

rm $(which termdown)
rm -rf ~/.config/termdown

Usage

# Open a file in the interactive TUI (default)
termdown README.md

# Plain cat-style output (non-interactive, pipe-friendly)
termdown --cat README.md
cat notes.md | termdown

# Pick a theme; show help
termdown --theme light README.md
termdown --help

The full CLI reference, TUI key bindings, configuration, and known issues live in the Usage Guide. Configuration is optional and lives at ~/.config/termdown/config.toml -- see config.example.toml for every default.

Terminal Support

Requires a terminal with Kitty graphics protocol support:

• Ghostty
• Kitty
• WezTerm
• iTerm2

On unsupported terminals, termdown prints a warning and heading images may not display correctly. H4-H6 headings always render as plain ANSI bold text.

License

Apache-2.0