macOS ships with no way to read a Markdown file as its author intended. Double-clicking a .md file opens it in TextEdit as raw text, Quick Look shows the same unformatted source, and Preview declines it entirely. For a README that is merely inconvenient. For a design document carrying Mermaid diagrams, tables, and LaTeX math, the raw source is close to unreadable.
This covers the routes that actually render Markdown on a Mac, and which ones survive a document with diagrams in it.
| Method | Result |
|---|---|
| Double-click | Opens in TextEdit as plain text — symbols visible, nothing rendered |
| Quick Look (spacebar) | Shows the raw source, no formatting |
| Preview.app | Will not open Markdown at all |
open -a Safari file.md |
Downloads or shows plain text; browsers do not render Markdown natively |
| Xcode | Syntax highlighting only, no rendered preview |
The common thread is that none of them render. Markdown is a plain-text format, and without something to convert it, macOS treats it exactly as it treats a .txt file.
That final check matters more than the choice of app. Most Mac Markdown tools handle headings, lists, and tables competently. Support for Mermaid diagrams and LaTeX math is where they diverge sharply, and that is exactly the content that fills architecture documents and AI-generated technical writing.
Nothing needs to be installed to read a Markdown file. Open mdview.io, drag the .md file onto the page, and it renders immediately — headings, GFM tables, syntax-highlighted code, task lists, LaTeX math through KaTeX, and Mermaid diagrams with zoom, pan, fullscreen, and SVG or PNG export.
The file is read in the browser, so it works the same on an Intel or Apple Silicon Mac, on a managed work machine where installing software is restricted, and on someone else's computer. If the document needs to reach a colleague, publishing it produces a share link rather than an attachment they will also be unable to open.
| Category | Examples | Notes |
|---|---|---|
| Editor with preview pane | VS Code, Obsidian, CotEditor | Built for writing; preview fidelity and diagram support vary by extension or plugin |
| Dedicated previewer | Marked-style preview apps | Watches a file and re-renders on save; pairs with a plain text editor |
| Note apps that import Markdown | Bear, Notion | Convert the file into their own document model rather than rendering it as-is |
| Browser-based renderer | mdview.io | No install, consistent rendering, diagram and math support built in |
Anything that converts Markdown into its own internal format — the third row — is worth treating carefully for technical documents. Import is lossy in ways that are easy to miss: a Mermaid block can survive as a fenced code block that never becomes a diagram, and math delimiters are frequently mangled.
Quick Look can be extended to preview Markdown, and several community plugins add it. The tradeoff is that a Quick Look plugin renders a static preview: fine for reading prose, but it will not give you a zoomable diagram or a working table of contents, and it needs reinstalling after some macOS updates. It suits skimming a README, not reviewing an architecture document.
If the file is already in a terminal session, rendering it there avoids the round trip through Finder. Command-line renderers print formatted Markdown directly to the terminal, which suits reading a README inside a repository you are already working in. Viewing Markdown in the terminal covers the tools and their limits — chiefly that diagrams cannot be drawn in a text terminal.
The reason a Mac user goes looking for a Markdown viewer is usually not a shopping list. It is a technical document — an architecture overview, a runbook, a specification generated by an AI assistant — and those are dense with exactly the content that basic renderers drop.
A Mermaid block that a tool does not understand appears as a wall of code. Math written in LaTeX appears as raw delimiters. A wide table becomes horizontally unreadable. Rendering the diagram is the whole point of opening the file, so it is worth confirming a tool does it before committing to a workflow.
If a diagram is malformed — common in Markdown produced by a language model — mdview.io's Fix MD repairs broken Mermaid, mangled tables, and bad math delimiters rather than simply failing to draw them.
Any text editor will show the source. To see it rendered, either drag it onto a browser-based renderer such as mdview.io or open it in an application with a Markdown preview pane.
No. Preview.app handles images and PDFs; it does not render Markdown.
TextEdit displays the file's literal contents. Those symbols are the Markdown syntax itself — they are meant to be converted into headings and emphasis by a renderer.
Open the renderer in a browser and drop the file in. No installation, and it behaves identically on a locked-down work machine.
An installed editor with a preview pane works offline. A browser-based renderer needs the page loaded, after which the file itself is read locally in the browser rather than uploaded.
TextEdit, as plain text. macOS has no default Markdown renderer, which is why a separate tool is needed to see formatting.
macOS handles Markdown as raw text because that is what Markdown is. The question is what converts it, and for technical documents the answer has to include diagrams and math, not just bold and bullets.
mdview.io renders Markdown as the reader will receive it — Mermaid with zoom, pan, and export, KaTeX math, GFM tables, syntax-highlighted code — with nothing to install on the Mac. For the equivalent on other platforms, see Markdown viewers for Windows and Linux.