Markdown Quick Look on macOS: preview .md files with Space

Quick Look is the best thing in Finder. Select a file, press Space, and macOS shows you the document — a PDF you can page through, a video you can scrub, a Keynote deck, a Numbers sheet, a RAW photo. No app launch, no window, no waiting.

Then you press Space on a .md file and get a wall of pound signs, asterisks and pipe characters that do not line up. Every other document type on your Mac previews as a document. Markdown previews as source code.

Increasingly those files are not ones you wrote. Claude, Codex and other AI tools save plans, specs and notes as Markdown, so a folder fills with finished documents that all preview as source. If that is how you got here, start with what to do with the .md files Claude and Codex leave behind.

Why Markdown is the exception

It is not that macOS does not recognise the format. It does. Ask the system about any Markdown file and it names the type precisely:

$ mdls -name kMDItemContentType -name kMDItemContentTypeTree README.md
kMDItemContentType     = "net.daringfireball.markdown"
kMDItemContentTypeTree = (
    "public.item",
    "public.text",
    "public.data",
    "public.content",
    "net.daringfireball.markdown",
    "public.plain-text"
)

The second list is the reason. Content types are a hierarchy, and Markdown conforms to public.plain-text. When you press Space, Quick Look looks for something registered to preview net.daringfireball.markdown, finds nothing, walks up the tree, and lands on the built-in plain-text previewer. That previewer then does exactly what it is supposed to do: it shows you the bytes in the file.

So the missing piece is not support for Markdown. It is a preview generator for Markdown. macOS has never shipped one, and as of macOS 26 it still does not. Every rendered Markdown preview you have ever seen on a Mac came from software somebody installed.

How Markdown Quick Look actually gets added

Quick Look previews come from app extensions. The standalone .qlgenerator plugins you may remember from older versions of macOS are gone — an extension now ships inside a regular app, and macOS registers it when that app is installed and run.

That means the setup is always the same three steps, whatever you install:

Install an app that contains a Markdown Quick Look extension.
Put it in /Applications and open it once, so macOS registers the extension.
Press Space on a .md file.

There is no configuration file to edit, no defaults write incantation, and nothing to install into ~/Library/QuickLook. If a guide tells you to copy a plugin into a Library folder, it predates the extension system and will not work on a current Mac.

What your options look like

QLMarkdown — free, open source, maintained, and deeply configurable if you enjoy that. Quick Look only: its app is a settings window, not somewhere to open and read your own documents. It is also the only option here that still supports macOS 11 to 13. See nicemd vs QLMarkdown.
A signed app with a bundled extension — anything from the App Store, or notarized for direct download, enables without quarantine workarounds and updates through the normal channel.
A full editor you already have — this generally does not give you Quick Look. Most Markdown editors render inside their own window and register no preview extension at all, which is why people with three Markdown apps installed still get raw text on Space.

A fuller breakdown of each, including which to pick, is in the comparison of Markdown Quick Look extensions.

If you are reading older advice: MacDown is no longer installable. It has sat at 0.7.2 for years, and its Homebrew cask was disabled on 1 September 2026 for failing Homebrew's Gatekeeper check. An existing copy keeps running; there is no supported way to get a new one. Any list still recommending it is stale.

Verifying it works, without guessing

Two places tell you the truth, and neither involves pressing Space and squinting.

The first is System Settings → General → Login Items & Extensions → Quick Look. Every app offering a preview extension is listed there with a switch. If yours is missing, macOS has not registered it — usually because the app has not been launched, or is not in /Applications.

The second is Terminal, which renders a file exactly the way Quick Look would:

qlmanage -p README.md

A rendered document means the extension is working and any remaining problem is about which surface you are looking at. Raw text means it is not — see the full troubleshooting checklist.

What a good preview should render

A rendered preview is only useful if it handles the Markdown people actually write. Worth checking before you settle on something:

Tables that line up, rather than pipes in a monospace column.
Task lists as checkboxes, since plans and checklists are half of what Markdown is used for.
Fenced code with syntax highlighting, not undifferentiated grey.
Mermaid diagrams, which are increasingly common in generated docs — see viewing Mermaid on a Mac.
Math, if you write any.
Front matter presented as metadata rather than dumped as a wall of YAML at the top.

One structural limitation applies to every Quick Look extension, not just one of them: a preview runs sandboxed and cannot ask you for permission to read the folder around the file, so images stored next to the document generally cannot be shown. A good extension degrades to alt text there rather than to a broken-image icon. If images matter for a particular document, open it properly.

nicemd

nicemd ships a Quick Look extension in the free tier, along with reading. Install it, open it once, and Space renders GitHub Flavored Markdown, Mermaid, KaTeX math and highlighted code — all bundled with the app, so a preview never touches the network. There is no account and no telemetry, and the paid unlock only covers editing, split view and export.