What is Markdown?
Markdown is a text formatting syntax that lets you write content with simple symbols instead of HTML tags. Created by John Gruber in 2004, it's designed to be readable as-is while also converting cleanly to HTML.
# This is a heading
This is a paragraph with **bold** and *italic* text.
- Bullet point one
- Bullet point two
The brilliance of Markdown is that even without rendering, the source text is perfectly readable. Compare that to HTML's <strong>bold</strong> soup.
Basic Syntax
| Element | Syntax | Result |
|---|---|---|
| Heading | # H1 ## H2 ### H3 | Headings 1-6 |
| Bold | **text** or __text__ | text |
| Italic | *text* or _text_ | text |
| Link | [text](url) | Clickable link |
| Image |  | Embedded image |
| Code | `code` | Inline code |
| Blockquote | > quote | Indented quote |
| Horizontal rule | --- | Divider line |
Lists
Unordered:
- Item one
- Item two
- Nested item
Ordered:
1. First
2. Second
3. Third
Task list (GitHub):
- [x] Completed
- [ ] Todo
Code Blocks
Use triple backticks with an optional language for syntax highlighting:
```javascript
const greeting = "Hello, World!";
console.log(greeting);
```
Most renderers support syntax highlighting for dozens of languages.
Where You'll See This
- README files - The
README.mdin every GitHub repo - Documentation - Docs sites, wikis, technical writing
- Blogs - Static site generators like Jekyll, Hugo, Astro
- Notes - Obsidian, Notion, Bear, and most note apps
- Comments - GitHub issues, Reddit, Discord, Slack
- CMS platforms - Content fields in headless CMSs
Markdown Flavors
The original spec was intentionally minimal. Various platforms extended it:
| Flavor | Additions | Used By |
|---|---|---|
| CommonMark | Strict spec, consistent parsing | Standard reference |
| GFM | Tables, task lists, strikethrough, autolinks | GitHub |
| MDX | JSX components in Markdown | React docs, blogs |
| MultiMarkdown | Footnotes, tables, citations | Academic writing |
| Markdown Extra | Footnotes, abbreviations, tables | PHP Markdown |
Tables
Tables aren't in the original spec but are supported by GFM and most platforms:
| Name | Type | Default |
|---------|--------|---------|
| enabled | bool | true |
| timeout | number | 30 |
The alignment colons are optional:
:---left align:---:center---:right align
Common Gotchas
A single line break in Markdown doesn't create a new paragraph. You need a blank line between paragraphs, or end a line with two spaces for a <br>.
- Escaping special characters - Use backslash to escape:
\*not italic\* - Nested lists need 4 spaces - Or a tab. Two spaces might not work everywhere.
- No standard for everything - Tables, footnotes, and task lists aren't universal
- Angle brackets break -
<script>gets interpreted as HTML. Escape with backticks or backslash. - Trailing whitespace matters - Two spaces at line end = line break. Your editor might strip them.
Configure your editor to show trailing whitespace and not auto-trim it in .md files, or you'll lose intentional line breaks.
Example: Full Document
# Project Name
A brief description of what this does.
## Installation
```bash
npm install my-package
Usage
import { thing } from 'my-package';
thing.doStuff();
Features
- Fast and lightweight
- Zero dependencies
- TypeScript support
License
MIT
## Try It
<ToolCTA href="/markdown-to-html">Convert Markdown to HTML</ToolCTA>
<DevQuote>
"Markdown: Because life's too short for closing tags."
</DevQuote>