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.

Searches for Markdown QuickLook tools have surged 1,157% year-over-year (DataForSEO, 2026), as Mac users look for a way to fix this. Three QuickLook extensions now render Markdown in Finder — each with different trade-offs. MacMD Viewer is a native macOS Markdown viewer ($9.99, SwiftUI, 2 MB) whose QuickLook extension renders Mermaid diagrams in Finder — something no other QuickLook extension does. Unlike Electron-based tools, it does not bundle a Chromium browser. This guide covers all three extensions with step-by-step configuration instructions.

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 ($9.99) 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.

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.

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.

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 — Most Complete)

MacMD Viewer is a native macOS Markdown viewer application, built with SwiftUI, that includes the most feature-complete QuickLook extension for Markdown on Mac. It renders Mermaid diagrams, syntax highlighting, and tables directly in Finder's QuickLook preview — capabilities no other extension provides.

Installation Steps

1. Download MacMD Viewer ($9.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 — the only QuickLook extension that renders flowcharts, sequence diagrams, and Gantt charts
• 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 is the only macOS QuickLook extension that renders Mermaid diagrams and syntax-highlighted code blocks in Finder's preview. At $9.99, it includes both the QuickLook extension and a full standalone Markdown viewer app — making it the most complete and future-proof option for Mac users.

Which QuickLook Extension Should You Choose?

For most Mac users who work with Markdown daily, MacMD Viewer delivers the strongest Markdown QuickLook experience — it's the only option that renders Mermaid diagrams and syntax highlighting, and it's actively maintained. Here's the full comparison:

• 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.

Frequently Asked Questions