A fast, native Quick Look extension for Markdown on macOS.
Press Space on a .md file in Finder and read it — rendered, highlighted, in light or dark.
- Works everywhere Quick Look does — the space-bar panel, Finder's preview pane and the column view, using the full width available.
- GitHub Flavored Markdown — tables, task lists, strikethrough, autolinks, footnotes,
> [!NOTE]alerts, heading anchors, emoji:shortcodes:, ==highlights==, front matter (shown as a table). - Syntax highlighting for 220 languages, GitHub-style colours in light mode and One Half Dark in dark mode.
- Math —
$inline$,$$display$$and```mathblocks, typeset natively with TeX-quality layout (fractions, integrals, matrices, aligned equations); what is supported. - Mermaid diagrams —
```mermaidblocks (flowchart, sequence, class, state, ER, pie, mind map, git graph and more) are drawn natively in light and dark, in the background so the document still opens instantly; see examples/diagrams.md. Diagrams that cannot be drawn stay visible as source. Rendering comes from mermaid-rs-renderer, which is young: some layouts differ from mermaid.js (Gantt dates and timelines with several events per period are known gaps). - Local images next to the file are embedded (
,<img src="logo.svg">). - Badges without the network — static shields.io badges are drawn locally in their real colours; other remote images show their description. Loading remote images can be turned on in the app.
- Light and dark follow the system appearance.
- Clickable links — headings scroll, links to other Markdown files open them.
- Finder thumbnails — icons show a miniature of the rendered page.
- Private by design — no web engine, no JavaScript, no network requests, sandboxed.
There is no web engine. A Rust core (comrak + syntect) parses the Markdown into a compact layout, and the Swift extension draws it with TextKit, the text system behind every Mac app. Math is typeset with SwiftMath, extended with KaTeX symbols, aliases and environments; see docs/math.md for what is supported.
| Native (default) | WebKit (optional) | |
|---|---|---|
| Typical README, request → ready | ~30 ms | ~200 ms |
| 900 KB changelog, first screen | ~60 ms | ~300 ms |
- Long documents show their first screenful immediately; the rest is laid out in the background.
- Syntax highlighting grammars are pre-processed at build time so their regexes compile 3–5× faster, and common languages are compiled on all cores while macOS launches the extension.
- Light and dark colours, including code, switch instantly with the system appearance.
More on how this works: Previewing Markdown on macOS in 30 ms: a Rust core and TextKit, no web engine.
Homebrew:
brew install --cask armamut/tap/md-quicklookOne line (downloads the latest release into /Applications):
curl -fsSL https://raw.githubusercontent.com/armamut/md-quicklook/main/scripts/install.sh | bashManually: download MD-QuickLook-x.y.z.zip from Releases, move MD QuickLook.app to /Applications and open it once. The app is not notarized, so remove the quarantine flag first:
xattr -dr com.apple.quarantine "/Applications/MD QuickLook.app"From source (needs Rust and the Xcode Command Line Tools — full Xcode is not required):
git clone https://github.com/armamut/md-quicklook.git
cd md-quicklook
make installOpening the app registers the extensions; after that it can be closed. If previews do not appear, check that MD QuickLook is enabled in System Settings ▸ General ▸ Login Items & Extensions ▸ Quick Look, then click Reset Quick Look in the app.
Open the app and click Check Now (or MD QuickLook ▸ Check for Updates…). When a newer release exists, Install and Relaunch downloads it from this repository's releases, verifies it and replaces the app in place. With Check for updates automatically on (the default), the app also looks once a day when you open it. Only the app does this: the Quick Look extensions never use the network. Running the one-line installer again also updates.
make uninstall # or drag the app to the Trashcore/ Rust: Markdown → native layout or HTML (static library + `mdql` CLI)
macos/ Swift: host app (with the updater), preview and thumbnail extensions,
native renderer (macos/Native), vendored SwiftMath (macos/Vendor)
scripts/ build.sh (Xcode-free build), install.sh, icon and screenshot helpers
The extensions read the file and call the Rust core through a small C API (core/include/mdql.h). mdql_render_native returns a binary layout — text plus blocks, paragraphs and styled runs — that macos/Native turns into an attributed string with text blocks (quotes, alerts, code), tables and attachment cells (images, formulas, diagrams, badges, checkboxes); mdql_render_mermaid draws a diagram. Both extensions share one library with all this code (Contents/Frameworks/libMDQuickLookCore.dylib); their own executables only start it (macos/Launchers). mdql_render_html produces a self-contained HTML page for the optional WebKit renderer, which can be chosen in the app.
Useful while developing:
make test # Rust tests
make bench # render timing
make snapshot-tool && build/native-snapshot README.md out.png dark # native render → PNG
build/math-coverage notes.md --list # formulas that do not typeset
core/target/release/mdql README.md -o out.html --theme dark
log stream --predicate 'subsystem == "io.github.armamut.mdquicklook"' # extension timingsBuilt by armamut together with Claude Code (Claude Opus 5.5 by Anthropic). Third-party components are listed in THIRD_PARTY_NOTICES.md.