MarsDawn

How to open .md files on Mac.

Double-click it. If your Mac opens it in a text editor and you see # and ** instead of headings and bold, the file is fine: a .md file is plain text, and that editor is showing the text as it is. Open it in an app that renders Markdown, such as MarsDawn, and make that app the default so every .md file opens there.

A .md file is plain text. The headings, bold words, tables and diagrams are written as marks: # for a heading, ** around bold, pipes for a table, a mermaid code block for a diagram. Open it in a plain text editor and you read the marks. To read the page the way its author meant, something has to render it.

Open a .md file on your Mac

  1. Double-click the file. It opens in the app your Mac has set for .md files. With no Markdown app, that is often a plain text editor, which shows the marks instead of the page.
  2. Pick the app yourself. Control-click the file and choose Open With, then the app. Or choose File ▸ Get Info (⌘I), pick an app under "Open with:", and click "Change All…" so every file of this type opens there. MarsDawn opens .md, .markdown, .mdown, .mkd and .mkdn files.
  3. Preview without opening it. Select the file in Finder and press Space. With MarsDawn installed, Quick Look shows the rendered page, diagrams included.

Read it in MarsDawn

MarsDawn is a Markdown editor for the Mac. It is free to download from the Mac App Store: try everything for 14 days, then unlock it once for USD 4.99. No subscription, no account. It needs macOS 26 or later.

Download on the App Store

Open a .md file and read the rendered page next to the source:

If an AI agent wrote the file, this is the loop MarsDawn is built for: the agent writes, you read it rendered, and it revises. See the home page, and marsdawn for agents for letting an agent open files for you. For why that reading matters and how to review a plan, see Reading what your agent hands back and Reviewing an agent plan in five minutes.

Without the app: turn it into a PDF

The free marsdawn command-line tool renders a Markdown file to a PDF, which any Mac can open. Tables, math, Mermaid diagrams and highlighted code come out rendered, and it needs nothing else installed, not even the MarsDawn app.

brew tap redtear1115/tap && brew install marsdawn
marsdawn export notes.md
open notes.pdf

export writes notes.pdf next to the Markdown file, and open shows it in your PDF viewer. It needs macOS 15 or later. The walk-through, with a real exported page, is on Markdown to PDF.

Questions

What is a .md file?

A .md file is a plain text file written in Markdown, a way of marking up text with simple characters: # for a heading, ** around bold, a pipe for a table cell. The extensions .markdown, .mdown, .mkd and .mkdn mean the same thing. Developers use it for READMEs and docs, and AI agents often hand back their plans and reports as .md files.

Why does my .md file open as plain text, with # and ** marks in it?

Because it is plain text, and a plain text editor shows it as it is. Nothing is wrong with the file. To see headings, bold, tables and diagrams, open it in an app that renders Markdown. In MarsDawn the rendered page sits next to the source.

Why does it open with garbled characters?

Garbled characters usually mean the file was saved in a text encoding other than UTF-8, and the app that opened it guessed wrong. The fix is to save a UTF-8 copy. MarsDawn opens a plain text file that isn't UTF-8 read-only, names the encoding it read it as in a bar at the top of the window, and offers Save As UTF-8… there, or File ▸ Save As… (⌥⇧⌘S), to write a UTF-8 copy you can edit.

Can I turn a .md file into a PDF?

Yes. In MarsDawn, choose File ▸ Export as PDF… (⌥⌘E) or File ▸ Print…; the pages are paginated, with diagrams drawn in and code highlighted, in the theme's light colors. Without the app, the free marsdawn export command-line tool makes the same PDF: marsdawn export notes.md. See PDF export and Markdown to PDF.

Can I open the .md files my AI agent wrote?

Yes, that is what MarsDawn is built for. Open the file and read the rendered page next to its source; when the agent revises it, open it again. An agent can also run marsdawn open plan.md to open the file in MarsDawn for you. See Reading what your agent hands back.

Next