Marq

Marq is a lightweight, native macOS markdown viewer. Point it at any .md file and get a clean, chromeless rendering window with live reload and vim-style navigation.

Marq is not an editor or a knowledge management system. It's a unix-philosophy tool — does one thing well and composes with your existing setup. Write in vim, VS Code, or whatever you prefer. Organise files however you like. Marq just renders them beautifully.

It tiles naturally alongside your terminal and editor in tiling window managers like Aerospace, with no window decorations or UI chrome getting in the way.

See examples/test.md for a demo of all supported features.

Install

brew tap jimbarritt/tap
brew install --cask marq

Since Marq is currently unsigned, you'll need to allow it past Gatekeeper on first run:

xattr -cr /Applications/Marq.app

Then open any markdown file with:

open -a Marq path/to/file.md

Set as default markdown handler

To open .md files with Marq by default (e.g. double-clicking in Finder):

brew install duti
duti -s com.jimbarritt.marq .md all
duti -s com.jimbarritt.marq .markdown all

If Marq doesn't register immediately, force Launch Services to re-index it first:

/System/Library/Frameworks/CoreServices.framework/Versions/A/Frameworks/LaunchServices.framework/Versions/A/Support/lsregister -f /Applications/Marq.app

Works great with AI tools

A strong use case for Marq is viewing markdown generated by AI agents. Agents dump reports, documentation, and summaries as .md files into arbitrary locations. Marq opens and renders them instantly with live reload — no vault setup, no importing, no ceremony.

If Marq is set as your default markdown handler, Claude Desktop shows an "Open with Marq" button directly on any markdown it generates, so you can jump straight to a rendered view.

See Set as default markdown handler below.

Marq vs Obsidian

Obsidian is a full personal knowledge management system — vaults, bidirectional linking, graph view, plugins, its own editor. It's an entire workflow you move into.

Marq is a focused viewer. The differences that matter:

• No vault required. Marq opens any .md file anywhere on disk.
• Lightweight and fast. Native Swift, no Electron. Pops up instantly.
• Tiling-friendly. No window chrome — sits cleanly alongside your terminal and editor.
• Vim-style browsing. j/k, gg/G, Ctrl-D/U, / search — for reading, not editing.
• Relative link navigation. Follow links between files without any vault or index.

They're complementary — Marq can browse an Obsidian vault, since a vault is just a folder of .md files. Edit and organise in Obsidian; use Marq for a distraction-free read view with vim navigation.

Features

• GitHub-style markdown rendering (light theme)
• All rendering libraries bundled offline (no internet required)
• Auto-refresh when the file changes on disk
• Follow relative markdown links between files
• Syntax-highlighted code blocks with copy button
• Mermaid.js diagrams
• KaTeX math / LaTeX
• Local and remote images
• "Copy Markdown" button (top right)
• Vim-style navigation keys

Usage

open -a Marq path/to/file.md

Building from source

just bundle        # builds build/Marq.app
just run-app       # builds and opens with test doc

Publishing a release

1. Check the current version:

   just version

2. Bump to the new version:

   just bump 1.2.0

3. Commit the version bump:

   git add justfile Sources/marq/Info.plist
   git commit -m "Bump to v1.2.0"
   git push

4. Build, publish to GitHub, and update the Homebrew cask:

   just publish

5. Push the cask update (must be done manually):

   cd /tmp/homebrew-tap && git push

Users can then upgrade with:

brew upgrade --cask marq

Keyboard Shortcuts

Key	Action
j / k	Scroll down / up
Ctrl-D / Ctrl-U	Half page down / up
gg	Go to top
G	Go to bottom
/	Search
n / N	Next / previous match
Esc	Close search
Cmd-Left / Cmd-Right	Navigate back / forward
Cmd-Q	Quit

Requirements

• macOS 14+
• Swift 5.9+