How to Open and Read .md Files on Your Mac

You downloaded a project from GitHub. There's a README.md file. You double-click it on your Mac — and get a wall of raw text full of hashtags and asterisks. Frustrating. Sound familiar?

You're not alone. macOS has no built-in Markdown renderer. TextEdit loads .md documents as plain text, displaying the raw syntax instead of formatted headings, code blocks, and diagrams. Searches for “how to open md file on mac” have increased 191% year-over-year (DataForSEO, 2026) — the problem is growing as Markdown becomes the default format for developer documentation, project READMEs, and technical notes.

Here are 5 ways to open .md files on Mac with proper formatting, from zero-install options to a dedicated native viewer. Our top pick is MacMD Viewer, a native macOS Markdown viewer ($9.99, SwiftUI, 2 MB) — it is not an editor, it is a dedicated viewer that does not require a subscription or internet connection.

TL;DR: macOS opens .md files in TextEdit as plain text — no formatting, no headings, no code blocks. To open .md files on Mac with proper rendering, use a QuickLook extension (press Space in Finder), VS Code with preview (Cmd+Shift+V), or install a dedicated viewer like MacMD Viewer that renders Mermaid diagrams and syntax highlighting natively.

What Is an .md File and Why Can't Mac Open It Properly?

An .md file is a Markdown document — a lightweight text format created by John Gruber in 2004 that employs plain text symbols to represent formatting. Every GitHub repository includes at least one .md file (the README), making Markdown the de facto standard for developer documentation (GitHub Docs). Some .md files are hidden by default — learn how to view hidden files on Mac.

Symbols like # become headings, **text** becomes bold, and triple backticks create code blocks. Note-taking applications like Obsidian and Bear also adopt .md as their native format. If you work in tech, you encounter these documents daily.

The problem isn't opening the file — it's rendering it. macOS treats .md files as plain text and opens them in TextEdit by default. You see raw syntax like ## Installation instead of a formatted heading. For a deeper look at rendering options across platforms, see our guide to viewing Markdown files.

Markdown (.md) is a lightweight text format used in every GitHub repository and most developer documentation. macOS has no built-in Markdown renderer — it displays .md files in TextEdit as plain text, showing raw syntax symbols instead of formatted headings, code blocks, and tables.

How to Open .md Files in TextEdit (Method 1 — Built-In)

TextEdit loads .md documents immediately with zero setup. But it shows raw Markdown syntax — not formatted text. No headings, no code highlighting, no tables. Just symbols.

Steps

1. Right-click the .md file in Finder
2. Select Open With > TextEdit
3. The file opens as plain text with raw Markdown syntax visible

This works for quick text searches or minor edits to the raw content. But if your document has code blocks, tables, or Mermaid diagrams? They're unreadable. You'll see backticks and pipe characters instead of formatted output.

Verdict: Fine for peeking at raw content. Not useful for actually reading a Markdown document with proper formatting.

TextEdit is the only zero-install option for opening .md files on Mac, but it shows raw Markdown syntax instead of rendered output. For formatted headings, code blocks, tables, and diagrams, you need a dedicated Markdown viewer or editor.

How to Preview .md Files with QuickLook (Method 2 — Fastest)

Press Space on any .md file in Finder and see it rendered instantly — if you set up a QuickLook extension first. This is the fastest method because you never leave Finder. Here's why it matters. Interest in QuickLook Markdown tools has surged — related searches are up over 1,300% year-over-year (DataForSEO, 2026).

Option A: QLMarkdown (Free, Open Source)

QLMarkdown is a free QuickLook generator available on GitHub. Deploy it via Homebrew:

brew install --cask qlmarkdown

After installing, enable it in System Settings > Privacy & Security > Extensions > QuickLook. It renders basic Markdown formatting — headings, lists, code blocks, and links. Doesn't handle Mermaid diagrams.

Option B: MacMD Viewer's QuickLook Extension

MacMD Viewer ($9.99) includes a QuickLook extension for Markdown that renders Mermaid diagrams and syntax highlighting directly in the Finder preview. It works everywhere QuickLook does — Finder, Spotlight, and Open dialogs.

For step-by-step installation, read our complete QuickLook setup guide.

QuickLook is the fastest way to preview Markdown on Mac. With a QuickLook extension installed, pressing Space on any .md file in Finder shows the rendered document instantly — no app launch, no window switching, no waiting.

