How to Preview Markdown Files with QuickLook on Mac

Press Space on any file in Finder to preview it. Works for PDFs, images, videos — but not Markdown. Your .md documents show up as raw text with hashtags and asterisks. No headings, no code blocks, no tables. Just symbols.

Three QuickLook extensions now render Markdown in Finder — each with different trade-offs. MacMD Viewer ($19.99 one-time) is a native macOS Markdown viewer built with SwiftUI whose QuickLook extension renders Mermaid diagrams directly in Finder's preview — one of very few that do. Unlike Electron-based tools, it does not bundle a Chromium browser. See the full feature list if you want to compare capabilities before choosing. This guide covers all three extensions with step-by-step configuration instructions.

MacMD Viewer ($19.99 one-time) is the only option here that renders Mermaid diagrams in QuickLook and includes a full standalone viewer app — see all features.

TL;DR: macOS has no built-in Markdown QuickLook support. Install QLMarkdown via Homebrew (free, but deprecated Sept 2026), Markdown Preview from the App Store ($2.99), or MacMD Viewer ($19.99 one-time) which includes a QuickLook extension with Mermaid diagram and syntax highlighting support. All require enabling in System Settings > Extensions > QuickLook.

Why Doesn't macOS Preview Markdown in QuickLook?

macOS QuickLook handles over 30 file types natively — PDFs, images, videos, Office documents, and more. Markdown is not one of them. Apple has never shipped a built-in QuickLook renderer for .md files, despite Markdown being the standard format for developer documentation since 2004.

QuickLook relies on extensions to process each file type. Without a Markdown extension installed, pressing Space on a .md document shows the raw plain text — # Heading instead of a formatted heading, **bold** instead of bold. For more ways to view Markdown beyond QuickLook, see our guide on how to open .md files on Mac.

macOS QuickLook supports over 30 file types natively — PDFs, images, videos, Office documents — but Markdown (.md) is not one of them. To enable Markdown QuickLook previews in Finder, you need to install a third-party extension and enable it in System Settings.

How to Install QLMarkdown on Mac (Option 1 — Free)

QLMarkdown is a free, open-source QuickLook extension by sbarex that renders Markdown content as formatted HTML in Finder. It supports .md, .markdown, .rmd, .mdx, and .textbundle files.

Installation Steps

1. Open Terminal
2. Run: brew install --cask qlmarkdown
3. Open QLMarkdown.app once to register the extension
4. Go to System Settings > Privacy & Security > Extensions > QuickLook
5. Enable "QLMarkdown"
6. Press Space on any .md file in Finder — it renders with headings, lists, code blocks, and tables

QLMarkdown displays headings, lists, code blocks, tables, and LaTeX math. It does not render Mermaid diagrams. If you need Mermaid support or a maintained long-term option, MacMD Viewer ($19.99 one-time) is the alternative to consider.

Deprecation Warning

The QLMarkdown Homebrew cask is marked deprecated with a disable date of September 1, 2026 (Homebrew Formulae). After that date, brew install --cask qlmarkdown will stop working. You'll still be able to install manually from the GitHub releases page, but automatic updates through Homebrew will end.

QLMarkdown is a free, open-source macOS QuickLook extension by sbarex that renders Markdown files as formatted HTML in Finder. However, its Homebrew cask is deprecated with a disable date of September 2026 — users should consider alternatives or plan to install manually from GitHub releases.

MacMD Viewer: native Markdown viewer for Mac with Mermaid diagrams and QuickLook. $19.99 one-time purchase →

How to Set Up Markdown Preview from the App Store (Option 2 — $2.99)

Markdown Preview by Anybox Ltd is a $2.99 Mac App Store application that adds Markdown rendering to QuickLook with zero Terminal configuration. It's the simplest option — download, enable, done.

Installation Steps

1. Search "Markdown Preview" on the Mac App Store
2. Purchase and install ($2.99 one-time)
3. Go to System Settings > Privacy & Security > Extensions > QuickLook
4. Enable "Markdown Preview"
5. Press Space on any .md file in Finder

Markdown Preview handles standard formatting — headings, lists, code blocks, links. It doesn't support Mermaid diagrams or syntax highlighting in code blocks. Updates arrive automatically through the App Store. If those gaps matter, MacMD Viewer ($19.99 one-time) covers both.

Markdown Preview is a $2.99 Mac App Store app by Anybox Ltd that adds Markdown QuickLook support without using Terminal or Homebrew. It renders standard Markdown formatting but lacks Mermaid diagram rendering and code syntax highlighting.

How to Use MacMD Viewer's QuickLook Extension (Option 3 — Mermaid + Full App)

MacMD Viewer ($19.99 one-time) is a native macOS Markdown viewer application, built with SwiftUI, that includes a QuickLook extension covering capabilities the other two options don't reach. It renders Mermaid diagrams, syntax highlighting, and tables directly in Finder's QuickLook preview — a combination few extensions offer.

Installation Steps

