A minimal, native macOS Markdown viewer with Quick Look — fast, offline, free
Double-click any .md file for a beautifully rendered preview, or press Space in Finder for instant Quick Look. GitHub-flavored Markdown, math, and Mermaid — all rendered natively. No editor overhead, no setup, no network. Just read.
繁體中文 | English
Main window — GitHub-style rendering with TOC sidebar, automatic light / dark theme
 |
 |
Quick Look — press Space on any .md file in Finder for an instant preview
macOS has no built-in way to read Markdown — open a .md file in Preview and you'll see raw text. MDViewer fills that gap: a native, focused reader that renders .md beautifully when you double-click a file or press Space in Finder.
Similar tools:
- Just need Quick Look? QLMarkdown is an open-source Quick Look extension. MDViewer includes Quick Look too, plus a standalone reader window with TOC sidebar, find-in-page, PDF/HTML export, and zoom.
- Writing Markdown? Try Obsidian, Typora, iA Writer, MacDown, or VS Code. Keep MDViewer as your default
.mdviewer, pick any of them as your external editor inside MDViewer, and press ⇧⌘E to open the current file there — MDViewer live-refreshes when you save.
- GitHub-style rendering — headings, tables, task lists, strikethrough, blockquotes
- Syntax highlighting — common languages via highlight.js
- Math formulas —
$...$inline,$$...$$display, and```mathcode blocks via Temml (MathML) - Mermaid diagrams — flowcharts, sequence diagrams, etc. (lazy-loaded)
- Footnotes —
[^1]syntax with clickable back-references - Emoji shortcodes —
:rocket:→ 🚀 - Quick Look — press Space in Finder to preview any
.mdfile, with inline local images - TOC sidebar — collapsible heading navigation with click-to-scroll
- In-page find — ⌘F opens a find bar with match highlighting and next/previous navigation
- History & tab restoration — ⌘Y opens a searchable history of recently opened files. Optional "Restore tabs on launch" setting reopens the previous session's tabs automatically.
- Export — save as PDF or self-contained HTML (all JS/CSS inlined), or print via system dialog
- Copy as Markdown — right-click or ⇧⌘C copies the original Markdown source of the current selection (block-level granularity); pastes cleanly into GitHub, Slack, or any Markdown editor. Empty selection is a no-op.
- Code block copy — every rendered code block has a one-click copy button in its corner
- Check for updates — menu item that compares against the latest GitHub release
- CJK support — full UTF-8 including Chinese, Japanese, Korean
- Offline — all dependencies bundled, zero network requests (except manual update check)
| Shortcut | Action |
|---|---|
| ⌘O | Open file dialog |
| ⇧⌘E | Open in external editor |
| ⌘E | Export as PDF |
| ⌘P | |
| ⇧⌘C | Copy selection as Markdown |
| ⌘F | Find in page |
| ⌘, | Toggle settings panel |
| ⇧⌘S | Toggle TOC sidebar |
| ⌘Y | Show file history |
| ← / → | Collapse / expand TOC heading |
| ⌘+ / ⌘− | Zoom in / out |
| ⌘0 | Actual size |
| Space (in Finder) | Quick Look preview |
brew tap ff2248/mdviewer
brew install --cask mdviewer➡ On first launch, see Approve first launch below.
Download the latest MDViewer-vX.Y.Z.dmg from Releases, open it, and drag MDViewer.app to /Applications.
➡ On first launch, see Approve first launch below.
Requires macOS 14+, Xcode 16+, and xcodegen (brew install xcodegen).
git clone https://github.com/ff2248/md-viewer.git
cd md-viewer
make installNo approval step needed — locally built apps bypass Gatekeeper (they never carry the quarantine flag).
MDViewer is distributed with ad-hoc signing and is not notarized through the Apple Developer Program. When macOS downloads the DMG (via Homebrew or directly) it attaches a quarantine flag, and Gatekeeper blocks the first launch. Since macOS Sequoia the right-click "Open" bypass no longer works — pick one:
- System Settings (recommended): open System Settings → Privacy & Security, scroll to the Security section, click Open Anyway, then confirm with your password.
- Terminal one-liner:
xattr -dr com.apple.quarantine /Applications/MDViewer.app
You only need to do this once per version.
| Method | Command |
|---|---|
| Homebrew | brew upgrade mdviewer |
| DMG | Download the new DMG and replace /Applications/MDViewer.app |
| Source | git pull && make install |
| Method | Command |
|---|---|
| Homebrew | brew uninstall mdviewer |
| DMG | Drag /Applications/MDViewer.app to the Trash |
| Source | make uninstall |
| Method | How |
|---|---|
| Double-click | Open any .md file (after setting as default) |
| Drag & drop | Drop a .md file onto the app window |
| CLI | open -a MDViewer yourfile.md |
Right-click any .md file → Get Info → Open With → select MDViewer → Change All.
Main app parses Markdown to HTML via cmark-gfm in Swift, pre-renders syntax highlighting (highlight.js) and math (Temml → MathML) via JavaScriptCore, then injects the result into a pre-loaded WKWebView. No JavaScript runs in the browser except Mermaid, which requires DOM.
Quick Look extension uses the QLPreviewReply data-based API — it returns self-contained HTML with all JS/CSS inlined for the system to render inside its sandbox.
The Shared/ directory holds the rendering pipeline and web resources used by both the app and the Quick Look extension, so previews and the main window stay visually identical.
make test # Run tests
make format # Format Swift code (requires: brew install swiftformat)MIT — see ThirdPartyNotices.txt for bundled dependencies.