Quick Look vs MDHero: Best Markdown Viewer for Mac

You’re in Finder. You see a README.md. You hit Space. Quick Look opens and you’re staring at a wall of pound signs, asterisks, and pipe characters. You close it, open the file in something else, wait for it to load, and wonder why macOS still can’t render the most common text format on the internet. If you’ve ever searched “quicklook markdown”, “how to preview markdown files in Finder”, or tried to find the best markdown viewer Mac users actually like, you know the frustration.

We took React’s README from GitHub — a real, 2,000-line markdown file with headings, code blocks, tables, and links — and opened it in both Quick Look and MDHero. Here’s what each one showed us, plus when each tool wins. For the broader picture, see our complete Mac guide and full markdown viewer comparison.

The test file

React’s README.md is a good stress test. It has an H1, several H2s, inline code, fenced code blocks with JSX syntax, a table of links to documentation pages, nested lists, and badges. It’s the kind of file millions of developers encounter daily. If a markdown viewer can’t handle this, it can’t handle much.

We downloaded the raw file, dropped it into a Finder folder, and opened it two ways: Space bar for Quick Look, double-click for MDHero.

Quick Look: instant, but useless for reading

Quick Look opened in under 100 milliseconds. No complaints there — it’s genuinely fast. But what it showed was raw text.

Headings appeared as ## Installation — the literal ## characters followed by the text, in the same font and size as everything else. There was no visual hierarchy. The H1 at the top looked identical to a bullet point three pages down.

