MarkdownViewer
A lightweight, native macOS application for viewing Markdown files with GitHub Flavored Markdown support and Mermaid diagram rendering.
Features
- Native macOS Experience: Document-based architecture with multi-window support
- GitHub Flavored Markdown: Tables, task lists, strikethrough, autolinks via cmark-gfm
- Mermaid Diagrams: Flowcharts, sequence diagrams, and more (bundled locally, no CDN)
- Quick Look Extension: Preview markdown files in Finder with spacebar
- Dark Mode: Automatic theme switching based on system appearance
- CLI PDF Export: Convert markdown to PDF from the terminal — no GUI needed
- Security Hardened: Content Security Policy, URL scheme validation
System Requirements
- macOS 13.0 (Ventura) or later
- Xcode 15+ (for building from source)
Installation
From Source
git clone https://github.com/heysamtexas/markdown-viewer
cd markdown-viewer
make install # Build, sign, and install to /Applications
Optionally create a mdview command-line shortcut:
sudo make symlink # Creates /usr/local/bin/mdview
Enable Quick Look
After installation, enable the Quick Look extension:
- Open System Settings > Privacy & Security > Extensions > Quick Look
- Enable MarkdownViewer
Or via terminal:
pluginkit -e use -i com.example.MarkdownViewer.QuickLook
qlmanage -r
Usage
GUI
- Open files: File > Open (⌘O), drag-and-drop, or double-click .md files
- Quick Look: Select a .md file in Finder and press Space
- Multiple files: Each file opens in its own window
- Print / Export PDF: ⌘P to print, ⇧⌘E to export as PDF
CLI: Export to PDF
Convert markdown files to PDF from the terminal, with full Mermaid diagram support:
mdview export document.md -o document.pdf
Or use the full app path without the symlink:
/Applications/MarkdownViewer.app/Contents/MacOS/MarkdownViewer export input.md -o output.pdf
The CLI runs headless — no window or dock icon appears.
Supported File Types
Technical Details
| Component | Technology |
|---|
| UI Framework | SwiftUI |
| Document Model | FileDocument protocol |
| Markdown Parser | cmark-gfm (Swift Package) |
| Rendering | WKWebView |
| Diagrams | Mermaid.js (bundled) |
Claude Code Plugin
MarkdownViewer includes a Claude Code plugin that adds a /mdview slash command for previewing markdown files and exporting them to PDF directly from Claude Code.
Install the Plugin
/plugin marketplace add heysamtexas/markdown-viewer
Then install the mdview plugin from the marketplace when prompted (or via /plugin).
Usage in Claude Code
/mdview README.md # Preview in the app
/mdview export README.md # Export to PDF
/mdview export README.md -o out.pdf # Export to specific path
License
MIT
Contributing
This project is maintained with agentic coding tools. See CLAUDE.md for development workflow.
heysamtexas
heysamtexas
