What Is a .md File? A Guide for Mac Users

You've seen .md files everywhere: on GitHub, in project folders, maybe sitting in your Downloads. Here's what they actually are and how to work with them on a Mac.

Zack Pennington ·
What Is a .md File? A Guide for Mac Users

You’ve probably run into a .md file at some point. Maybe it was a README.md on GitHub, a CHANGELOG.md in a project folder, or a random file someone sent you. You double-clicked it, your Mac opened it in TextEdit, and you saw a bunch of weird characters mixed in with normal text.

That .md file is a Markdown file, and once you understand what’s going on, it’s one of the most useful file formats out there.

Markdown in 30 seconds

Markdown is a plain-text formatting language created by John Gruber back in 2004. The idea is simple: write in plain text using a few lightweight symbols, and any tool that understands Markdown can render it into clean, formatted output.

The .md file extension is short for Markdown. That’s it. A .md file is just a text file with Markdown formatting inside.

What the syntax looks like

If you’ve never seen Markdown before, here’s the gist:

# This is a heading

Regular paragraph text with **bold** and *italic* words.

- Bullet list item
- Another item

1. Numbered list
2. Second item

[A link](https://example.com)

`inline code`

It’s readable even without rendering. That’s the whole point. Your content stays human-readable in its raw form, but looks polished when a Markdown-aware tool displays it.

Who uses .md files (and why)

Markdown has become the default writing format for anyone working in tech:

  • Developers write README.md files to document their projects on GitHub
  • Technical writers use it for documentation sites and knowledge bases
  • Note-takers use Markdown in apps like Obsidian for personal knowledge management
  • Bloggers write posts in Markdown for static site generators like Astro, Hugo, and Jekyll

The appeal is portability. A .md file is just plain text, so it works everywhere. You’re not locked into any app, any platform, or any proprietary format. You can open a Markdown file you wrote ten years from now and it’ll still make perfect sense.

How .md files differ from .txt and .doc

A .txt file is plain text with no formatting at all. What you see is what you get. No bold, no headings, no structure.

A .doc or .docx file is a binary format tied to Microsoft Word. It supports rich formatting, but you need specific software to open it, and the underlying file isn’t human-readable.

A .md file sits in between. It’s plain text (so any text editor can open it), but it contains lightweight formatting syntax that tools can render into styled output. You get structure and readability without the overhead of a binary format.

Where you’ll encounter .md files

Once you start looking, Markdown files are everywhere:

  • GitHub and GitLab: Every repository’s front page is rendered from a README.md
  • Documentation: Most open source docs are written in Markdown
  • Note-taking apps: Obsidian, Bear, and others store notes as .md files
  • Static site generators: Blog posts and pages are authored in Markdown
  • Project folders: CONTRIBUTING.md, LICENSE.md, CHANGELOG.md are standard conventions

How to open .md files on Mac

Here’s where things get a little awkward. macOS doesn’t have a built-in Markdown viewer. If you double-click a .md file, it’ll probably open in TextEdit or Xcode, neither of which renders the formatting.

You have a few options:

Quick Look. Select a .md file in Finder and press Space. Depending on your macOS version, you might get a basic preview.

VS Code. If you already have it installed, VS Code has solid Markdown support with a built-in preview pane.

mdMD. A free, native macOS Markdown editor that shows your raw source and a styled preview side by side. It’s built with SwiftUI and AppKit, so it launches instantly and feels like a proper Mac app. Good option if you want something lightweight and purpose-built.

Any text editor. Since .md files are plain text, you can open them in anything. You just won’t see the formatting rendered.

Start working with Markdown

The best way to get comfortable with .md files is to open one and start editing. Grab a Markdown editor, open a README.md from any project, and experiment with the syntax. Within five minutes, you’ll have the basics down.

Markdown has stuck around for over twenty years because it’s genuinely simple and useful. Once you learn it, you’ll wonder how you ever wrote documentation without it.