How to View .md Files in VS Code (Method 3 — For Developers)

Visual Studio Code renders Markdown documents with a single keyboard shortcut: press Cmd+Shift+V to toggle a formatted preview of any open .md file. With over 15 million monthly active users (Microsoft, 2025), VS Code is the most widely adopted tool capable of previewing Markdown on Mac.

Steps

1. Open the .md file in VS Code (File > Open, or drag and drop)
2. Press Cmd+Shift+V to open the rendered preview
3. Or press Cmd+K V for side-by-side view — editing on the left, preview on the right

What program opens a .md file? VS Code is the most commonly cited answer in Google's People Also Ask results. It's free, cross-platform, and renders Markdown out of the box.

But there are trade-offs. VS Code is a 300+ MB download — heavy just to read a text document. It doesn't render Mermaid diagrams without adding an extension. And if you're not a developer? The interface can feel overwhelming.

VS Code is the most popular free tool for previewing Markdown on Mac, with over 15 million monthly active users. Its built-in preview (Cmd+Shift+V) renders headings, lists, code blocks, and tables — but requires extensions for Mermaid diagrams.

How to Read .md Files with MacMD Viewer (Method 4 — Native Mac App)

If you regularly need to open .md files on Mac, MacMD Viewer is a native macOS application built with SwiftUI that displays them with Mermaid diagram support, syntax highlighting, live file watching, and a QuickLook extension. At 2 MB, it's 150x smaller than VS Code. Purpose-built for reading, not editing. Available at macmdviewer.com for $9.99 one-time.

Steps

1. Download MacMD Viewer ($9.99 one-time)
2. Open any .md file — it renders instantly with full formatting
3. Set as default: right-click a .md file > Get Info > Open With > MacMD Viewer > Change All

What makes it different from VS Code or a text editor? It's purpose-built for reading, not editing. You get:

• Mermaid diagrams rendered inline (flowcharts, sequence, Gantt)
• Syntax highlighting for every major language
• Live file watching — edit in VS Code, see changes in MacMD Viewer instantly
• Table of contents sidebar for navigating long documents
• Dark mode that follows your system preference

We built MacMD Viewer because no existing tool handled this well on Mac. Editors like Typora focus on writing. Viewers like Marked 2 cost $13.99 and lack Mermaid support. MacMD Viewer does one thing — render .md content — and does it right. See all MacMD Viewer features.

MacMD Viewer is a native macOS application that renders .md files with Mermaid diagram support, syntax highlighting, a table of contents sidebar, and a QuickLook extension. At 2 MB, it delivers a focused reading experience for $9.99 one-time.

How to View .md Files in Your Browser (Method 5 — No Install on Mac)

Browser extensions render Markdown documents directly in Chrome or Firefox without installing a native Mac application. Add the “Markdown Viewer” extension from the Chrome Web Store, then drag any .md file into a browser tab to see it formatted.

The limitations are significant. Browser extensions only work for content you explicitly load in the browser — there's no system-wide integration. You can't double-click a .md file and have it open rendered. No Mermaid diagram support. You also need to grant file access permission in chrome://extensions.

When is this useful? You're on a work laptop with restricted installs, and you need to read one document quickly. That's it.

Browser extensions like Markdown Viewer for Chrome can render .md files in a browser tab without installing native software. However, they lack system integration — you can't set them as the default .md handler — and don't support Mermaid diagrams or syntax highlighting.

Which Method Should You Use to Open .md Files on Mac?

For most users, MacMD Viewer ($9.99) is the best way to open .md files on Mac — it renders everything including Mermaid diagrams in a native 2 MB app. For quick one-off previews, a free QuickLook extension lets you press Space in Finder. Developers already using VS Code can use its built-in preview. Here's the full comparison:

The short version:

• Need to peek at a file once? Install QLMarkdown and press Space in Finder.
• Read .md files regularly for work? MacMD Viewer — native, fast, and handles everything including Mermaid diagrams.
• Already coding in VS Code? Use the built-in preview. It's good enough for quick checks.

For Mac users who open .md files daily, the most effective setup combines MacMD Viewer as the default app (for full rendering with Mermaid diagrams and syntax highlighting) with its QuickLook extension for instant Finder previews. This two-tool approach covers every scenario from quick peeks to deep documentation reading.

Frequently Asked Questions