nicemdGuides
Reading Markdown
on a Mac.
Short, practical answers for anyone who has just been handed a .md file and would rather not install a code editor to read it.
Claude made a .md file. Here is how to open it.
You asked for a plan, a spec or a summary and got back a file full of hashes and asterisks. Nothing is wrong with it. Your Mac just has no idea how to show it.
What is a .md file?
A plain-text document with a little formatting, and the format AI tools write in. Here is what it is, how to open one, and what README.md, CLAUDE.md and PLAN.md are for.
How to open a .md file on a Mac
Double-clicking gives you TextEdit and a screen full of symbols. Here is how to open it as a readable document instead, and how to make that stick.
Markdown viewers for Mac
macOS has no Markdown viewer of its own. Here are the options for viewing .md files as formatted documents, from free to a few dollars, and what each one is good for.
Markdown Quick Look on macOS
Space renders PDFs, images, spreadsheets and Keynote decks. On a .md file it shows you asterisks. Here is why, and how to fix it in about a minute.
Markdown without VS Code
Every answer online says install a code editor. You wanted to read a document. Here is the short route, and where the shortcuts have teeth.
Quick Look Markdown not working
You installed the app. You pressed Space. You still see asterisks. Nine things cause this, and they are worth checking in order.
Previewing a README on your Mac
The commit-push-refresh loop to check whether your README looks right is a slow way to proof a document. It renders locally in one keystroke.
Viewing Mermaid diagrams on a Mac
GitHub turns a mermaid code fence into a diagram. Locally it stays a code fence — and increasingly the diagrams are the part worth reading.
How to read Claude Code plans and AI Markdown on a Mac
Claude Code, Codex, ChatGPT and Claude all hand you Markdown. Here is where those files are, and how to read them as documents instead of as code.
Previewing agent output in Finder
Press Space on a .md file and macOS shows you asterisks. Here is exactly why, and what to do instead of changing what your agent writes.
Why your Markdown preview goes stale when an agent edits the file
Coding agents replace files instead of rewriting them. Most preview windows are watching the file that no longer exists.
Plan files you can actually check off
Your agent writes a task list. Ticking a box should edit the file — not open an editor, and not live only in your head.