Markdown is a plain text formatting language. You write it in any text editor, and software converts it into formatted HTML. A word like **bold** becomes bold. A line that starts with # becomes a heading. That's the whole idea.
John Gruber created Markdown in 2004, together with Aaron Swartz. Gruber's design philosophy was simple: a Markdown file should be readable without being rendered. If you open a .md file in Notepad, the formatting marks should feel natural, not like noise. That's what sets it apart from HTML, where tags like <strong>bold</strong> clutter the reading experience.
Markdown spread quickly from developer blogs to GitHub, documentation platforms, note-taking apps, and messaging tools. Today it's one of the most widely used writing formats on the internet.
Why people use Markdown
Markdown works for several audiences who each find something different to like about it.
Developers use it because GitHub renders .md files automatically. Every repository README, pull request comment, and issue description on GitHub accepts Markdown. It's also the default format for documentation tools like MkDocs, Docusaurus, and GitBook.
Writers and bloggers use it because it keeps them focused on words. There's no toolbar to click, no formatting dialog to dismiss. You write, and you get formatted output when you're done.
Note-takers use it in apps like Obsidian and Notion, where Markdown files stay portable. If you switch apps, your files move with you as plain text.
Content teams use it because Markdown separates content from presentation. Designers control how pages look through CSS; writers just write.
Core syntax
These are the constructs you'll use in almost every Markdown document.
Headings
Prefix a line with one to six # symbols. The number of symbols maps to the HTML heading level.
# Heading 1
## Heading 2
### Heading 3
Bold and italic
Wrap text in asterisks or underscores.
**bold text**
*italic text*
***bold and italic***
Links and images
Links use square brackets for the text and parentheses for the URL. Images follow the same pattern with an exclamation mark at the front.
[Visit md0](https://md0.io)
Lists
Unordered lists use a hyphen. Ordered lists use a number followed by a period.
- First item
- Second item
- Third item
1. Step one
1. Step two
1. Step three
You can use 1. for every ordered list item. The renderer handles the incrementing automatically.
Code
Backticks wrap inline code. Triple backticks create a fenced code block. Add a language name after the opening backticks to get syntax highlighting.
Run `npm install` to get started.
```javascript
function greet(name) {
return `Hello, ${name}!`;
}
### Blockquotes
Start a line with `>` to create a blockquote.
```markdown
> This is a quoted passage. You can use it for citations,
> callouts, or pulled quotes.
GitHub Flavored Markdown
GitHub ships its own extension of Markdown, called GitHub Flavored Markdown (GFM). You'll encounter these features constantly if you work with GitHub repositories.
Tables use pipes and hyphens to define columns and rows.
| Name | Type | Required |
|----------|--------|----------|
| title | string | yes |
| date | string | yes |
| excerpt | string | no |
Task lists render as checkboxes inside issues and pull requests.
- [x] Write the post
- [ ] Add images
- [ ] Publish
Strikethrough wraps text in double tildes.
~~This sentence is no longer accurate.~~
GFM also supports syntax-highlighted fenced code blocks, emoji shortcodes (:rocket:), and automatic link detection for bare URLs.
Where Markdown shows up
Markdown is everywhere now, though not every platform uses exactly the same flavor.
GitHub and GitLab render .md files and accept Markdown in issues, pull requests, and wikis. If you write code, you probably already use Markdown without thinking about it.
Notion converts Markdown-style syntax as you type. Start a line with ## and Notion turns it into a heading immediately.
Obsidian stores every note as a plain .md file. This is one of its biggest selling points: your notes are never locked into a proprietary format.
VS Code has a built-in Markdown preview pane. Open any .md file and press Ctrl+Shift+V (or Cmd+Shift+V on macOS) to see the rendered version beside your raw text.
Reddit uses a Markdown-based editor. Asterisks for bold, backticks for inline code, > for blockquotes.
Discord and Slack support a subset of Markdown in messages: bold, italic, code blocks, and strikethrough all work.
How to start writing Markdown
You need a text editor that can open .md files and a way to preview the result. Several good options exist at different levels of commitment.
If you want to start in your browser right now, the md0 editor gives you a split-pane view: raw Markdown on the left, rendered output on the right. Paste some text, add a # before the first line, and you'll see the heading appear instantly. You can also convert your document to HTML using the md0 Markdown to HTML tool.
If you prefer a dedicated app, Obsidian is free for personal use and stores everything as local .md files. VS Code works well if you're already using it as a code editor.
Once you're comfortable with the basics, keep the md0 Markdown cheatsheet bookmarked. It covers every standard syntax element in a single reference page.
Frequently asked questions
Is Markdown the same as HTML?
No. Markdown is a source format; HTML is the output. When a Markdown processor encounters **bold**, it converts that to <strong>bold</strong> in HTML. You write Markdown, and the tool produces HTML. Most Markdown processors also accept raw HTML inline, so you can mix the two when Markdown alone doesn't cover what you need.
Does Markdown replace word processors?
For most purposes, no. Word processors like Google Docs or Microsoft Word are better for documents that need precise layout control, tracked changes in a collaborative review workflow, or complex formatting like mail merge. Markdown is the better fit for structured writing that will be published to the web, read in a terminal, or stored in version control. Many people use both: Markdown for technical writing and docs, word processors for reports and proposals.
What is the .md file extension?
.md stands for Markdown. It's the most common extension for Markdown files, though .markdown is also valid. Most editors and platforms recognize .md automatically. On GitHub, a file named README.md in a repository root gets rendered on the repository's homepage. You can open .md files in any text editor since they're just plain text with formatting marks.