Markdown cheatsheet · Open .md on Mac
Opening .md files on Mac
macOS opens .md files, but it never renders them: Quick Look and TextEdit both show you raw markdown. Here's what does render, and how to make a real app the default.
The fastest way: Quick Look
Select the file in Finder and press Space. Quick Look shows you the contents without opening any app at all.
The catch, and it's the reason this page exists: macOS shows .md files in Quick Look as raw text. You'll see ## Setup rather than a heading. It's the fastest way to read a file, and it doesn't render markdown.
Your options on Mac
| App | Renders markdown | Good for |
|---|---|---|
| Quick Look (Space) | No, raw text | A two-second glance |
| TextEdit | No | Raw text, already installed |
| Safari / Chrome | No, without an extension | Raw text |
| Xcode | Yes, sort of | Nothing, if you're not shipping apps |
| VS Code | Yes, in a preview pane | Developers |
| maxdown | Yes, in place as you type | Reading and writing .md properly. Free. |
| Typora | Yes | Same idea, $14.99 one-time |
TextEdit has one specific trap: it may open a .md file in rich text mode and start "helpfully" curling your quotes and capitalising things. If you're editing markdown in TextEdit, use Format → Make Plain Text (Shift+Cmd+T) first, or your file will pick up characters that break code blocks.
Making .md open in the app you want, permanently
This is the part people get stuck on, because doing it for one file doesn't do it for the rest.
- Click a
.mdfile once in Finder to select it. - Press Cmd+I (or right-click → Get Info).
- Open the Open with section.
- Pick your app from the dropdown.
- Click "Change All…", then confirm.
Opening a file from the Terminal
open notes.md uses your default app, whatever you set above. open -a "maxdown" notes.md forces a specific one without changing the default, which is handy when you usually want VS Code but occasionally want to read.
The "damaged and can't be opened" message
If you install a markdown app and macOS says it's damaged and can't be opened, the file is almost never damaged. That message means the app isn't signed with an Apple Developer certificate, which costs the developer $99 a year. Small and free apps often skip it.
To open it anyway: right-click the app and choose Open, then confirm. On recent macOS versions, go to System Settings → Privacy & Security and click Open Anyway. Do this only for software you deliberately downloaded from a site you trust.
Common questions
Why does Quick Look show raw markdown?
macOS treats .md as plain text and has no markdown renderer built in. Quick Look plugins exist that add one.
Why did my .md file open in Xcode?
Installing Xcode registers it for a pile of text formats, .md included, and it quietly becomes the default. Use "Change All…" above to take it back.
Can I edit markdown in Pages?
Don't. Pages will convert it into a Pages document, and you'll lose the plain-text file that made it markdown in the first place.