QuickMD

Lightning-fast native macOS Markdown viewer

Features • Installation • Usage • Tech Stack • Support

---

Overview

QuickMD is the fastest, most elegant Markdown viewer for macOS. Double-click any .md file and instantly see beautifully rendered content. No Electron bloat, no loading screens—just pure native macOS performance.

Perfect for developers, writers, students, and anyone who works with Markdown daily. Think of it as the Preview.app equivalent for Markdown files.

Features

⚡ Blazing Fast

• Opens in milliseconds—no loading screens
• Native SwiftUI app—lightweight
• Lazy native rendering—even 10,000+ line documents open without freezing the UI

🔁 Companion to Your Editor

• ✅ Auto-reload — the document refreshes the moment your editor saves it. Enable auto-save in VS Code/Cursor/Zed and QuickMD becomes a live preview
• ✅ Open in External Editor (⌘E) — one-click handoff to VS Code, Cursor, Sublime, Zed, Typora, Obsidian and more (auto-detected; configurable in Settings)
• ✅ Copy button on code blocks — hover and click, like on GitHub
• ✅ Mermaid zoom — open any diagram in a pinch-to-zoom viewer

📝 Complete Markdown Support

• ✅ Headers, bold, italic, strikethrough (ATX # and setext underline styles)
• ✅ Tables with proper column alignment
• ✅ Code blocks with syntax highlighting
• ✅ LaTeX math — display ($$...$$) and inline ($...$) with TeX-quality rendering
• ✅ Mermaid diagrams — flowcharts, sequence, pie, class diagrams and more
• ✅ Footnotes — [^id] references with definitions at end of document
• ✅ Task lists with checkboxes (- [ ] / - [x])
• ✅ Nested lists (ordered and unordered)
• ✅ Images (local and remote URLs)
• ✅ Links (inline, reference-style, autolinks)
• ✅ Nested blockquotes with level indicators
• ✅ Horizontal rules
• ✅ YAML frontmatter (rendered as a neutral code block)
• ✅ Windows (CRLF) and legacy line endings, UTF-16/Latin-1 fallbacks

🔍 Navigation & Search

• Find in document (⌘F) with match count and per-word navigation
• Word-level highlighting across all block types (text, code, tables, blockquotes)
• Table of Contents sidebar (⌘⇧T) — auto-generated from headings
• Copy entire document (⌘⇧C) or individual sections (hover heading → copy icon)
• Export to PDF (⌘⇧E) and Print (⌘P)

🎨 Custom Themes

• 7 built-in themes: Auto, Solarized Light/Dark, Dracula, GitHub, Gruvbox Dark, Nord
• User themes from disk — drop a JSON file into ~/Library/Containers/pl.falami.studio.QuickMD/Data/Library/Application Support/QuickMD/Themes/ (or use the Import Theme… button in Settings). Live reload, no restart. See docs/themes/ for the schema and examples.
• Settings panel (⌘,) with color previews
• Theme persists across app restarts

💻 Developer-Friendly

• Syntax highlighting for 10+ languages (Swift, Python, JavaScript, Go, Rust, etc.)
• Perfect for README files and documentation
• Handles AI-generated markdown perfectly
• Dark mode that follows system settings (or choose a fixed theme)

🔒 Privacy Focused

• No analytics, no tracking
• Works completely offline (except for remote images)
• Your files stay on your device
• Open source—see exactly what the code does

Screenshots

Dark Mode	Light Mode
Syntax Highlighting	Theme Picker (Dracula)

More screenshots

Tables & Lists	File Tree	Table of Contents

Installation

Mac App Store (Recommended)

Available on the Mac App Store.

Homebrew

brew tap b451c/quickmd
brew install --cask quickmd

Build from Source

# Clone the repository
git clone https://github.com/b451c/quickmd.git
cd quickmd/QuickMD

# Open in Xcode
open QuickMD.xcodeproj

# Build and run (⌘R)

Requirements:

• macOS 13.0 (Ventura) or later
• Xcode 15.0+
• Swift 5.9+

Usage

Set as Default Markdown Viewer

1. Right-click any .md file in Finder
2. Select Get Info (⌘I)
3. Under Open with, select QuickMD
4. Click Change All...

Now all your Markdown files will open instantly with QuickMD!

Keyboard Shortcuts

Shortcut	Action
⌘O	Open file
⌘W	Close tab (or window if last tab)
⌘E	Open in External Editor
⌘F	Find in document
⌘G / ⇧⌘G	Next / previous match
⌘⇧C	Copy Markdown source
⌘⇧T	Toggle Table of Contents
⌘⇧D	Toggle Recent Documents sidebar
⌃⇥ / ⌃⇧⇥	Switch between tabs
⌘⇧E	Export to PDF
⌘P	Print
⌘,	Settings (themes + external editor)

Tech Stack

• Language: Swift 5.9
• Framework: SwiftUI
• Minimum OS: macOS 13.0 (Ventura)
• Architecture: Native Apple Silicon + Intel

Key Components

• Custom Markdown parser with block-level parsing, YAML frontmatter and reference link pre-pass
• Native NSTextView text pipeline with lazy layout — native selection, native links, no SwiftUI text bottlenecks on huge documents
• Per-document file watcher (DispatchSource) powering auto-reload, including atomic editor saves
• Regex-based syntax highlighting for code blocks (computed off the main thread)
• LaTeX math rendering via vendored SwiftMath (Core Graphics, no network); inline math as native text attachments
• Mermaid diagram rendering via bundled Mermaid.js (offline, no CDN), with snapshot caching and a zoom viewer
• 7 built-in themes + user themes from disk, with @AppStorage persistence
• AsyncImage for remote image rendering
• Security-Scoped Bookmarks for local image access in sandbox
• Per-block PDF export with multi-page pagination
• Zero external package dependencies — everything is vendored or bundled
• Unit test suite (76 tests) + GitHub Actions CI building every flavor on each push

Project Structure

QuickMD/
├── QuickMD/
│   ├── QuickMDApp.swift            # App entry point + menu commands
│   ├── MarkdownDocument.swift      # FileDocument model (encoding + line-ending normalization)
│   ├── MarkdownView.swift          # Main document view (lazy block layout)
│   ├── MarkdownBlock.swift         # Block type enum
│   ├── MarkdownBlockParser.swift   # Line-by-line block parser (+ YAML frontmatter)
│   ├── MarkdownRenderer.swift      # Inline markdown → AttributedString (SwiftUI + AppKit scopes)
│   ├── MarkdownTheme.swift         # Built-in themes
│   ├── MarkdownExport.swift        # PDF export + print support
│   ├── DocumentSearch.swift        # Find-in-document match engine
│   ├── SectionExtractor.swift      # "Copy section" boundaries from parser source lines
│   ├── InlineMathSegmenter.swift   # $...$ segmentation
│   ├── FileWatchManager.swift      # Auto-reload file watcher (DispatchSource)
│   ├── ExternalEditorManager.swift # ⌘E editor detection + launch
│   ├── WindowTabbing.swift         # Native macOS tab merging
│   ├── CustomThemeStore.swift      # User themes from disk (live reload + validation)
│   ├── RecentDocumentsStore.swift  # Recent documents tracking
│   ├── TipJarManager.swift         # StoreKit 2 IAP (App Store only)
│   ├── TipJarView.swift            # Tip Jar UI (App Store only)
│   ├── SandboxAccessManager.swift  # Security-scoped bookmarks
│   ├── SwiftMath/                  # Vendored math rendering (Core Graphics)
│   ├── Resources/
│   │   ├── mermaid.min.js          # Bundled Mermaid.js
│   │   └── mermaid-template.html   # HTML template for diagrams
│   ├── Views/
│   │   ├── TextBlockView.swift     # NSTextView-backed text blocks (native selection, inline math)
│   │   ├── CodeBlockView.swift     # NSTextView-backed code blocks (+ copy button)
│   │   ├── MathBlockView.swift     # LaTeX display math ($$...$$)
│   │   ├── MermaidBlockView.swift  # Mermaid diagrams (WKWebView + zoom + snapshot cache)
│   │   ├── TableBlockView.swift    # Table rendering with alignment
│   │   ├── ImageBlockView.swift    # Local + remote image rendering
│   │   ├── BlockquoteView.swift    # Nested blockquotes
│   │   ├── ChromeButtons.swift     # Heading copy, source copy, edit, support buttons
│   │   ├── SearchBar.swift         # Find in document (⌘F)
│   │   ├── TableOfContentsView.swift # ToC sidebar (⌘⇧T)
│   │   ├── RecentDocumentsSidebar.swift # Recent docs sidebar (⌘⇧D)
│   │   ├── SettingsView.swift      # Settings window (⌘,): Themes + Editor tabs
│   │   ├── ExternalEditorPickerView.swift # Editor selection
│   │   └── ThemePickerView.swift   # Theme picker + import/reload
│   └── Assets.xcassets/            # App icon + assets
├── QuickMDTests/                   # Unit tests (parser, renderer, search, watcher, ...)
├── docs/themes/                    # Schema + starter custom themes
├── CHANGELOG.md                    # Version history
└── demo.md                         # Demo file for testing

Development

Running the App

# Open in Xcode
open QuickMD/QuickMD.xcodeproj

# Run with ⌘R

Building for Release

GitHub version (default — donation links, no Tip Jar):

xcodebuild -project QuickMD/QuickMD.xcodeproj -scheme QuickMD -configuration Release archive

Or simply build in Xcode with ⌘B.

App Store version (Tip Jar IAP):

xcodebuild -project QuickMD/QuickMD.xcodeproj -scheme QuickMD -configuration Release \
  OTHER_SWIFT_FLAGS="-DAPPSTORE" archive

The APPSTORE flag enables Tip Jar IAP and disables the GitHub-only update checker.

Running Tests

xcodebuild -project QuickMD/QuickMD.xcodeproj -scheme QuickMD \
  -destination 'platform=macOS' test

CI runs the test suite plus Release builds of both flavors on every push and pull request.

Support

Get Help

• 🐛 Report a Bug
• 💡 Request a Feature

Support Development

QuickMD is free and open source. If you find it useful, consider supporting development:

Roadmap

• Export to PDF (⌘⇧E) and Print (⌘P)
• Syntax highlighting for code blocks
• Find & search within document (⌘F)
• Nested blockquotes with level indicators
• Table of Contents sidebar (⌘⇧T)
• Reference-style links ([text][id])
• Custom color themes (7 built-in)
• Copy to clipboard (whole file + sections)
• LaTeX math rendering ($$...$$)
• Mermaid diagram rendering (flowcharts, sequence, pie, class, etc.)
• Security-Scoped Bookmarks for local images
• Persistent Table of Contents state
• Inline math ($...$)
• Footnotes ([^id] references with definitions)
• Homebrew Cask formula
• User-defined themes loaded from disk (JSON drop-in)
• Recent Documents sidebar (⌘⇧D)
• Native macOS tabs (every doc opens as a tab in one window)
• NSTextView-backed code blocks (native selection, no SwiftUI Text trap)
• Large-document fast-load — NSTextView text blocks + lazy rendering (#10, #11)
• File auto-reload — live preview with your editor's auto-save
• Open in External Editor (⌘E) with auto-detected editor picker
• Copy button on code blocks
• Mermaid diagram zoom (#12)
• YAML frontmatter + setext headings + CRLF line endings
• Unit test suite + GitHub Actions CI
• Mermaid diagram PDF export (full fidelity)
• GFM alerts/admonitions (NOTE, WARNING, TIP)
• Definition lists

Have a feature request? Open an issue!

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Privacy

QuickMD respects your privacy. See our Privacy Policy for details.

TL;DR: No data collection, no analytics, no tracking. Everything runs locally on your device.

---

Built with ❤️ using Swift and SwiftUI

⭐ Star this repo if you find QuickMD useful!