mdview renders Markdown beautifully in iTerm2, including local images at their exact positions in the document.
mdview report.md
The demo is a real Markdown document containing every supported feature, not a staged mockup:
mdview examples/showcase.mdSource: examples/showcase.md
brew tap givemethatsewon/tap
brew trust --formula givemethatsewon/tap/mdview
brew install mdviewHomebrew requires explicit trust for formulae from non-official taps. The
command above trusts only mdview, not every formula in the tap.
Homebrew and Go are not required. This installs the verified release binary to
$HOME/.local/bin:
curl -fsSL https://raw.githubusercontent.com/givemethatsewon/mdview/v0.1.0/scripts/install.sh | sh -s -- v0.1.0Add $HOME/.local/bin to PATH if it is not already present. To inspect the
script before running it:
curl -fsSL https://raw.githubusercontent.com/givemethatsewon/mdview/v0.1.0/scripts/install.sh -o /tmp/mdview-install.sh
less /tmp/mdview-install.sh
sh /tmp/mdview-install.sh v0.1.0Set MDVIEW_INSTALL_DIR to install somewhere else.
Go 1.25.8 or newer is required.
go install github.com/givemethatsewon/mdview@v0.1.0Ensure the directory reported by go env GOBIN (or $(go env GOPATH)/bin when GOBIN is empty) is on PATH for global use.
To build a standalone binary instead:
go build -trimpath -ldflags="-s -w" -o mdview .Release assets and the Homebrew checksum workflow are documented in docs/releasing.md.
The parser supports CommonMark plus:
- GitHub-flavored tables, strikethrough, task lists, and automatic links
- ordered and unordered lists, blockquotes, fenced code, and definition lists
- local inline images, resolved relative to the Markdown file
- PHP Markdown Extra-style footnotes with superscript references
$...$inline math and$$...$$display math rendered as terminal Unicode- GitHub alerts:
NOTE,TIP,IMPORTANT,WARNING, andCAUTION
Remote image URLs remain styled links. Missing local images are reported as errors. Absolute paths and ../ paths are allowed, matching normal local Markdown behavior.
Goldmark parses the document once, with termtex math represented as dedicated AST nodes so Markdown structure and destinations remain untouched. mdview normalizes math, footnotes, and alerts inside that AST, and replaces local image nodes with unique markers. Glamour renders the complete document in one pass, after which each image marker is replaced by an iTerm2 OSC 1337;File=...;inline=1 sequence. This keeps headings, lists, tables, code blocks, extensions, and images in document order.
The Markdown pipeline talks to a small imageBackend interface. The MVP wires in only the iTerm2 implementation; a future Kitty graphics backend can be added without changing parsing, marker placement, or Markdown rendering.
Footnotes use PHP Markdown Extra syntax. References are rendered as compact Unicode superscripts while definitions remain a subtly dimmed numbered list:
A claim.[^source]
[^source]: Supporting detail.Math supports $...$ inline expressions and $$...$$ display expressions. It is rendered as Unicode terminal text by termtex; malformed or unsupported expressions remain visible as LaTeX source.
Inline: $a^2 + b^2 = c^2$
$$
\frac{-b \pm \sqrt{b^2 - 4ac}}{2a}
$$GitHub's five top-level alert types are supported: NOTE, TIP, IMPORTANT, WARNING, and CAUTION.
> [!WARNING]
> Check the generated output before publishing.- macOS and iTerm2
- one local Markdown file per invocation
- intrinsic image sizing through iTerm2's OSC 1337 protocol
- no TUI, pager, configuration file, or network fetching
The implementation follows Glow's CLI rendering path, uses Glamour v2 over Goldmark, and emits the documented iTerm2 inline image protocol.