Markee

A native macOS Markdown preview app that watches a file on disk and re-renders the moment you save. **Editor-agnostic** — keep using Vim, VS Code, Cursor, Zed, JetBrains, Sublime, or whatever else you already love; let Markee handle the preview.

Website: markee.sbang.dev

Why Markee?

Most Mac Markdown apps want to be your editor too — and that means picking between their text-editing experience and the one you've already tuned for years. Markee skips the fight: it's a preview. You edit in the editor you know, save the file, and the rendered view updates instantly. Want to jump back to a heading you're scrolled to? Right-click it in the outline → Open in Editor, and your editor opens at that line.

Features

• Live re-render on save, with scroll position preserved.
• Works with editors that do atomic saves (Vim, VS Code, Cursor, Zed, Sublime, JetBrains, …).
• GitHub-flavored Markdown plus footnotes, definition lists, attribute lists, task lists, YAML front matter.
• KaTeX math (inline $…$ and display $$…$$).
• Syntax highlighting via highlight.js.
• Mermaid diagrams.
• Quick Look — press Space on a .md file in Finder for a fully rendered preview instead of raw text.
• Finder thumbnails & document icon — .md files show a thumbnail of their rendered content, and carry a branded Markee document icon.
• Interactive task-list checkboxes that write back to the source file.
• Open in Editor at Current Heading — ⌥⌘E or right-click an outline row to jump to that heading's source line in your editor.
• Outline sidebar with live active-heading highlight (⌘⌥\ to toggle).
• Export Standalone HTML with inlined CSS + images (⌘E).
• ⌘F find in preview, ⌘P print or save as PDF.
• Light + dark themes, follows prefers-color-scheme.
• CLI launcher: markee path/to/notes.md.

Install

Recommended: prebuilt .app

Download Markee.app.zip from the latest GitHub Release, unzip, drag into /Applications.

Release builds are Developer ID signed and notarized, so they open normally with a double-click — no Gatekeeper warning, no right-click workaround needed.

From source

make fetch-vendor   # one-time: pinned downloads of markdown-it, KaTeX, highlight.js, Mermaid
make app            # builds Markee.app at the repo root
make run            # builds + opens
make install        # copies to /Applications

Subsequent make app invocations skip the vendor fetch (sentinel-based).

Use

Any of these opens a file:

• Drag a .md onto the Markee dock icon.
• File ▸ Open… (⌘O).
• open Markee.app yourfile.md.
• After installing the CLI (File ▸ Install Command Line Tool…): markee yourfile.md.

Then edit the file in your editor. Save. The preview updates.

Keyboard shortcuts

Shortcut	Action
⌘O	Open file
⌘W	Close window
⌘⌥\	Toggle outline sidebar
⌘E	Export Standalone HTML
⌥⌘E	Open in Editor at current heading
⌘F	Find in preview
⌘P	Print / save as PDF

Open-in-Editor configuration

Markee auto-detects the first available editor from this list on your PATH (via your login shell, so Homebrew / fnm / asdf entries work):

cursor → code → zed → subl → mate → mvim → hx

Override by setting a preference:

defaults write com.markee.preview editor "zed"

For each editor, Markee constructs the right "jump to line" syntax — code -g path:line:col, zed path:line:col, subl path:line, mate -l line path, mvim +line path, hx path:line. The full list of supported editors is in Sources/Markee/EditorLauncher.swift.

Develop

make test         # swift test + node --test (Swift + JS)
make test-swift   # FileWatcher, SchemeHandler, PreviewController, EditorLauncher
make test-js      # util.js (collectTaskLineNumbers, slugify, pickActiveHeading)
make clean        # nuke .build, Markee.app, and Resources/web/vendor

48 tests passing at HEAD (24 Swift + 24 JS).

Project layout

Sources/Markee/        Swift app (SwiftUI DocumentGroup + WKWebView)
Resources/web/         HTML/JS/CSS shipped into the bundle
  template.html        Loads vendor + util + app
  app.js               Renderer glue, scroll preservation, message bridge
  util.js              Pure helpers (importable by Node tests)
  theme.css            Light/dark theme
  vendor/              Fetched at build time, not committed
Resources/cli/markee   Shell launcher
Resources/AppIcon.svg  Source for the app icon
scripts/               build-icon.sh, fetch-vendor.sh, sign-app.sh, notarize-app.sh
Tests/                 Swift + JS tests
fixtures/sample.md     Exercises every feature
docs/demo.md           README hero document

How it works (briefly)

The Swift side is a thin host: a DocumentGroup, a per-window PreviewController, a FileWatcher (kqueue with atomic-save reattach), and two custom URL scheme handlers — markee-app:// for bundle assets and markee-doc:// for the current document's directory (sandboxed against path traversal and symlink escape). All Markdown rendering happens in JavaScript inside the WebView; Swift just streams the file's source into window.markee.render({…}) after every change.

Requirements

• macOS 13 (Ventura) or later.
• Apple Silicon (untested on Intel — should work but no CI for it).
• Swift 5.9+ (ships with Xcode 15 / the Command Line Tools).
• Node ≥ 18 (only needed to run the JS test suite).

Status

v1.0.0 — see CHANGELOG.md for the full release history. Developer ID signed and notarized.

Contributing

This is a small personal project. Issues and focused PRs are welcome; for anything larger than a small fix, please open an issue first so we can talk through the approach. See CONTRIBUTING.md.

For security reports, see SECURITY.md.

License

MIT. Markee bundles a handful of third-party JS/CSS libraries under their own permissive licenses — see THIRD-PARTY-NOTICES.md for the full texts.

Credits

Built on the shoulders of markdown-it, KaTeX, highlight.js, and Mermaid. The macOS-app shell is plain SwiftUI + WKWebView.