mdview

mdview

mdview renders Markdown beautifully in iTerm2, including local images at their exact positions in the document.

mdview report.md

Demo

The demo is a real Markdown document containing every supported feature, not a staged mockup:

mdview examples/showcase.md

Source: examples/showcase.md

Install

Homebrew

brew tap givemethatsewon/tap
brew install mdview

Or install directly with brew install givemethatsewon/tap/mdview.

Installer

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.0

Add $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.0

Set MDVIEW_INSTALL_DIR to install somewhere else.

Go

Go 1.25.8 or newer is required.

go install github.com/givemethatsewon/mdview@v0.1.0

Ensure 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.

Supported Markdown

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, and CAUTION

Remote image URLs remain styled links. Missing local images are reported as errors. Absolute paths and ../ paths are allowed, matching normal local Markdown behavior.

Design

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.

Extended syntax

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.

Scope

• 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.

License

MIT