The complete guide to viewing Markdown files on Mac in 2026

If you’ve ever double-clicked a .md file and seen it open in TextEdit — raw asterisks, pound signs, and all — you know the problem. Whether you’re trying to view markdown files Mac users actually enjoy reading, or just figure out how to open .md files on macOS, this guide covers every option worth knowing.

Why .md is everywhere now

Markdown used to be a developer thing. Now it’s the default for READMEs, LLM output, Claude Code plans, Substack drafts, Obsidian notes, and every product spec written after 2022. If you work with text, you open .md files. A lot.

The trouble is macOS has never really known what to do with them. Finder shows a generic icon. Double-click opens TextEdit. Preview refuses. Quick Look shrugs. For a format this common, the out-of-the-box experience is surprisingly bad — and finding a good markdown viewer Mac users actually enjoy shouldn’t be this hard.

Option 1 · Quick Look (built-in, but limited)

The first thing people try when figuring out how to view markdown files on Mac is Quick Look. Hit Space on a selected file in Finder and macOS shows you a preview. For images and PDFs, this is magic. For Markdown, it’s… fine.

Quick Look shows raw text with no rendering — headings, lists, and code blocks all look the same. You can install a Quick Look plugin like QLMarkdown to fix this, but it requires a Terminal command and a permissions tango with Gatekeeper.

# Install QLMarkdown with Homebrew
brew install --cask qlmarkdown

# Remove Apple's Gatekeeper flag so it actually loads
xattr -d com.apple.quarantine /Applications/QLMarkdown.app

# Restart the Quick Look server
qlmanage -r

Verdict: Good for a five-second peek. Not something you want to read a 2,000-line README in.

Option 2 · VS Code preview

If you already have VS Code open, Cmd+Shift+V renders the markdown beside the source. It’s fast, it’s GitHub-flavored, and you probably have it installed.

The catch: VS Code is an IDE. Launching it just to read a note pulls in 400MB of editor, a file tree you don’t want, and a title bar that says “workspace.” It’s the wrong tool for reading.

Option 3 · Browser extensions

Chrome and Firefox both have extensions (Markdown Viewer, Markdown Preview Plus) that render local .md files when you drag them into a tab. This works — but only if you remember to enable “Allow access to file URLs” in extension settings, and only if your browser isn’t already cluttered with tabs.

It also means your reading experience is at the mercy of whichever browser you’re using and whichever themes it’s applying. Consistency is not this tool’s strength.

Option 4 · Native markdown viewer for Mac (the good path)

A native markdown viewer is a small app whose primary job is to render Markdown — no file tree, no extensions to configure, no permanent editing toolbar. Double-click a file, read it, close it. The newer ones (like MDHero) also let you flip into a focused editor when you need to fix a typo, then save and get out. This is the best markdown reader experience on macOS.

The main options on Mac in 2026 (see our full comparison for details):

• MDHero — free, open source, ~8MB. Syntax highlighting, KaTeX, Mermaid, tabs. Reads Claude Code plans natively. As of v0.2.0, includes a built-in lightweight editor (Cmd+E to toggle, Cmd+S to save).
• Macdown — classic choice, but development has slowed since 2022.
• Marked 2 — excellent, but $15 and more focused on writer-with-preview workflows than reading.
• Typora — a hybrid editor/viewer. Great if you also edit; overkill if you just read.

# Option A — Homebrew (coming soon)
brew install --cask mdhero

# Option B — direct download
# https://mdhero.app
open "https://github.com/vaibhavuk-dev/mdhero/releases/latest"

The 30-second default-app fix

Whatever markdown viewer for Mac you pick, make it the default app. Otherwise double-click still opens TextEdit.

1. Right-click any .md file in Finder.
2. Choose Get Info (or hit Cmd+I).
3. Expand Open with, pick your viewer, then click Change All…
4. Confirm the prompt. Done.

Edge cases worth knowing

LLM-pasted Markdown

When you paste output from ChatGPT or Claude into a text file, newlines often come through as literal \n characters. Most viewers render this as a wall of backslashes. Look for one that auto-detects and unescapes — MDHero does this with Cmd+Shift+V. We wrote a deeper guide on fixing AI paste formatting if you run into this often.

GitHub URLs

Pasting a GitHub file URL into a good viewer should fetch and render it. This saves you the “clone the repo just to read the README” dance.

Claude Code plans

Claude Code writes plans to ~/.claude/plans. Point your viewer at that folder and you can flip through recent plans like inbox mail — see our Claude Code plans guide for the workflow.

“The best tool is the one that disappears. For reading Markdown, that means opening in under a second and getting out of your way.”

The verdict

Use Quick Look for 5-second peeks. Use VS Code when you already have it open and the file is small. Use a native markdown viewer for everything else — which, if you’re reading Markdown daily, is most of the time.

MDHero is the best free markdown viewer for Mac — native, lightweight, and open in two seconds. If you’ve made it this far, try it and let us know what’s missing. Also available on Windows.