PDFs and conversion

How to open and view Markdown files on a Mac

Updated 25 October 2026 · 3 min read

TextEdit and Quick Look show .md files as plain text. How to open Markdown on a Mac, preview it in an editor, or see it formatted with Space in Finder.

Markdown files, ending in .md, are plain text with a few symbols for headings, lists and links. READMEs, notes apps, documentation and AI tools all produce them. Every Mac can open them; the catch is that by default you see the symbols rather than the formatted page.

Open a .md file as text

Double-click a .md file and macOS opens it in whichever app is set for that type, often TextEdit or Xcode. TextEdit shows the raw text, with # before headings and ** around bold words. That is fine for editing and awkward for reading.

To choose the app, Control-click the file and choose Open With. To change it for every Markdown file, select one, press ⌘I, pick an app under Open with and click Change All.

Quick Look shows plain text

Select a .md file in Finder and press Space. Quick Look shows the file's text without formatting. Headings, tables and links appear as their Markdown source.

Preview in an editor

Many code editors include a Markdown preview. In Visual Studio Code, open the file and press ⇧⌘V to switch to the preview, or ⌘K then V to open it beside the source, according to Visual Studio Code's Markdown documentation, checked on 25 October 2026. That suits writing. For reading a file someone sent you, opening an editor each time is a lot of ceremony.

Quick Look extensions

Apps can add Quick Look extensions that teach Finder how to preview a type of file. A Markdown extension formats the file when you press Space, with no app to open. Two things to know:

• One extension wins. If several installed apps offer a Markdown preview, macOS uses only one. To choose, open System Settings › General › Login Items & Extensions, click the info button next to Quick Look and turn off the ones you do not want. On macOS Sonoma the list is in System Settings › Privacy & Security › Extensions › Quick Look.
• Old plug-ins no longer work. Since macOS Sequoia, Quick Look uses app extensions only. Older .qlgenerator plug-ins are ignored.

How Orrel does it

Orrel includes a Quick Look extension for Markdown. Once Orrel is installed in Applications and has been opened, select any .md file in Finder and press Space to see it formatted:

• The common syntax. Headings, lists, links, block quotes, code blocks, tables, task lists with their ticks, strikethrough and links written as plain web addresses.
• Front matter. The metadata block at the top of many notes and blog posts is shown as a small table rather than as stray text.
• Light and dark. The preview follows your Mac's appearance.
• Images beside the file. Pictures referenced with a relative path are shown. Images on the web are shown as links, so a preview never fetches anything from the network.

To share a formatted copy, Orrel's Convert turns a Markdown file into a PDF or an HTML page, written as a new file beside the original. Control-click the file in Orrel, drop it on Orrel's Dock icon or use Finder's Quick Actions.

Where Orrel stops

The preview is read-only; Orrel is not a Markdown editor. Code blocks are shown in a monospaced font without syntax colouring. HTML written inside a Markdown file is shown as text rather than run, and there is no support for diagrams or maths notation. Files larger than 2 MB show only their beginning, with a note saying so. If another app's Quick Look extension is chosen for Markdown, macOS uses that one instead, until you switch it off in System Settings.