Quick Look for Markdown on macOS 14 and 15: setup and fixes

Quick Look is the preview you get when you select a file in Finder and press Space. For Markdown files it is very handy: you can check a README or a note without opening anything. But it only shows formatted Markdown if an app provides a Quick Look extension for it. This post explains the setup on macOS 14 and 15, and what to check when it does not work.

The examples use Markko, which includes a Quick Look extension in its free version. The steps are the same for other apps that ship one.

How it works

Quick Look itself does not know how to format Markdown. Apps can bring a Quick Look extension that tells macOS: “I can preview this file type.” For Markdown, that type is public.markdown. When you press Space on a .md file, macOS looks for an enabled extension that claims the type and lets it draw the preview.

So three things have to be true:

1. An app with a Markdown Quick Look extension is installed.
2. The extension is enabled.
3. No other extension gets in the way.

Setup

Install the app and open it once. macOS registers an app’s extensions when the app is installed and launched. Then select a .md file in Finder and press Space. In many cases, that is all.

If you see plain text or a generic icon instead, check that the extension is enabled. The place moved between macOS versions.

macOS 15: System Settings ▸ General ▸ Login Items & Extensions ▸ Quick Look. Find the app in the list and turn it on.

macOS 14: System Settings ▸ Privacy & Security ▸ Extensions ▸ Quick Look. Tick the box next to the app.

Go back to Finder and press Space on the file again.

Fix 1: reset Quick Look

Quick Look keeps a cache and a background process. After installing, updating or removing an app, it can hold on to old state. Reset it in Terminal:

qlmanage -r

This makes Quick Look reload its list of preview providers. To clear the thumbnail cache as well, run:

qlmanage -r cache

If Finder still shows the old preview, relaunch Finder: hold Option, right-click the Finder icon in the Dock and choose Relaunch. Logging out and in again does the same more thoroughly.

Fix 2: another app claims Markdown

If more than one installed app has a Quick Look extension for public.markdown, macOS picks one. It may not be the one you want. Signs of this: the preview looks different from what you expect, or it changed after you installed another app.

Go to the Quick Look list in System Settings, using the path for your macOS version above. Look for other entries that could handle Markdown: editors, note apps and other viewers sometimes ship one. Turn off the ones you do not want, keep the one you do, then run qlmanage -r.

You do not have to uninstall the other app. Turning off its Quick Look extension is enough.

Fix 3: check the file type

Sometimes the file is the odd one. To see how macOS classifies a file, run:

mdls -name kMDItemContentType -name kMDItemContentTypeTree notes.md

The output shows the content type of the file and the types it belongs to. If the file is not seen as Markdown, a Markdown extension will not be asked to preview it. This can happen with unusual extensions, or with files that have no extension at all. Renaming the file to end in .md is the simplest fix.

Fix 4: the basics

A few plain things are worth ruling out:

• Open the app once. If you installed it and never launched it, the extension may not be registered yet.
• Update the app. An old version may have an old extension.
• Restart the Mac. It is boring, and it clears most stuck extension state.
• Try another file. If one file fails and others work, the problem is in that file, for example a very large size.

What you get when it works

With Markko’s extension enabled, pressing Space on a Markdown file shows the document formatted as GitHub Flavored Markdown. With Markko Pro, Mermaid diagrams are drawn in the Quick Look preview too. The arrow keys move through the files in the folder, so you can scan a directory of notes quickly.

Quick Look is for glancing. For longer reading, open the file in the app itself, where you have an outline, find and themes.

Short checklist

1. Install the app and open it once.
2. Enable its extension: macOS 15 under General ▸ Login Items & Extensions ▸ Quick Look, macOS 14 under Privacy & Security ▸ Extensions ▸ Quick Look.
3. Run qlmanage -r.
4. Turn off other Quick Look extensions that claim Markdown.
5. Check the file type with mdls if a single file misbehaves.

If the preview still does not show after these steps, contact the developer of the app whose extension you use, and include your macOS version and the output of the mdls command.