On this page · 6 sections
You select a README.md in Finder, press Space, and macOS shows you a wall of hashes and asterisks. It is the single most common complaint about reading Markdown on a Mac, and for years the only fixes involved Homebrew and a Terminal window.
That changed in MDHero v0.2.10. Here is the short version, then the why.
The fix, in three steps
- Install MDHero — free, open source, about 8MB.
- Open it once. This is the step people miss: launching the app is what registers its Quick Look extension with macOS.
- Select any
.mdfile in Finder and press Space.
Still showing raw text?
Enable MDHero under System Settings → General → Login Items & Extensions → Quick Look. macOS sometimes needs the extension switched on explicitly, particularly if you have had other Markdown apps installed.
That is the whole setup. No brew install, no xattr command to strip a quarantine flag, no restarting the Quick Look server.
Why Space shows raw text in the first place
Quick Look is a plugin architecture. macOS ships preview generators for images, PDFs, video, plain text and a long list of other formats — but never one for Markdown. When you press Space on a .md file, Quick Look finds no Markdown generator, falls back to the plain-text one, and renders the file exactly as it is stored on disk.
So the # in # Installation is not a rendering bug. Quick Look is doing precisely what it was asked to do with a text file. The missing piece is a generator, and any app can supply one — Apple just never did for Markdown.
What actually renders
The extension uses the same rendering engine as the MDHero window, so the preview is not a cut-down version:
- Headings, lists and tables with real visual hierarchy
- Syntax-highlighted code blocks across 25+ languages
- KaTeX math —
$$\sum_{i=1}^{n}$$typeset properly, not left as LaTeX source - Mermaid diagrams drawn as flowcharts and sequence diagrams
- Light and dark following your system appearance
The last three are the interesting ones, because they are exactly what the plugin route never managed.
Compared to the QLMarkdown plugin
Before v0.2.10, the standard answer to “how do I preview Markdown in Finder” was QLMarkdown — a standalone Quick Look plugin. It is a good piece of software and still works.
| Stock macOS | QLMarkdown | MDHero | |
|---|---|---|---|
| Headings, tables, lists | ✗ | ✓ | ✓ |
| Syntax-highlighted code | ✗ | ✗ | ✓ |
| KaTeX math | ✗ | ✗ | ✓ |
| Mermaid diagrams | ✗ | ✗ | ✓ |
| Setup | — | Homebrew + Terminal | Open the app once |
| Survives macOS updates | — | Often needs re-authorising | Yes |
If you want only a Quick Look plugin and nothing else installed, QLMarkdown remains a reasonable pick. If you read Markdown often enough to want a real viewer too, MDHero gives you both from one install.
Make double-click work as well
Quick Look is for glancing. For files you intend to read properly — with tabs, find, a table of contents and editing — set MDHero as the default handler too:
- Right-click any
.mdfile in Finder - Get Info (or
Cmd+I) - Under Open with, choose MDHero
- Click Change All… and confirm
Space then previews the file and double-click opens it for real. Two gestures, two jobs.
One more thing in v0.2.10
The macOS .dmg is now notarized and stapled by Apple. Earlier releases were signed but the disk image itself was not notarized, so macOS showed a warning on first open and sometimes blocked the download outright. That step is gone — the download opens straight away.
For the full picture of reading Markdown on a Mac, see the complete 2026 guide or the head-to-head in Quick Look vs MDHero.
Frequently asked questions
Why does pressing Space on a .md file show raw text?
Because macOS ships no Quick Look preview generator for Markdown. Quick Look falls back to treating the file as plain text, so you see the literal hash and asterisk characters instead of formatting. Nothing is broken — the renderer simply does not exist until some app supplies one.
How do I make Finder's Quick Look render Markdown?
Install MDHero and open it once so macOS registers its Quick Look extension, then select any .md file in Finder and press Space. If it still shows raw text, enable MDHero under System Settings, General, Login Items and Extensions, Quick Look. No Terminal or Homebrew step is involved.
Is this different from the QLMarkdown plugin?
Yes. QLMarkdown is a standalone Quick Look plugin installed through Homebrew, and it renders headings, tables and lists but not syntax-highlighted code, KaTeX math or Mermaid diagrams. MDHero's extension renders all of those because it uses the same engine as the app, and it installs with the app rather than needing a Terminal command and a Gatekeeper exception.
Do I have to open MDHero to use Quick Look?
Only once, right after installing, so macOS registers the extension. After that the Space preview works on its own without launching MDHero at all.
Does this work on Windows or Linux?
No. Quick Look is a macOS feature, so the extension is macOS-only. On Windows and Linux, MDHero still opens .md files rendered on a double-click once you set it as the default handler for Markdown.