Markdown Preview

A fast, native macOS app for reading Markdown files.

    

---

Drop a .md on the icon (or set Markdown Preview as your default handler) and get a clean, scrollable preview with a real document outline — no Electron, no browser tab.

Installation

Markdown Preview is available in the official Homebrew cask repository:

brew install --cask markdown-preview

Or grab the latest signed and notarized DMG from the Releases page.

Screenshots

Edit Markdown directly with a native formatting toolbar:

Quick Look preview — spacebar a .md in Finder:

Customize the toolbar — drag in Print, Copy, Zoom and the rest from View → Customize Toolbar…

Features

• Native rendering — WKWebView pipeline backed by swift-markdown, with heading anchors and link handling.
• Edit Mode — edit Markdown in place with a formatting toolbar for headings, emphasis, lists, quotes, code, and links. Toggle it from the toolbar or with ⌘E, then save with ⌘S.
• Mermaid diagrams — fenced mermaid code blocks render as diagrams in both the app and Quick Look previews, using a bundled renderer so previews work offline without a CDN request.
• Math equations — LaTeX inline ($x_1 + x_2$), display ($$\int_0^1 x^2\,dx$$), and fenced math blocks render with a bundled KaTeX. Selecting a rendered formula and copying yields the original LaTeX source (via the official copy-tex extension).
• Document outline — sidebar TOC that mirrors your headings; click to jump.
• Inspector panel — toggleable side panel with file metadata.
• In-document search — toolbar search field plus standard ⌘F / ⌘G / ⌘⇧G for next/previous match.
• Open With — switch to your real editor (VS Code, Cursor, Zed, Sublime, BBEdit, Nova, CotEditor, TextMate, MacVim, Xcode, TextEdit) without leaving the preview. The list filters to apps that actually declare an editor role for Markdown, and remembers your pick.
• Open in LLM — send the current Markdown file to Codex, Claude, or ChatGPT from the toolbar. Supported apps open with file or folder context where possible, with a copy-and-open fallback for longer prompts.
• Text zoom — bump preview text up or down with trackpad pinch, the toolbar's A A control, or ⌘+ / ⌘− / ⌘0. Discrete Safari-style stops from 50% to 300%.
• Customizable toolbar — drag in the items you actually use (Print, Copy, Zoom, Sidebar, Open With, Inspector, Share, Search) via View → Customize Toolbar… Standard AppKit affordance, your layout sticks across launches.
• Share = copy the source — the share toolbar feeds the picker the Markdown text itself, so Copy writes the raw source to the clipboard (great for pasting into ChatGPT / Claude), and Mail, Messages, and Notes get the content in the body instead of a file URL.
• Quick Look extension — system-wide .md previews from Finder spacebar, Spotlight, and Mail attachments without launching the app.
• Command line tools — install mdp, md-preview, and markdown-preview from the app menu, then open files or folders from any shell with commands like mdp README.md or mdp ..
• URL scheme — open a file or folder from a browser link or another app with md-preview://file/<absolute path> (e.g. md-preview://file/Users/me/project/README.md), the same shape as cursor://file/…. Percent-encode special characters in the path (a space becomes %20).
• Default handler — offers to register itself as the default .md opener on first launch.

Supported file types

.md, .markdown, .mdown, .txt UTI: net.daringfireball.markdown

Requirements

• macOS 15 or later
• Apple Silicon or Intel

Building from source

git clone git@github.com:pluk-inc/markdown-preview.git
cd markdown-preview
open markdown-preview.xcodeproj

Build and run the markdown-preview scheme. Swift Package Manager will resolve Sparkle, Sentry, and swift-markdown on first build.

Crash reporting

Release builds submit native crash reports to the pluk-inc/markdown-preview Sentry project. The integration does not collect performance traces, session data, breadcrumbs, network requests, user information, document contents, or file paths. Users can turn reporting off directly from Markdown Preview > Send Anonymous Crash Reports; on later launches, the Sentry SDK will not initialize at all.

The committed DSN is a public client key. Release archives upload the app dSYM with sentry-cli; authenticate locally with sentry-cli login and keep that authentication token outside the repository.

Anonymous usage analytics

Release builds can submit at most one anonymous app became active event per installation per UTC day when Markdown Preview becomes active. The event contains a random installation identifier, app version, macOS major version, processor architecture, locale country or region, and the flag that prevents PostHog from creating a person profile. It is used to count daily and monthly active installations and understand basic platform compatibility. It does not contain document contents, file names or paths, actions, screens, precise location, personal information, or advertising identifiers. Users can disable it from Settings > Privacy.

The PostHog project token is injected from the gitignored Secrets.xcconfig. Copy Secrets.xcconfig.example to Secrets.xcconfig and set POSTHOG_PROJECT_TOKEN before making a release build. If the token is absent, or for a Debug build, analytics remains disabled. Every event disables GeoIP enrichment, and the PostHog project must also be configured to discard IP data in Project Settings > General.

Project layout

md-preview/         Main app target (AppKit, WKWebView)
quick-look/         Quick Look extension (.appex)
scripts/            Release & rollback automation
Version.xcconfig    Marketing & build version (single source of truth)
appcast.xml         Sparkle update feed

Releasing

Releases are driven by Amore — it handles building, code signing, notarization, DMG creation, S3 upload, and Sparkle appcast publishing in one shot.

Bump MARKETING_VERSION and CURRENT_PROJECT_VERSION in Version.xcconfig, then:

./scripts/release.sh

Use ./scripts/rollback-release.sh to revert the appcast pointer if a release misbehaves.

Contributing

Pull requests are welcome. For larger changes, please open an issue first to discuss what you'd like to change.

1. Fork the repo and create your branch from main.
2. Run the app and verify the change end-to-end (UI changes need a manual smoke test — there's no UI test suite yet).
3. Keep PRs focused; one logical change per PR.
4. Match the existing Swift style (no formatter is enforced; mirror nearby code).

Special Sponsor

    

Support

Markdown Preview is free and MIT-licensed. If it saved you a browser tab, you can buy us a coffee.

Acknowledgments

• Amore — MacOS release automation (signing, notarization, DMG, hosting, appcast)
• swift-markdown — Markdown parser (Apple, cmark-gfm-backed)
• Mermaid — Bundled diagram renderer for mermaid fenced code blocks
• KaTeX — Bundled math typesetter for inline $…$, display $$…$$, and ```math blocks
• Sparkle — Auto-update framework
• Sentry — Privacy-filtered native crash reporting
• LottieFiles — Animated README logo

License

MIT