How to open a .md file on a Mac
Short answer: press the spacebar. Select the file in Finder, press space, and macOS renders it — if something on the Mac knows how. Out of the box nothing does, which is why a .md file opens as grey monospaced text or not at all. Install a reader and the spacebar starts working.
This page covers what the file actually is, the three ways to read one, and how to set what opens it by default.
What a .md file is
A .md file is plain text. You can open it in any editor and read every character of it — there is no binary format, no zip container, nothing proprietary. What makes it Markdown is a handful of conventions for marking structure inside that text: a line starting with # is a heading, **text** is bold, a line starting with - is a bullet.
# Release notes
- Fixed the thing that **crashed** on launch
- See `docs/setup.md` for the new steps
That is the whole trick. Markdown was written in 2004 by John Gruber so that a text file would stay readable as text while a program could also set it as a document. Twenty years later it is what GitHub READMEs, most note apps and most documentation sites are written in, which is why .md files end up on your Mac whether or not you ever chose to use them.
The extension varies a little: .md is the common one, .markdown, .mdown and .mkd show up too, and they are all the same thing.
Three ways to read one
The spacebar, in Finder
Quick Look is the fastest way, when something has taught macOS to render Markdown. Select the file, press space, read, press space again. No app opens, nothing loads, and you can walk through a folder of notes with the arrow keys.
This is what PreviewMD adds: a Quick Look extension and document thumbnails, so a folder of .md files looks like a folder of documents instead of a wall of identical blank icons. It is also the reason it is free — reading should not be the part you pay for.
An editor
Any Markdown editor opens one properly: you see the rendered page, you can type into the source, you can export. Which one to use depends on what you do with the file. If you mostly read and occasionally fix a line, a document-based app that leaves files where they are is the right shape. If you write all day with plugins and backlinks, a vault-style app will suit you better.
The browser, or TextEdit
Dragging a .md file into Safari shows the raw text, not a rendered page — the browser has no reason to treat it as Markdown. TextEdit shows the text too, and will happily save it back, which is fine for a quick fix. Neither renders tables, code highlighting or math.
Setting what opens .md files
macOS remembers one app per file type, and it is easy to change:
- Click a
.mdfile in Finder once to select it. - Press ⌘I, or choose File ▸ Get Info.
- Under Open with, pick the app you want.
- Click Change All… and confirm, so every
.mdfile follows.
Quick Look is separate from that choice. It is served by whichever installed app provides a Markdown preview extension, and it works even when the app itself is not running. If the spacebar is still showing plain text after installing a reader, open the app once — the system registers the extension on first launch — and check System Settings ▸ General ▸ Login Items & Extensions ▸ Quick Look.
Reading Markdown on this Mac
PreviewMD renders .md in Quick Look, draws document thumbnails in Finder, and opens into a window with the rendered page beside its source. It is free on Mac, iPad and iPhone, keeps no account, and leaves your files exactly where they are.
The Markdown cheat sheet on this site shows every mark and what it renders — on the left the result, on the right the source that produced it.