How to Preview Markdown on Mac with Quick Look (Press Space)

Select a .md file in Finder, press space, and macOS shows you raw source: visible hashes, visible asterisks, pipe characters where a table should be.

The file is readable, technically. It is just not rendered. Here is every way to fix that.

Why macOS does this

Quick Look renders file types it has a generator for: images, PDFs, plain text, video. Markdown is registered as plain text, so you get exactly that, the characters in the file.

Apple has never shipped a Markdown Quick Look generator. The fix in every case below is installing something that provides one.

Method 1: a Quick Look extension

The direct fix. Install an app that registers a Markdown preview generator, and space in Finder starts rendering.

• QLMarkdown is free, open source and actively maintained, with brew install --cask qlmarkdown. It handles headings, lists, code blocks, tables, math and Mermaid. Open it once after installing so macOS finds the extension.
• Markdown Preview by Anybox is $1.99 on the App Store, with Mermaid and math, on macOS 12 and up.
• TypeFire registers its extension on install with nothing to open first, and the same app edits the file on double click, keeps the folder as notes, and adds a clipboard manager and a text expander. It does not render Mermaid or math.

If you only want the preview and nothing else, QLMarkdown costs nothing and renders the most. If you also write Markdown, TypeFire is one install instead of two. The full list of Quick Look plugins covers code and video too.

Method 2: open it in something

Slower, but no installation of a preview extension:

• TextEdit opens .md as plain text, so this does not help
• Safari will not render it either, since Markdown is not HTML
• A Markdown editor such as Typora, MacDown or Obsidian renders it once opened

The gap here is obvious: you have to open an app for every file you want to glance at, which is exactly what Quick Look exists to avoid.

Method 3: the terminal

If you live in a shell, glow and mdcat render Markdown to a terminal with formatting and color. Both are good, and both are irrelevant if you are browsing in Finder.

Method 4: convert it

Pandoc turns Markdown into HTML or PDF, which you can then preview normally. Useful for publishing, absurd for reading a README.

What good looks like

Whichever you pick, a Markdown preview should handle:

• Headings, lists, quotes, links and images, the basics
• Tables, which is where thin implementations fall over first
• Code fences with syntax highlighting, which is most of why developers want this
• Task lists, the - [ ] checkboxes GitHub Flavored Markdown added

If you preview READMEs, GitHub Flavored Markdown support is the thing to check, because plain CommonMark renderers will not do tables or task lists.

After you install it

Select a .md file and press space. If you still see raw source, the ordered fixes are here. The short version:

1. Open the app once, so macOS registers its extension
2. Check System Settings, then General, then Login Items and Extensions, and confirm the Quick Look extension is enabled
3. If it is still stubborn, qlmanage -r in Terminal reloads Quick Look generators

Doing it as part of something you already run

TypeFire installs a Quick Look extension for Markdown, so space in Finder renders any .md file on your Mac, whether TypeFire created it or not. It also edits Markdown, can be set as your default .md app, and includes a text expander for the repetitive parts of writing Markdown.

All of that is free. Download for Mac or read the Markdown feature tour.