$ termmd

A Markdown viewer for terminals that can do more than plain text.

GitHub crates.io Download
$ cargo install termmd
termmd rendering a Markdown document in a terminal: a heading, an inline image of coloured gradients and discs, a NOTE callout, a bordered table, and syntax-highlighted Rust.
Real output, rendered from the escape sequences termmd actually emits — including the image, drawn through the kitty graphics protocol.

## Why another one

Terminals quietly became capable. They do 24-bit colour, they draw images through three different protocols, they have clickable hyperlinks, and they know how wide a Japanese character is. Most terminal Markdown viewers were written before some of that was true, and it shows: tables come out ragged or missing, images turn into [image], CJK text overflows the margin, and a wide table is simply cut off.

Images, actually rendered

Four backends, chosen by asking the terminal what it supports: the kitty graphics protocol, iTerm2 inline images, DEC sixel, and Unicode half blocks. PNG, JPEG, GIF, WebP, BMP, TIFF and SVG — vector art rasterised at the size it will be shown, so badge text stays legible.

Remote images are opt-in

Images at an http(s) URL are not fetched by default: opening a document should not make network requests you did not ask for. Most README badges are remote, so if a picture is missing, that is usually why — and termmd says so where the image would have been, rather than leaving a gap.

Files, directories, URLs

termmd docs/ lists a directory's Markdown, each file with its first heading, as a document you can follow links out of — backspace comes back. termmd https://…/README.md fetches and renders, resolving the relative links and images inside it against where it came from.

Emoji and maths

:rocket: is drawn as a rocket, from the alias set GitHub accepts, and $E = mc^2$ as E = mc². What Unicode has no character for is left exactly as written, because TeX is still readable.

Tables that fit

Column widths are measured, not guessed. Spare room goes where it is needed; when space runs short the prose column wraps while 1.2.0 and Yes stay intact. Too narrow for a grid, and the table becomes readable records instead of a mangled box.

Typography

Text is measured in display columns over grapheme clusters, so CJK, emoji and combining accents wrap where they should. Lists hang their continuation lines under the text. GitHub alerts get their own colour and label.

A real pager

Search with live highlighting, a table of contents you can jump from, a link list, horizontal scrolling for wide tables, and live reload on save. Links to other local Markdown files open in termmd; backspace comes back.

Syntax highlighting

213 languages and 32 themes through syntect. Fence languages resolve through aliases, and a block with no language at all is sniffed from its first line.

It degrades honestly

Truecolor falls back to 256, then 16, then to bold and underline. Box drawing falls back to ASCII. Every fallback can be forced, and termmd --caps shows what was detected and why.

## The pager

Press t for the contents, / to search, L for links, i to toggle images. The mouse belongs to your terminal, so drag still selects and copies — the wheel scrolls through alternate scroll.

y copies the code block you are looking at to your clipboard, over OSC 52, which works down an ssh connection. It copies the source as written — no highlighting, no line numbers, and no trailing newline, so a shell snippet lands at your prompt instead of running itself.

The termmd pager with the table of contents panel open over a document, showing headings indented by level with the current section highlighted.

## Terminal support

Detection is by live query where possible: termmd asks the terminal what it supports and only guesses from TERM when nothing answers.

TerminalImagesColourHyperlinks
kitty, Ghostty, WezTermkitty protocoltruecoloryes
iTerm2kitty protocol (3.5+), else iTerm2 protocoltruecoloryes
foot, mlterm, xtermsixeltruecolorvaries
Windows Terminal, Konsolesixeltruecoloryes
Alacritty, Terminal.app, othershalf blocks256 or 16varies
tmux 3.4+, sixel terminalsixel, drawn by tmuxinheritedinherited
tmux otherwise, screenhalf blocksinheritedinherited

Inside tmux the terminal that answers is tmux, and it claims sixel whether or not the terminal it draws on could show one. So termmd asks tmux what it decided the client can do — #{client_termfeatures} — and takes pictures and hyperlinks from that. A client that cannot manage them keeps half blocks.

Sixel is encoded by termmd itself, quantisation included: median cut over a 15-bit histogram, Floyd–Steinberg dithering, run-length encoded output. No libsixel.

## Install

# homebrew
brew install EdMUK/tap/termmd

# from crates.io
cargo install termmd

# or the release archive, without compiling
cargo binstall termmd

# or a prebuilt binary (macOS, Linux, Windows)
curl -sSL https://github.com/EdMUK/termmd/releases/latest/download/termmd-aarch64-apple-darwin.tar.gz | tar xz
sudo install termmd-aarch64-apple-darwin/termmd /usr/local/bin/termmd
# then
termmd README.md               # interactive pager
termmd -P README.md            # print and exit
termmd --remote-images R.md    # fetch http(s) images — off by default
termmd --watch NOTES.md        # re-render on save
termmd --caps                  # what termmd detected about your terminal

termmd --completions zsh > ~/.zfunc/_termmd          # bash, fish, powershell, elvish too
termmd --man > /usr/local/share/man/man1/termmd.1

If a picture is missing

It is almost always a remote image. termmd does not fetch http(s) URLs unless you ask it to, so most README badges show a placeholder that says exactly that:

🖼 Build (remote image, run with --remote-images)
🖼 diagram.png (file not found)
🖼 photo.avif (cannot read AVIF image)

Pass --remote-images, or set remote-images = true in ~/.config/termmd/config.toml to make it the default. If images are missing for some other reason, termmd --caps reports which protocol was detected.

Piped output is plain text with no escape sequences, so termmd doc.md | grep behaves. Full options, configuration and theming are in the README.