mdview

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:

1. Open System Settings > Privacy & Security > Extensions > Quick Look 2. 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

• .md
• .markdown

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.