What is Markdown?
Markdown is a simple way to add formatting to plain text using ordinary characters. You put
# in front of a heading and ** around bold words, and a Markdown tool
shows the finished result. John Gruber created it in 2004, with help from Aaron Swartz, so that
people could write for the web without typing HTML.
A short example
The text on the left is all you type. It stays readable even before anything turns it into the formatted version on the right.
# Shopping list
Get these **today**:
- Bread
- Milk
More at [the shop](https://example.com).You can try this now in the online Markdown editor, or learn the rest of the basics.
Is Markdown a programming language?
No. Markdown is a markup language: it describes how a document is structured and doesn't run or calculate anything. It's also much smaller than HTML, another markup language, and most Markdown tools convert it to HTML to display it. People often say "the Markdown language" or "Markdown format", and they mean the same thing.
What is a .md file?
A .md file is a plain text file written in Markdown. The extension tells editors
and tools to treat the text as Markdown, and .markdown means the same thing. You
may have seen a README.md file in a software project, which is where GitHub and
similar sites look for a project's description.
How to open a .md file
A .md file is text, so any text editor can open it. To see it formatted, use one
of these:
- In your browser: open it in our online editor. There's nothing to install and the file isn't uploaded.
- On Windows: Notepad shows the raw text. Choose Open with to pick another app if double-clicking doesn't open it.
- On a Mac: TextEdit shows the raw text. Right-click the file and choose Open With to pick another app.
- In VS Code: open the file and press Ctrl+Shift+V, or Cmd+Shift+V on a Mac, for a formatted preview.
- In a dedicated app: see the directory of Markdown apps for desktop and mobile.
How to create a .md file
Write some text in any plain text editor and save it with a name ending in .md,
such as notes.md. Two common snags:
- In Notepad, set Save as type to All files, or you may get
notes.md.txt. - In TextEdit, choose Format, then Make Plain Text, before you save.
Or write it in the online editor and download it from there. To turn something you already have into Markdown, try Word to Markdown or rich text to Markdown.
What is Markdown used for?
- Software documentation: README files and project docs on GitHub and GitLab.
- Notes: apps such as Obsidian keep notes as Markdown files.
- Websites and blogs: many static site generators build pages from Markdown.
- Chat and forums: Discord, Reddit and others accept some of its syntax.
- Reports and papers: Markdown can be converted to PDF and Word.
Support varies a little from one app to the next. The compatibility table shows what works where.
Markdown and AI
You've probably already seen Markdown if you use an AI chat assistant, because they commonly
format their replies with it. Stray ** or # characters in a pasted
reply are Markdown that hasn't been displayed as formatting.
Markdown to rich text turns such a reply into
formatted text you can paste into a document.
It also works well in the other direction. Markdown keeps a document's headings, lists and tables without the extra tags of HTML, which makes it a tidy way to give documents to an AI tool. To prepare your files, you can convert them from PDF, Word or a web page.
Why use Markdown?
- It's readable as it is. The file makes sense before it's formatted.
- It works everywhere. Any device can open plain text, now and in the future.
- It's quick to learn. Most people need only a few symbols.
- It works with version control. Tools like Git can show exactly which lines changed.
Where to next
Read the basics for every core rule with examples, keep the cheat sheet handy, or explore the free Markdown tools.
Spotted a mistake? Let us know.