mdmatcha

README

mdmatcha

A terminal markdown reader with PDF-reader-style navigation.

go build -o ./bin/mdmatcha .
./bin/mdmatcha examples/demo.md

Features

• Table of contents sidebar (collapsible tree, like a PDF reader)
• Rendered, source and split views
• Tables, code blocks, task lists (GitHub-flavored markdown via glamour)
• Inline images (PNG/JPEG/GIF/WebP, local paths and http(s) URLs): pixel-perfect via the kitty graphics protocol on supporting terminals (Ghostty, Kitty, WezTerm — auto-detected), truecolor half-block art everywhere else
• Mermaid diagrams, rendered through mmdc (npm i -g @mermaid-js/mermaid-cli); without it they appear as code blocks
• Search with live highlighting and match navigation
• Mouse support: wheel scrolling per pane, click TOC entries to jump. To select/copy text, hold shift while dragging (terminal-native selection), or press m to release mouse capture entirely
• Auto-reload: the document refreshes automatically when the file changes on disk (scroll position is kept) — handy for files being written by coding agents; disable with -no-watch

Keys

Key	Action
q / ctrl+c	quit
t	toggle TOC sidebar
v	cycle view: rendered → source → split
tab	cycle focus between TOC and panes
j/k d/u f/b g/G	scroll focused pane
/	search (live), enter commit, esc clear
n / N	next / previous match
m	toggle mouse capture (off = select & copy)
r	reload file (also happens automatically)

In the TOC: enter jumps to the section (both panes), space toggles collapse, h/l collapse/expand, H/L collapse/expand all.

Flags

• -style — glamour style: auto (default), dark, light, notty, dracula, tokyo-night, pink, ascii, or a path to a JSON style file
• -graphics — image backend: auto (default, probes the terminal), kitty, halfblocks
• -graphics-probe — self-test the terminal's kitty graphics support (normal and alternate screen) and exit
• -no-images — skip image and diagram rasterization
• -no-watch — disable auto-reload when the file changes on disk

Viewing untrusted files

Document content is sanitized of terminal escape sequences before display, so a malicious file cannot retitle the window, write the clipboard, or otherwise control the terminal. Note that images referenced by http(s) URL are fetched when the document is opened, which reveals your IP address to the referenced hosts — pass -no-images to disable that.

Documentation

Overview

Command mdmatcha is a terminal markdown reader with a collapsible table of contents, rendered/source/split views, inline images and diagrams, search and mouse support.