Markdown Quick Look not working on your Mac

You press Space on a .md file and get raw text, a blank panel, or some other app's preview. Each of those has a specific cause, and each takes a minute to fix.

Short answer

Work down the list. Most previews come back by the third step.

Install a Markdown Quick Look extension. macOS has none of its own.
Move the app to Applications and open it once, so macOS registers the extension.
Switch the extension on in System Settings: General, Login Items & Extensions, Quick Look on macOS 15 and later; Privacy & Security, Extensions, Quick Look on macOS 14.
Run qlmanage -r in Terminal to make Quick Look reload its extensions.
Switch off any other Markdown preview. macOS uses one extension per file type.

Raw text: nothing is rendering Markdown

macOS can preview images, PDFs, and plain text by itself, but it has no Markdown renderer. Until an app adds one, Space on a .md file shows exactly what is in the file: hashes, asterisks, and pipes where headings, bold text, and tables should be.

Glance fixes this in about a minute. It ships a Quick Look extension that draws Markdown natively, with tables, syntax-highlighted code, Mermaid diagrams, and LaTeX math, and it is free for reading and previews. The Finder preview guide walks through the install step by step.

A Markdown file rendered by Glance in a macOS Quick Look window

The extension is installed but switched off

Quick Look extensions can be switched off one by one, and a macOS update sometimes switches one off for you. On macOS 15 and later the switches are in System Settings, General, Login Items & Extensions, Quick Look. On macOS 14 they are under Privacy & Security, Extensions, Quick Look.

To check from Terminal, run pluginkit -m -p com.apple.quicklook.preview. Every installed preview extension is listed, with + in front when it is on and - when it is off.

Glance checks for you. Its Settings has a Quick Look pane that shows whether the extension is registered and switched on, and an Open Quick Look Settings button that takes you straight to the right panel when it is not.

It worked yesterday: macOS lost track of it

After a system update, Quick Look sometimes forgets an extension that is still installed and still switched on. Running qlmanage -r in Terminal makes it reload the list, and qlmanage -r cache clears stale thumbnails. Logging out and back in does the same.

Glance checks its own registration every time it launches and repairs it if macOS dropped it. If previews still stop, Check Again in Settings, Quick Look re-registers the extension and refreshes Quick Look in one click, with no Terminal involved.

Get Markdown previews that keep working

Download for macOS

Free to read, Pro to edit · v0.2.2 · 9.8 MB · macOS 14+

Blank previews after installing iA Writer, Typora, or TeXShop

This one is hard to spot. macOS gives every file a type, and .md files are normally net.daringfireball.markdown. Some editors declare a type of their own for the same extension: iA Writer declares net.ia.markdown, Typora io.typora.markdown, and TeXShop com.unknown.md. Install one and every .md file on the Mac quietly takes the new type, so a Quick Look extension that only claims the standard one stops matching, and the preview comes up blank.

To see the type your Mac gives a file, run mdls -name kMDItemContentType README.md. Glance claims all of these types, since version 0.2.2, so its previews keep working whichever Markdown editors you have installed.

Another app's preview keeps answering

macOS uses one Quick Look extension per file type. Several Markdown apps ship one, including QLMarkdown, Marked QL, MarkEdit, and, since version 1.14, Obsidian, and with two installed you cannot predict which answers for .md. Keep the one you want and switch the others off in the Quick Look panel of System Settings.

If you choose Glance, press Return in the preview and the file opens in a window that looks exactly like it, ready to read in full, search with ⌘F, or export as a PDF.

Setting up from scratch? Start with Markdown Quick Look for macOS and the Finder preview guide. Comparing extensions? See QLMarkdown and Marked, or the roundup of Mac Markdown apps.

FAQ

Because macOS has no Markdown renderer of its own. Without a third-party Quick Look extension, Space on a .md file shows the plain-text fallback: the syntax, unrendered. Install an app that ships a Markdown extension, such as Glance, and open it once from Applications.

Run qlmanage -r in Terminal to make Quick Look reload its list of extensions, and qlmanage -r cache to clear its thumbnail cache. Logging out and back in has the same effect. If you use Glance, Settings, Quick Look, Check Again re-registers its extension and refreshes Quick Look in one click.

Those editors declare their own file type for .md files (net.ia.markdown, io.typora.markdown, com.unknown.md), and on a Mac that has one installed, every .md file takes that type. A Quick Look extension that only claims the standard Markdown type no longer matches anything. Glance claims all of these types, since version 0.2.2, so its previews keep working whichever editors you have.

Run pluginkit -m -p com.apple.quicklook.preview in Terminal. Each line is an installed preview extension, with a plus sign in front when it is on and a minus sign when it is off. To see what type macOS gives a file, run mdls -name kMDItemContentType on it.

Yes. Reading and Quick Look previews are free, with no account and no time limit. Editing the rendered page is Glance Pro, free for 14 days and then $9.99 once.

Ready to glance?