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.
• Quick Edit (⌘↩): select text and fix it in place: the block turns into its Markdown, ⌘↩ saves. For anything bigger, Open in 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.
• In-window navigation — click .md links to move between files with Back/Forward (⌘[ / ⌘]), a sidebar file tree, [[wiki-links]], and a workspace-wide search palette (⇧⌘O).
• Window pinning — float a window on top (⌥⌘P), keep it on all Spaces, or use ghost mode to dim it until you hover.
• Light + dark themes, following prefers-color-scheme, plus a Preferences window (⌘,) to override the theme, accent color, base font size, and load a custom CSS file.
• Free and fully featured; nothing is gated. An optional supporter license silences the occasional support nudge — pay what you want once, or $5 a year.
• 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

just fetch-vendor   # pinned downloads of markdown-it, KaTeX, highlight.js, Mermaid
just app            # builds Markee.app at the repo root (never touches /Applications)
just run            # builds + opens the repo-root build
just install        # builds, then replaces /Applications/Markee.app

Every build re-verifies the vendored files against scripts/vendor.sha256; already-present files aren't downloaded again. Run just to list every recipe.

Use

Any of these opens a file:

• Drag a Markdown file onto the Markee dock icon.
• File ▸ Open… (⌘O).
• File ▸ Open Folder as Workspace… to set a folder as the navigation root.
• 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.

Workspaces

Opening a single file quietly establishes a workspace around it — the root Markee uses to resolve the file tree, [[wiki-links]], and ⇧⌘O search. The root is inferred from the file you open: the enclosing git repository if there is one, otherwise the nearest parent folder holding more than one Markdown file, otherwise the file's own folder. Use File ▸ Open Folder as Workspace… to set it explicitly.

Keyboard shortcuts

Shortcut	Action
⌘O	Open file
⌘W	Close window
⌘,	Preferences
⌘⌥\	Toggle outline sidebar
⌘[ / ⌘]	Back / forward
⇧⌘O	Search workspace
⌘R	Reload from disk
⌘+ / ⌘=	Zoom in
⌘-	Zoom out
⌘0	Actual size
⌘E	Export Standalone HTML
⇧⌘E	Export PDF
⌥⌘E	Open in Editor at current heading
⌘↩	Quick Edit the selected block (⌘↩ again saves, Esc cancels)
⇧⌘C	Copy Markdown source
⌥⌘C	Copy reflowed Markdown (soft-wrapped paragraphs unwrapped)
⇧⌥⌘C	Copy as rendered plain text
⇧⌘R	Reveal in Finder
⌘F	Find in preview
⌘G / ⇧⌘G	Find next / previous
⌘P	Print / save as PDF
⌥⌘P	Float window on top

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

Override it in Markee ▸ Settings ▸ General ▸ Editor, or with a preference (a bare command name, not a path):

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. The full list of supported editors is in Sources/Markee/EditorLauncher.swift. Terminal editors (nvim, vim, hx, …) aren't supported: Markee launches the editor without a terminal, so use a GUI build such as mvim.

Develop

just test         # swift test + node --test (Swift + JS)
just test-swift   # Swift unit tests (XCTest)
just test-js      # JS helper, render-snapshot, source-line, wiki-link, reflow and Quick Edit tests
just clean        # nuke .build, Markee.app, and Resources/web/vendor
just dev          # launch with the Debug menu (MARKEE_DEV_TOOLS=1) and forced supporter state
just reset        # wipe local state + relaunch a fresh, un-licensed install

Swift tests need full Xcode (XCTest isn't in the Command Line Tools): if swift test reports no such module 'XCTest', run it with DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer.

Project layout

Sources/Markee/        Swift app (SwiftUI DocumentGroup + WKWebView)
  Workspace*.swift     Workspace root + file tree, search, and back/forward
  NavigationHistory.swift  Pure back/forward stack
Sources/MarkeeKit/     Shared library: renderer, scheme handlers, file reader
Sources/MarkeeQuickLookPreview/    Quick Look preview extension (.appex)
Sources/MarkeeQuickLookThumbnail/  Quick Look thumbnail extension (.appex)
Resources/web/         HTML/JS/CSS shipped into the bundle
  template.html        Loads vendor + util + render-core + reflow + quick-edit-core + app + quick-edit (strict CSP)
  app.js               Renderer glue, scroll preservation, message bridge
  render-core.js       markdown-it pipeline + front matter + source lines (also used by Node tests)
  reflow.js            Copy Reflowed Markdown: unwraps soft-wrapped paragraphs
  quick-edit-core.js   Quick Edit's pure helpers (importable by Node tests)
  quick-edit.js        Quick Edit: the in-place block editor
  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 most rendering features
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 files under the workspace root (the enclosing git repo or docs folder; sandboxed against path traversal and symlink escape — see SECURITY.md). 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

See Releases for the current version and CHANGELOG.md for the full 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.

Using Markee at work? Markee is free for everyone, companies included. If your team wants priority support and a commercial support agreement on file, see COMMERCIAL.md.

Credits

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