mdv

mdv is a small, dependency-free Markdown pager for macOS terminals. It renders a practical Markdown subset with colour, paging, literal search, followable links, source line numbers, and $VISUAL/$EDITOR integration.

go build -o mdv ./cmd/mdv
install mdv /usr/local/bin/mdv
mdv README.md

The first release accepts one real .md or .markdown file and requires interactive stdin and stdout. Run mdv --help for options. Keys are shown with h inside the viewer.

Links are live. Tab and Shift-Tab move between the links in the document, Enter opens the selected one, and clicking a link opens it too. A link to another Markdown file is resolved against the directory of the file holding it and shown in the same pager; < and > go back and forward through the files visited, returning you to the line you were reading. Web and mailto links open in your default application. A link to something mdv cannot show — a missing file, a .go file, a bare #anchor — says so in the status line and leaves your place alone.

A preprocessor can rewrite a file before it is shown. -p CMD (or the MDV_PREPROCESSOR environment variable) names a command that mdv runs over each single Markdown file it opens: the file's absolute path is passed as the last argument, its bytes are fed on standard input, and whatever the command writes to standard output is rendered in place of the file. The file's path on disk is unchanged, so editing, reloading and relative links still point at the real file, and -p "" turns the environment default off for one run. The command is lexed without a shell and preprocessing never runs in diff or git mode. This is how the pager shows generated backlinks: point -p at a script that appends them as ordinary Markdown links.

mdv diff OLD NEW compares two files of any type in the same pager:

mdv -l diff old.go new.go

It shows a side-by-side view with per-file line numbers, -/+ markers, word-level highlighting inside rewritten lines, and unchanged context folded behind ⋯ N unchanged lines markers. [ and ] jump between hunks, x opens the next fold, X opens all of them, z collapses them again, and l toggles the line-number gutters. --no-split gives a classic one-column diff, --no-fold shows every line, and -U N sets the context window. Narrow terminals fall back to one column automatically.

Two Markdown files are compared as rendered Markdown: the unit is a block, so reflowing a paragraph is not a change and a one-word edit shows as one word rather than as every line below it. Unchanged blocks are drawn once at full width and only changed ones split into panes. --raw asks for the literal line diff instead, --md forces the Markdown comparison on.

mdv git compares a file's two versions in a repository:

mdv git                # the index against the working tree
mdv git --staged       # HEAD against the index
mdv git HEAD~3 README.md
mdv git v1.2..v1.3

Git supplies the file contents; mdv computes the difference itself, so folding, expansion, search and the Markdown comparison all work as they do on two files. When several files changed, they are listed in a sidebar and < and > — or the left and right arrows — move between them.

Supported Markdown includes headings, paragraphs, rules, fenced and indented code, quotes, lists and task lists, simple pipe tables, emphasis, strong, strikethrough, code spans, inline links, and bare HTTP(S) URLs. Fenced code carries coarse syntax highlighting for a fixed set of languages. Reference links, footnotes, inline HTML, complex nesting, stdin, multiple files, watching, and in-document anchors are deferred.