1. Download MacMD Viewer ($19.99 one-time)
2. Open the app once to register the QuickLook extension
3. Enable in System Settings > Privacy & Security > Extensions > QuickLook
4. Press Space on any .md file in Finder — see it rendered with full formatting

What makes it the most complete option?

• Mermaid diagrams — renders flowcharts, sequence diagrams, and Gantt charts right in the QuickLook preview, which most extensions can't do
• Syntax highlighting — code blocks with proper language-specific coloring
• Works everywhere — Finder, Spotlight, and Open/Save dialogs
• Includes the full app — table of contents sidebar, zoom, live file watching, dark mode
• Future-proof — actively maintained, unlike QLMarkdown's deprecated Homebrew cask

See all MacMD Viewer features or visit the QuickLook extension page for more details.

MacMD Viewer renders Mermaid diagrams and syntax-highlighted code blocks directly in Finder's QuickLook preview — something neither QLMarkdown nor Markdown Preview supports. At $19.99 one-time, it includes both the QuickLook extension and a full standalone Markdown viewer app.

Which QuickLook Extension Should You Choose?

Here's how the three options compare. Note that Readdown (free) also provides a QuickLook extension — though without Mermaid or syntax highlighting. If you also want to compare the full viewer landscape beyond QuickLook, see our native Markdown viewer roundup for macOS.

Feature	QLMarkdown	Markdown Preview	MacMD Viewer
Price	Free	$2.99	$19.99 one-time
Install method	Homebrew / GitHub	App Store	Direct / App Store
Mermaid diagrams	No	No	Yes
Syntax highlighting	Basic	No	Yes
Math (LaTeX)	Yes	No	Yes
Status	Deprecated Sept 2026	Active	Active
Includes viewer app	No	No	Yes

• Free and temporary? QLMarkdown — but plan for the Homebrew deprecation in September 2026.
• Simple and no Terminal? Markdown Preview from the App Store.
• Full-featured and future-proof? MacMD Viewer.

How to Fix QuickLook Markdown Not Working on Mac?

If Markdown QuickLook isn't working, the most common fix is resetting the cache. Launch Terminal and run qlmanage -r — this forces macOS to rediscover all installed extensions. If that doesn't resolve it, try these steps in order:

1. Check Extension Is Enabled

Go to System Settings > Privacy & Security > Extensions > QuickLook and verify your Markdown extension is toggled on.

2. Open the App Once

Some extensions only register after you launch the parent application. Open QLMarkdown.app or MacMD Viewer once, then check the extensions list again.

3. Restart Finder

Hold Option and right-click the Finder icon in your Dock. Select Relaunch.

4. Xcode Conflict

Xcode registers its own handler for .md files, which can override QuickLook extensions. Fix this by right-clicking a .md file > Get Info > Open With > change to your preferred app > Change All.

5. macOS Sequoia Permission

On macOS 15 (Sequoia) and later, you may need to explicitly approve the extension. Check System Settings for a security prompt after first enabling.

If QuickLook isn't rendering Markdown after installing an extension, run qlmanage -r in Terminal to reset the QuickLook cache. If Xcode is installed, it may override .md file handling — change the default app via Finder > Get Info > Open With.

If you also need to reveal hidden .md files before previewing them, read our guide on how to view hidden files on Mac. For converting Markdown to PDF after previewing, see our Markdown to PDF on Mac guide.

Frequently Asked Questions

How do I install QLMarkdown on Mac?

Run 'brew install --cask qlmarkdown' in Terminal, then enable it in System Settings > Privacy & Security > Extensions > QuickLook. Note: the Homebrew cask is deprecated with a disable date of September 1, 2026 (Homebrew Formulae). After that, install manually from the GitHub releases page.

Is QLMarkdown deprecated?

The Homebrew cask for QLMarkdown is deprecated with a disable date of September 1, 2026 (Homebrew Formulae). The GitHub project by sbarex remains active. After the Homebrew deprecation, you can still install QLMarkdown manually from GitHub releases or switch to MacMD Viewer's QuickLook extension.

Does any QuickLook extension support Mermaid diagrams?

MacMD Viewer ($19.99 one-time) renders Mermaid diagrams — flowcharts, sequence diagrams, Gantt charts — directly in Finder's QuickLook preview. Neither QLMarkdown nor the App Store's Markdown Preview support Mermaid rendering.

Why doesn't QuickLook show formatted Markdown on my Mac?

macOS has no built-in Markdown renderer for QuickLook. You need to install a third-party extension — QLMarkdown (free), Markdown Preview ($2.99), or MacMD Viewer ($19.99 one-time) — and enable it in System Settings > Extensions > QuickLook. If it still doesn't work, run 'qlmanage -r' in Terminal.

How do I enable QuickLook extensions on Mac?

Go to System Settings > Privacy & Security > Extensions > QuickLook. Check the box next to your Markdown extension. If the extension doesn't appear, open the app once to register it, then restart Finder by holding Option and right-clicking the Finder icon in the Dock.