Code blocks were worse. A fenced block with ````jsx` just showed the backticks, the language hint, and the code — all in the same monospaced font, with no background, no highlighting, and no way to distinguish code from prose. If you didn’t already know what JSX looks like, you’d have no idea where the code started and ended.

Tables were the real disaster. Markdown tables use pipe characters and dashes to create structure: | Column | Column |. Quick Look rendered every pipe and dash literally. What should have been a clean two-column table looked like an ASCII art accident.

Links showed as [text](url) — brackets, parentheses, and all. Images showed as ![alt](path). Badges at the top of the file were a forest of [![ characters.

The file was technically readable in the way a JSON blob is technically readable. You could extract meaning from it if you already knew Markdown syntax. But you weren’t reading a document — you were parsing source code in your head.

The QLMarkdown fix (and its limits)

There is a middle path. A Quick Look plugin called QLMarkdown adds markdown rendering to the Space-bar preview. It’s open source, maintained, and genuinely useful.

brew install --cask qlmarkdown
xattr -d com.apple.quarantine /Applications/QLMarkdown.app
qlmanage -r

QLMarkdown works well for basic files. Headings get proper sizes, code blocks get backgrounds, and tables render as actual tables. It transforms the Quick Look experience from “useless” to “decent.”

But it has limits. There’s no syntax highlighting inside code blocks — all code is monochrome. KaTeX math expressions ($$\sum_{i=1}^{n}$$) render as raw LaTeX strings. Mermaid diagram blocks show as plain text. And since it’s a Quick Look plugin, you’re still confined to the Quick Look window: no tabs, no dark mode toggle, no way to keep the file open while you work on something else.

For a five-second peek at a simple file, QLMarkdown is a genuine improvement. For anything more, you hit the ceiling fast.

The simpler fix: MDHero’s own Quick Look extension

Since v0.2.10 you don’t need a separate plugin at all. MDHero installs a Quick Look extension alongside the app, so the Space preview renders Markdown using the same engine as the main window.

Setting it up is two steps and no Terminal:

1. Install MDHero and open it once — that’s what registers the extension with macOS.
2. Select any .md file in Finder and press Space.

If it still shows raw text, enable MDHero under System Settings → General → Login Items & Extensions → Quick Look.

The difference from QLMarkdown is what survives into the preview. Syntax highlighting inside code blocks, KaTeX math and Mermaid diagrams all render in the Quick Look panel — the three things the plugin route specifically can’t do. You get the fast Space glance and the real rendering, which previously required picking one.

MDHero: a native markdown viewer for Mac with full rendering

Opening the same React README in MDHero — a native markdown reader built specifically for Mac — showed a different document entirely. The H1 rendered large and bold at the top. H2s created clear section breaks. The visual hierarchy made it immediately obvious how the document was organized — you could scan the structure in two seconds.

Code blocks rendered with syntax highlighting. JSX keywords were colored, strings were distinct from variables, and each block sat inside a rounded container with a subtle background. You could tell at a glance where prose ended and code began.

The table of documentation links rendered as an actual HTML table — columns aligned, rows alternating, text wrapping cleanly. No pipes, no dashes, no mental parsing.

Links showed as clickable blue text. Badges rendered as actual badge images. The entire document looked like what you’d see on GitHub’s rendered view — except it was running locally, in a native window, with no browser tab or internet connection required.

Beyond the basics, MDHero handled things a bare preview panel can’t:

• Mermaid diagrams rendered as actual flowcharts and sequence diagrams
• KaTeX math showed as properly typeset equations
• Dark mode matched the system setting, or toggled independently
• Tabs let you open multiple files and flip between them
• Table of Contents sidebar, resizable, to jump to any heading instantly

The first two now carry over into Quick Look itself via MDHero’s extension. The rest — tabs, editing, find — are what the full window is still for.

The file opened in about 400 milliseconds — slower than Quick Look’s instant preview, but fast enough that you’d never notice in practice.

When Quick Look wins

Quick Look isn’t bad. It’s instant, it’s built in, and it requires zero installation. There are real situations where it’s the right tool:

• Five-second file identification. You’re in a folder with twelve .md files and you just need to find the right one. Hit Space, glance at the first few lines, hit Space again. Quick Look’s speed is unbeatable for this.
• Simple files. A three-line TODO.md or a short CHANGELOG.md doesn’t need syntax highlighting or rendered tables. Raw text is fine.
• Zero setup machines. You’re on a coworker’s Mac or a fresh install. Quick Look is already there. No Homebrew, no downloads, no permissions dialogs.

If your interaction with a markdown file lasts less than ten seconds, Quick Look is probably enough.

When MDHero wins

The moment you actually need to read the file — not just identify it — the calculus changes:

• Anything longer than a page. Without headings, hierarchy, and a table of contents, scrolling through a long document is a guessing game. Rendered markdown gives you structure.
• Files with code. Syntax highlighting isn’t a luxury when you’re reading a tutorial or a project README with installation commands. Monochrome code blocks hide bugs and confuse languages.
• Math and diagrams. If a file contains KaTeX equations or Mermaid flowcharts, Quick Look shows you the source markup. MDHero shows you the rendered output. There’s no workaround for this in Quick Look, even with QLMarkdown.
• Multiple files. Quick Look shows one file at a time in a transient window. MDHero lets you open tabs, keep files pinned, and switch between them — useful when you’re cross-referencing a README with a CONTRIBUTING guide.
• AI-pasted content. When you paste output from ChatGPT or Claude into a .md file, escaped newlines and formatting artifacts are common. MDHero’s LLM paste mode auto-cleans these. Quick Look shows them raw.

The hybrid approach: how to preview markdown files in Finder properly

You don’t have to choose. The best workflow uses both.

Keep Quick Look as your peek tool — Space bar in Finder for a fast glance, now rendered by MDHero’s extension rather than showing raw text. Then set MDHero as your default .md app so that double-clicking opens the file for real reading, with tabs, find and editing.

To set the default:

1. Right-click any .md file in Finder
2. Click Get Info (or Cmd+I)
3. Under Open with, select MDHero
4. Click Change All… and confirm

Now Space gives you a rendered preview and double-click opens the full app. Two tools, two jobs, zero conflict — and no plugin to re-authorise after every macOS update.

Quick Look was built to preview everything, which is why it never learned Markdown. MDHero was built to render Markdown — and as of v0.2.10 it lends that ability back to Quick Look, so the wall of ## characters is gone from both the preview and the app. Looking for more options? See our full comparison of free markdown viewers.