Set it up, and what to do when it does not take. Updated July 2026.
You press space on a .md file expecting a rendered document, and macOS shows you hash marks and asterisks. Fifteen minutes later you have installed something, restarted Finder twice, and it still shows raw text. This page is the fix, in the order the problems actually happen.
Why it happens
Worth knowing before you install anything, because it explains why no setting will turn this on. We checked it rather than repeating it — on macOS 26.5.2 (build 25F84, Apple silicon):
So the system recognises .md as its own type, finds no generator for it, and falls back to plain text. Every fix below is an extension you add. There is no switch.
The fix
Any of these will do it. Pick on how you like installing things — the preview quality is broadly the same, and the differences matter later, not now.
Then switch the extension on, which macOS does not do for you:
When it does not work
Quick Look caches its generator list. Run qlmanage -r in Terminal, then qlmanage -r cache. If that does not do it, log out and back in. A reboot is almost never what fixes this, despite what the forums say.
Usually a second Markdown extension got installed and the two are competing — macOS picks one and it may not be yours. Go back to Login Items & Extensions and turn off every Markdown generator except one.
Check the extension, not the content. .markdown, .mdx and .txt files holding Markdown are different types as far as macOS is concerned, and not every generator claims all of them. QLMarkdown covers the widest set; Peekdown is the one to reach for if your files are MDX or Obsidian markup.
Mermaid and LaTeX are not part of Markdown, so they only render if the generator implements them. QLMarkdown, Markdown Preview, MacMD Viewer and Readdown all do. If your diagrams show as code blocks, that is the generator, not your file.
Once it works
Quick Look previews. It does not open, and it does not edit. That distinction is what separates the options once the immediate problem is solved.
If you only ever preview, stop at the generator you installed — several of the above cost nothing and you are already done. Readdown is the one to look at if you want a proper reading window and will never edit. Ours exists for the case where preview is not the end of it: double-click opens the file rendered, ⌘E edits the source, ⌘S saves it back, in one app instead of an extension plus an editor.
PX7 Digital makes PX7 Markdown Viewer, so this page is not neutral. Prices, formats and system requirements for the other apps were taken from each product's own site on 31 July 2026, and the macOS behaviour above was checked on the machine and version named. Where a vendor does not publish a price, this page says so instead of guessing. Something out of date? Tell us.