How to Preview Markdown Files on Mac (Without Opening an App)

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, LaTeX and Mermaid.
• Glance is an App Store all-in-one that previews code files as well as Markdown.
• TypeFire installs one as part of the app, alongside a Markdown editor and a text expander.

If you only want previews and nothing else, QLMarkdown is the honest recommendation and it costs nothing.

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 colour. 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:

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.