You download a project and find a file called README.md, or a colleague sends notes.md, and double-clicking it either opens the wrong program or nothing at all. A .md file looks mysterious, but it is one of the simplest document formats in common use: it is plain text.
What a Markdown file is
Markdown is a way of writing formatted text using ordinary keyboard characters. A line that starts with # is a heading, text wrapped in **double asterisks** is bold, and a line starting with - is a bullet point. Nothing is hidden inside the file: if you open it in any text editor you see exactly those characters.
John Gruber created the original Markdown syntax in 2004, working with Aaron Swartz on the idea. The goal was a format that is readable as-is, without looking like it is full of markup. Compare the same sentence in HTML and Markdown:
- HTML:
<p>This is <strong>important</strong>.</p> - Markdown:
This is **important**.
A program that understands Markdown turns the second form into formatted output. A program that does not still shows something a person can read.
Why .md files are everywhere
Markdown caught on because it is portable and diff-friendly. A .md file is just text, so version-control tools such as Git can show exactly which lines changed. That is why software projects use it for documentation (README.md, CONTRIBUTING.md, CHANGELOG.md), and why note-taking tools and static website generators use it for content.
The common extensions are .md and .markdown. Both mean the same thing. There is no special binary structure, no embedded fonts, and no hidden metadata unless the author adds a block of settings at the top (often called front matter).
What a Markdown file is not
A Markdown file does not store fonts, page size, margins or colours. Those choices belong to whatever program displays the file. Two people can open the same .md file and see it styled differently, because the file only describes structure: this is a heading, this is a list, this is a link.
That is the main difference from a Word document or a PDF. A .docx file is a zipped bundle of XML and media. A PDF fixes the layout of every page. A Markdown file is just words and symbols.
How to open a Markdown file
You have three options, depending on what you want to do.
- Read the raw text. Any text editor works: Notepad on Windows, TextEdit in plain-text mode on a Mac, or a code editor. You will see the formatting symbols.
- See it formatted. Use a Markdown viewer or editor with a preview. Many code editors have one built in. In the browser, Docento's Text & Markdown Editor opens a
.mdfile locally, shows a rendered preview, and lets you switch back to editing. The file is read on your device and is not uploaded. - On a phone. The Docento mobile app opens
.mdfiles from your file manager and shows them rendered; see how to open and edit .md files on Android.
How to edit a Markdown file
Edit the text and save. Because the file is plain text, any editor will do. A Markdown-aware editor adds conveniences: toolbar buttons for bold and lists, a live preview, and spell checking. Whichever you use, save the file with the .md extension, and make sure your editor saves as plain text rather than a rich-text format. If you accidentally save as .rtf or .docx, the Markdown symbols will no longer work as intended.
Common questions
Is Markdown the same as HTML? No. Markdown is much smaller and simpler, and many Markdown tools convert it to HTML. Most converters also let you include raw HTML inside a Markdown file for the cases Markdown cannot express.
Can I turn a Markdown file into a PDF? Yes. Our guide on converting Markdown to PDF covers the common routes. The editor above also has an Export PDF button for simple documents.
Is there only one Markdown? No, and this trips people up. The original description left some cases ambiguous, so several variants exist. See Markdown flavors explained.
Takeaway
A .md file is plain text with a few formatting conventions. You can open it in any editor, preview it in a Markdown-aware one, and convert it to other formats when you need to share it. If you want the quickest route, open it in the Text & Markdown Editor and flip between Edit and Preview.
