How to Preview Markdown Files Directly in macOS Finder

Arthur — Tue, 17 Mar 2026 20:39:44 +0000

You know that thing where you press Space on a file in Finder and get an instant preview?

It works for images. PDFs. Videos. Even 3D models.

But try it on a .md file. Nothing useful. Just raw text in a monospace font.

Here's how to fix that — and turn your Finder into a proper Markdown previewer.

What QuickLook actually is

For those unfamiliar: QuickLook is a macOS feature that renders a file preview when you press the spacebar in Finder. No app launches. No window management. Just instant preview.

Developers use it constantly without thinking about it. You select a .png and press Space to check the right asset. You select a .pdf to skim a doc without opening Preview. It's muscle memory.

The problem is that macOS ships with no QuickLook support for Markdown. Press Space on README.md and you get the same experience as opening it in TextEdit — raw syntax, no rendering.

Which is wild, because Markdown is arguably the most common documentation format in software development.

The setup (takes 2 minutes)

You need a QuickLook extension that understands Markdown. There are a few options:

QLMarkdown — Free, open-source, available on GitHub. Solid for basic Markdown rendering. No Mermaid support.

MacMD Viewer — $19.99 on https://macmdviewer.com/from/devto. Full viewer app that includes a QuickLook extension. Handles Mermaid diagrams, syntax highlighting, and dark mode in the preview. This is what we built and what I'll demo below.

Install either one. No config needed. macOS picks up the extension automatically.

The workflow that changes everything

Once installed, here's what your daily workflow looks like:

Triaging repos

You clone a repo. Before opening anything in your editor:

~/projects/new-repo/
├── README.md          ← select, press Space
├── CONTRIBUTING.md    ← arrow down, preview updates
├── docs/
│   ├── setup.md       ← arrow down again
│   └── api.md         ← you've scanned 4 docs in 10 seconds
├── src/
└── package.json

You just read four documentation files without launching a single app. Arrow keys move between files. The preview updates in real-time.

Compare that to: open VS Code → wait 3 seconds → navigate to file → Cmd+Shift+V for preview → repeat for each file. For reading documentation, QuickLook is 10x faster.

Reviewing PRs locally

Someone sends you a branch with updated docs. You check it out, navigate to the changed .md files in Finder, press Space. Instantly see how the rendered output looks. No need to push to GitHub just to preview the formatting.

Checking Mermaid diagrams

This is where it gets interesting. If your QuickLook extension supports Mermaid, you can preview architecture diagrams without leaving Finder.

Imagine your doc contains a flowchart: Client → API Gateway → Auth Service → Database. In raw Markdown, that's just text. With the right QuickLook extension, press Space and you see the actual rendered diagram — boxes, arrows, layout.

No browser, no Mermaid Live Editor, no copy-pasting syntax into a web tool.

For teams that document architecture in Markdown (and in 2026, most teams do), this is a massive time saver.

Live editing preview

If your QuickLook extension supports live reload (MacMD Viewer does), you can keep the preview open while editing the file in your favorite editor. Every save updates the preview instantly.

Split your screen: editor on the left, Finder QuickLook preview on the right. Poor man's live preview that works with any text editor — Vim, Neovim, Sublime, whatever.

Pro tips

Set your default app. Right-click any .md file → Get Info → Open With → choose your Markdown viewer → "Change All." Now double-clicking opens the rendered view, not TextEdit.

Spotlight works too. Open Spotlight (Cmd+Space), type a filename, arrow down to the .md file. The preview panel on the right renders it. You just searched and previewed a Markdown file without touching Finder.

Open/Save dialogs. Any time macOS shows a file picker (Cmd+O in any app), you can press Space to QuickLook preview files. Works with the Markdown extension installed. Handy when you're looking for the right doc in a cluttered project.

The before and after

Before:

See .md file in Finder
Double-click → TextEdit opens → raw text
Close TextEdit
Open VS Code
Wait for it to load
Open file, switch to preview
Read the doc
Close VS Code

After:

See .md file in Finder
Press Space
Read the doc

Eight steps down to two. That's not an optimization. That's a different workflow entirely.

The bigger picture

Markdown isn't going away. If anything, AI tools are generating more of it than ever. Every Cursor session, every Copilot suggestion, every v0 scaffold comes with .md files.

Your operating system should be able to read them natively. macOS can't — yet. But with the right QuickLook extension, it takes two minutes to fix what Apple hasn't fixed in 25 years of macOS development.

Try it. Select a .md file. Press Space. You'll wonder how you ever lived without it.

I've been using MacMD Viewer for this — it's a native macOS app with a QuickLook extension that handles Mermaid and syntax highlighting. $19.99 once. QLMarkdown is a solid free alternative if you just need basic rendering. Either way, get QuickLook working for Markdown. Your future self will thank you.

DEV Community: Arthur