What Is an .md File?

An .md file is a plain-text file written in Markdown — a lightweight formatting language that turns simple symbols like #, ** and - into headings, bold text and lists when the file is rendered. You'll most often meet .md files as READMEs on GitHub, documentation, notes and configuration files for AI tools.

What's actually inside an .md file

Just text — with a few characters that carry formatting meaning. Here's the entire "language" of a basic file:

# Heading

This paragraph has **bold** and *italic* text, and a [link](https://example.com).

- a bullet list
- with two items

1. a numbered list
2. with two items

> A blockquote for emphasis

`code` for inline code

| Name | Role |
|------|------|
| Ada  | Dev  |

Rendered, that becomes a formatted page with a heading, styled text, lists, a quote, and a table. But the file itself, open in any text editor, is still 100% readable as-is — that's the point of the format.

Why .md files exist

Markdown was created in 2004 by John Gruber to let people write for the web without learning HTML. The format caught on because it hit a sweet spot:

• Plain text — no proprietary binary format, opens in literally any editor
• Version-control friendly — diffable, mergeable, reviewable like code
• Renders everywhere — GitHub, documentation sites, notes apps, chat tools
• It's the web's default — practically every developer platform speaks it

Where you'll meet .md files

• README.md — nearly every open-source project on GitHub, and the file that greets you in most repos
• Documentation — API docs, guides and wikis are often a set of .md files rendered into a docs site
• Notes — Obsidian, Logseq and similar tools store your notes as .md files you can always read elsewhere
• AI agent files — CLAUDE.md and AGENTS.md (see below) are plain Markdown files that tell coding agents how to work in a repo
• Blogs & drafts — many writers keep drafts as Markdown before publishing

.md vs .txt vs .docx

The .txt file is readable but unformatted; the .docx is formatted but proprietary. Markdown splits the difference: readable as text, renders as a document, and treats formatting as something you can review line by line.

How to open an .md file

Since it's plain text, every route works — the question is what you want out of it:

• Just read it: open it in VS Code preview, or view it on GitHub
• See the raw text: open it in Notepad, TextEdit or any text editor
• Full instructions: see how to open an .md file on Windows, Mac, Linux and mobile

How to create an .md file

Open any text editor, write text, save with a .md extension. That's genuinely all there is:

# My first document

Hello, world. **Bold words** cost nothing here.

GitHub will render it, your notes app will render it, your docs site will render it. No special software, no export step, no format conversion.

What about CLAUDE.md and AGENTS.md?

You'll see these two specific .md files increasingly often: they're how AI coding agents get project context. CLAUDE.md is read by Claude Code at session start; AGENTS.md is the emerging cross-agent convention. Both are normal Markdown — the magic is in who reads them.

Frequently asked questions

Is .md the same as Markdown? Yes. .md is just the filename extension for Markdown files (.markdown also exists). Markdown is the format.

What's the difference between .md and .markdown? Only the extension — the content is identical. .md is simply the more common of the two.

Can Word open .md files? Yes, as plain text — but it won't render the formatting. Use a Markdown viewer or converter for that.

Is a .md file safe to open? Plain text can't run code. Opening an .md file is no riskier than opening a .txt file.

Who uses Markdown? Developers (READMEs, docs), writers (drafts, publishing), note-takers (Obsidian), and now AI agents — increasingly, everyone.