What is Markdown?
What Markdown is, what a .md file contains and how to open one, where you will run into it, and how a 2004 blog-writing shortcut became the default format for docs, notes, and AI chat.
Short answer
Markdown is a lightweight markup language: plain text where symbols mark the formatting. # Title is a heading, **word** is bold, - item is a list item, and an app converts them to formatted text, usually HTML. John Gruber created it in 2004. A Markdown file is a plain text file ending in .md that any text editor can open.
A 30-Second Example
The left side is what you type. The right side is how most apps display it.
# A Markdown file
This paragraph has **bold** and *italic* text.
- First item
- Second item
Visit [MarkdownFormatting](https://markdownformatting.com).
Use `code` for variables.A Markdown file
This paragraph has bold and italic text.
- First item
- Second item
Visit MarkdownFormatting.
Use code for variables.
No tags and no toolbar. The #, *, -, brackets, and backticks carry all of the formatting. Try editing it yourself in the online Markdown editor.
What Is Markdown?
Markdown is a plain-text formatting syntax. Instead of typing <h1>Title</h1>, you type # Title. Instead of <strong>bold</strong>, you type **bold**. John Gruber created it in 2004, with Aaron Swartz as his main collaborator on the syntax, so he could write blog posts without hand-coding HTML.
Gruber described Markdown as two things: the syntax, and a tool that converts it to HTML. That split still holds. You write the syntax in any editor; a renderer (GitHub, a note app, a static site generator, a chat app) turns it into formatted output. The design goal was readability: a Markdown document should look sensible as plain text, before anything converts it.
There is no official standards body. The core syntax is pinned down by the CommonMark spec, and platforms add their own extensions on top, which is why a table that works on GitHub may show up as pipes and dashes somewhere else.
What Is a Markdown (.md) File?
A Markdown file is a plain text file that contains Markdown syntax and uses the .md extension. You can make one by saving any text file with a .md name. Because the formatting is part of the text, the same file works across operating systems, Git, and note apps without conversion.
| File extension | .md (the long form .markdown also works) |
|---|---|
| What is inside | Plain text, usually UTF-8. No binary data, no hidden formatting |
| MIME type | text/markdown, registered in RFC 7763 (2016) |
| Opens in | Any text editor. A Markdown app or viewer shows it formatted |
| Common names | README.md, CHANGELOG.md, CONTRIBUTING.md, AGENTS.md |
How to open a .md file
Any text editor shows the source, with the asterisks and hash marks visible. That is the file working correctly, not a broken download. To read it formatted:
- VS Code: open the file and press Ctrl+Shift+V (Cmd+Shift+V on a Mac), or Ctrl+K V for a side-by-side preview. See the VS Code Markdown guide.
- Windows 11: Notepad renders Markdown formatting since 2025. On macOS, TextEdit and Quick Look still show only the raw text.
- In the browser: drop the file on the Markdown viewer. It is read locally and never uploaded.
Markdown vs HTML vs Word
Markdown sits between the two formats people usually compare it to: as portable as HTML, nearly as easy to write as a Word document.
| Property | Markdown (.md) | HTML | Word (.docx) |
|---|---|---|---|
| File type | Plain text | Plain text | Zipped XML (.docx) |
| How formatting is written | Symbols: # ** - > | Tags: <h1> <strong> | Toolbar; stored out of sight |
| Readable without an app | Yes | Hard to read | No |
| Layout and styling control | Minimal | Full (with CSS) | Full |
| Clean Git diffs | Yes | Yes | No |
| Typical use | Docs, READMEs, notes, chat | Web pages | Print and shared office documents |
Need one of the others? The Markdown to HTML converter and Markdown to PDF converter run in your browser.
Where Is Markdown Used?
Almost every tool that handles text for developers or writers reads Markdown. These are the places you are most likely to meet it.
GitHub, GitLab, and source control
READMEs, issues, pull requests, and comments are written in Markdown. GitHub adds tables, task lists, alerts, footnotes, and math.
Documentation sites
Docusaurus, VitePress, MkDocs, Hugo, and most static-site generators build pages from Markdown files. Writers handle the words; the generator handles the HTML.
Note apps
Obsidian keeps every note as a plain .md file in a folder you choose, so the notes outlive the app. Notion, Bear, and others accept Markdown shortcuts as you type but store notes in their own format.
Chat and forums
Slack, Discord, Reddit, and Stack Overflow all format messages with Markdown or something close to it. Each platform adds its own quirks and limits.
AI assistants
ChatGPT, Claude, and Gemini format their replies in Markdown. Instruction files for AI tools, such as AGENTS.md, CLAUDE.md, and llms.txt, are Markdown files too.
Writing and publishing
Technical writers and bloggers draft in Markdown because it stays out of the way. One source file can become a web page, a PDF, a slide deck, or a Word document.
Markdown Flavors
A flavor is a dialect: the core syntax plus a set of extras. Headings, emphasis, links, lists, and code work in nearly all of them. What changes is everything else.
| Flavor | What it is |
|---|---|
| CommonMark | A precise spec of the core syntax with hundreds of test cases. Most modern parsers follow it, including the one behind VS Code's preview. |
| GitHub Flavored Markdown (GFM) | CommonMark plus tables, task lists, strikethrough, and automatic links. GitHub.com adds alerts, footnotes, and math on top. GitHub Markdown guide |
| Obsidian Flavored Markdown | CommonMark and GFM plus wikilinks, embeds, callouts, highlights, and comments. Obsidian guide |
| Chat apps | Discord, Slack, and Reddit each parse their own subset with their own rules. Slack's classic format, mrkdwn, uses *single asterisks* for bold. Discord formatting guide |
| Pandoc and MultiMarkdown | Writing-focused flavors with footnotes, citations, definition lists, and metadata, used for papers, books, and conversions to Word or PDF. |
The Markdown cheat sheet labels every syntax as CommonMark, GFM, or extended, so you can tell what will carry over.
A Short History of Markdown
2004
John Gruber publishes Markdown on Daring Fireball: a syntax plus a Perl script, Markdown.pl, that converts it to HTML. Aaron Swartz was his main collaborator on the syntax. Version 1.0.1, released that December, is still the last stable release.
2004-2014
Gruber's description leaves edge cases open, such as how far to indent a nested list, so the dozens of new implementations start to disagree.
2014
A group including John MacFarlane and Jeff Atwood publishes CommonMark, a strict spec with test cases. It was first announced as "Standard Markdown" and renamed after Gruber objected.
2016
RFC 7763 registers text/markdown as the official media type for Markdown files.
2017
GitHub publishes a formal GFM spec built on CommonMark and moves all Markdown on github.com to it.
2024
CommonMark 0.31.2, the current version, is released. There is still no 1.0.
Why Markdown Became the Default
Markdown is not the only lightweight markup language (reStructuredText and AsciiDoc both predate it), but it is the one most people reach for. A few reasons:
Readable source
Gruber's stated goal was a format that reads naturally as plain text. Even unrendered, the structure is obvious.
Small syntax
The core rules fit on one page. Most people are productive after ten minutes with a cheat sheet.
Supported everywhere
Code hosts, docs tools, note apps, chat apps, and AI assistants all read it, natively or through a converter.
Version-control friendly
Because the file is plain text, Git diffs stay clean and history stays useful.
HTML when you need it
Where the renderer allows it, as GitHub and most docs tools do, raw HTML fills the gaps. Chat apps strip it.
What Markdown Cannot Do
Markdown is intentionally limited. It was designed for writing, not page layout. Standard Markdown has no syntax for:
- Underlined text. Use HTML or a platform-specific trick; see the underline guide.
- Text color or font size. See the text color guide for workarounds.
- Centering, columns, or image sizes. HTML covers some of it; see centering text.
- Tables, task lists, or footnotes in the original syntax, though GFM and many other flavors add them.
The same Markdown can also render differently from app to app. When the output matters, test it where it will be read. The platform guides cover GitHub, Slack, Discord, Reddit, and Obsidian.
Quick Reference
The most common Markdown syntax in one table. The full cheat sheet has copy buttons and previews for every element.
| Element | Markdown | Result |
|---|---|---|
| Heading | # Title | Top-level heading |
| Bold | **text** | Bold text |
| Italic | *text* | Italic text |
| Link | [text](url) | Clickable link |
| Image |  | Embedded image |
| Unordered list | - item | Bullet list |
| Ordered list | 1. item | Numbered list |
| Inline code | `code` | Monospaced code |
| Code block | ```lang ... ``` | Code block, highlighted where supported |
| Blockquote | > quote | Quoted text |
| Horizontal rule | --- | Divider line |
Frequently Asked Questions
What is Markdown in simple terms?
Markdown is a way to format plain text with punctuation. You type # for a heading, **double asterisks** for bold, and backticks for code, and an app converts those characters into formatted text, usually HTML. The source stays readable even when nothing converts it.
What is a Markdown file?
A Markdown file is a plain text file with the .md extension (sometimes .markdown) that contains Markdown syntax. It holds no binary data or hidden formatting, so any text editor can open it, and any Markdown-aware app can display it formatted. README.md is the most common example.
How do I open a Markdown file?
Any text editor opens it, because it is plain text. To see it formatted, open it in VS Code and press Ctrl+Shift+V (Cmd+Shift+V on a Mac), use Obsidian, or drop it on a browser-based Markdown viewer. On Windows 11, Notepad renders Markdown itself; on macOS, TextEdit and Quick Look show the raw source.
Who created Markdown?
John Gruber created Markdown in 2004 and published it on his site, Daring Fireball, with Aaron Swartz as his main collaborator on the syntax. Gruber's version 1.0.1 from December 2004 was the last; CommonMark (2014) and GitHub's GFM spec (2017) now define how it is parsed.
Is Markdown the same as HTML?
No. Markdown is a shorthand that is usually converted to HTML before it is displayed. HTML is the output and gives full control over layout; Markdown is a faster, more readable way to write the common parts. Most renderers also accept raw HTML inside Markdown for anything the syntax cannot express.
What is the difference between Markdown and a Word document?
A Markdown file is plain text where the formatting is visible as symbols, so it opens anywhere and works well with Git. A Word .docx file is a zipped package of XML that needs Word or a compatible app, stores formatting out of sight, and offers full page layout. Pandoc can convert between the two.
Is Markdown a programming language?
No. Markdown is a markup language. It describes structure and formatting, but it has no variables, logic, or commands to run.
Do all apps use the same Markdown?
No. CommonMark defines the core syntax, and most apps agree on it. GitHub Flavored Markdown adds tables, task lists, strikethrough, and automatic links. Obsidian adds wikilinks and callouts, Slack's classic mrkdwn uses *single asterisks* for bold, and Discord has its own rules. Core syntax mostly carries over; the extras do not.
Can I use Markdown for a website?
Yes. Static site generators like Hugo, Eleventy, Astro, and Jekyll build whole sites from Markdown files, and Next.js can render them through MDX. To convert a single file, use Pandoc, a library like marked, or an online Markdown to HTML converter.
Got handed a .md file?
If a README opened as raw punctuation, nothing is wrong with it. That is what the file contains. Drop it on the Markdown viewer to read it formatted, or see how to open .md files on Windows, Mac, and mobile.