The short version

Install a Markdown app that ships a Quick Look extension, enable it in System Settings, then press Space on any .md file. That’s it — no Terminal, no config files.

Step by step

1. Install a Quick Look–capable Markdown app. Markdown Better View ships both a preview and a thumbnail extension; free options like PreviewMarkdown work too (see below).
2. Enable the extension. Open System Settings → General → Login Items & Extensions, scroll to Extensions, click the ⓘ next to Quick Look, and turn the app’s extension on. (On older macOS it’s System Settings → Extensions, or System Preferences → Extensions.)
3. Preview a file. Select any .md file in Finder and press Space. You should see it rendered — headings, lists, code blocks, tables.
4. Turn on thumbnails (optional). Enable the app’s thumbnail extension the same way. Finder then shows a rendered thumbnail for each Markdown file instead of a generic icon.

If Quick Look still shows raw text

This is common and almost always a registration glitch, not a broken app. In order:

1. Toggle the extension off and on in Login Items & Extensions.
2. Reset Quick Look from Terminal: qlmanage -r && qlmanage -r cache
3. Remove old duplicate copies of the app (extra copies in Downloads or build folders confuse macOS’ extension registry — keep one copy in /Applications).
4. Still stuck? Log out or restart — it clears the extension daemon’s cache.

Free vs paid

Free Quick Look extensions exist: PreviewMarkdown (free) and the open-source QLMarkdown (free, though its Homebrew cask is deprecated because it isn’t signed/notarized). They add a Finder preview and nothing more. If you mainly read Markdown and want a no-setup extension plus a full reader — table of contents, instant find, themes, reading mode, folder→tabs and live reload — Markdown Better View is a one-time $9.99 with no subscription. See the full best Markdown viewers for Mac roundup.

FAQ

Why does macOS show .md files as plain text in Quick Look?

Out of the box macOS has no Markdown Quick Look generator, so it falls back to its built-in plain-text preview and you see the raw # and * characters. Installing an app that ships a Quick Look extension adds a rendered preview for .md files.

How do I enable a Markdown Quick Look extension?

Install a Markdown app that includes one, then open System Settings → General → Login Items & Extensions, find Quick Look under Extensions, and turn on the app’s extension. Then select a .md file in Finder and press Space.

Quick Look still shows raw text after installing — how do I fix it?

Toggle the extension off and on in System Settings, then reset Quick Look from Terminal with “qlmanage -r && qlmanage -r cache” and, if needed, log out or restart. Also remove any old duplicate copies of the app (extra copies in Downloads or build folders confuse the extension registry).

Can I get rendered Markdown thumbnails in Finder too?

Yes, if the app ships a thumbnail extension. Enable it the same way under Login Items & Extensions, and Finder shows a rendered thumbnail for each .md file instead of a generic icon.

Is there a free way to preview Markdown in Finder?

Yes — free Quick Look extensions exist (for example PreviewMarkdown, or the open-source QLMarkdown, though its Homebrew cask is deprecated because it is unsigned). They preview in Finder but are not full reading apps. A paid viewer like Markdown Better View adds a no-setup extension plus a table of contents, find, themes, reading mode and live reload.