What Is a .md File? Markdown Explained

You clone a project from GitHub, open the folder, and find README.md, CHANGELOG.md and a docs folder full of .md files. They are all plain text, with a few extra characters marking headings, lists and bold words.

The file is just text

.md stands for Markdown, a way of marking up text that John Gruber published in 2004. There is no binary data in the file and no hidden formatting. Notepad opens it and you can read every word.

The only thing that sets it apart is the characters you add:

# Big heading

A paragraph with **bold**, *italic* and `inline code`.

## A list

- First item
- Second item

> A quote.

Hand the file to a Markdown reader and # turns into a heading, ** into bold text, - into a bullet. Left alone, the raw file still makes sense to a person reading it. That is why, more than twenty years later, Markdown is still the default for technical documentation.

Why not just use Word?

Because .md files are small, open in any program, and stay readable as plain text. The bigger reason is git. When you edit a .md file, git shows the exact lines that changed, so a colleague can review them. With .docx, git shows one line: the binary file changed. There is nothing to review.

	`.md`	`.docx`	`.txt`
Contents	Text plus markup characters	A ZIP package holding XML	Text only
Opens in	Any editor, any browser	Word, LibreOffice, Google Docs	Any editor
Formatting	Defined by the syntax	Defined by the word processor	None
Line-by-line diffs in git	Yes	No	Yes
Usually used for	READMEs, project docs, notes	Reports, contracts	Quick notes

Where you will run into them

More often than you might expect:

The front page of every GitHub and GitLab repository is a README.md. When you land on an unfamiliar project, that is the file to read first.
Project documentation: install guides, changelogs, API references.
Note apps such as Obsidian, Logseq and Joplin store notes as .md so you can take them anywhere.
Static sites built with Hugo, Jekyll, Astro or VitePress write posts in Markdown, then build HTML.

So how do I read one?

The quickest route is to open MDFrame and drag the file into the window. Nothing to install, the file stays on your machine, and you see the formatted page straight away. If you want to edit the content, open it in VS Code, Notepad++ or any text editor. Each platform has its own quirks, covered in how to open a .md file.

Frequently asked questions

Can Word open a .md file?

Not directly. Word opens it as plain text, so you get all the # and ** characters included. If the recipient needs a Word document, convert it to .docx first.

Can a .md file carry malware?

The file itself is text and runs nothing. The only risk is embedded HTML or JavaScript that an app renders without cleaning it first. MDFrame strips untrusted HTML before displaying a document.

Is .md the same as .markdown?

Yes. Same format, longer extension. A few older tools also use .mdown, .mkd or .mdx.

What is a .md file?