What Is an .md File?

The .md File Extension

A file ending in .md is a Markdown file — a plain-text document that uses simple formatting symbols to represent headings, bold text, links, lists, and code blocks. The most common example is README.md, the file that appears on the front page of almost every GitHub repository.

Markdown was created by John Gruber in 2004 as a way to write formatted content that is still easy to read in its raw form. Today it is used everywhere: documentation, notes, wikis, blogs, and technical specs.

What's Inside an .md File?

An .md file is just plain text with lightweight formatting. Here's what Markdown syntax looks like:

• # Heading — creates a heading
• **bold** — makes text bold
• - item — creates a bullet list
• [link](url) — adds a hyperlink
• `code` — inline code
• ``` — fenced code blocks

You can open any .md file in a basic text editor and read it, but a dedicated md file reader renders the formatting so you see headings, bold text, and code blocks as they were intended.

Where You'll Encounter .md Files

• GitHub & GitLab — README.md, CONTRIBUTING.md, CHANGELOG.md
• Documentation — API docs, project specs, architecture notes
• Note-taking — Obsidian, Bear, and other apps store notes as .md files
• Static site generators — Jekyll, Hugo, Astro use Markdown for content
• Developer workflows — meeting notes, ADRs, runbooks

How to Open .md Files on macOS

macOS doesn't include a built-in Markdown viewer. Here are your options:

• TextEdit — shows the raw syntax, no rendering
• Xcode — renders basic Markdown but is heavy and slow to launch
• VS Code — has a Markdown preview, but it's a full code editor
• Online Markdown viewer — drop a file in your browser, no install needed
• MDViewer — a native macOS app built specifically to view and edit .md files

Open .md Files Instantly with MDViewer

MDViewer is a free, native macOS md file reader built with SwiftUI. It does one thing well: open .md files and render them beautifully.

• Set as default app — double-click any .md file in Finder to open it instantly
• Tabbed interface — open multiple files in one window
• Smart table of contents — navigate long documents by heading
• Inline editing — double-click to edit, ⌘S to save
• Git history — browse file revisions and diffs without leaving the app
• GitHub Flavored Markdown — tables, task lists, code blocks with syntax highlighting

Requires macOS 13.0 or later. Intel and Apple Silicon.

FAQ

Can I edit .md files or just view them?

With MDViewer, you can do both. Double-click any word to enter edit mode, make your changes, and press ⌘S to save. Press Esc to return to reading.

Is .md the same as .markdown?

Yes. Both extensions refer to Markdown files. .md is the more common convention. MDViewer handles both.

Are .md files safe to open?

Yes. Markdown files are plain text — they cannot contain viruses or executable code. They are one of the safest file types you can open.

Can I convert .md to PDF?

Many Markdown editors support exporting to PDF. On macOS, you can also print from any app and choose "Save as PDF" from the print dialog.