Markdown is the universal language for developer documentation. READMEs, Notion docs, GitHub issues, pull requests, Slack messages, Discord — they all support some flavor of Markdown. This is the complete reference you can bookmark and return to.
Headings
# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6
Always add a space after the #. Some parsers require it; all accept it.
Text Formatting
**Bold text**
*Italic text*
***Bold and italic***
~~Strikethrough~~
`Inline code`
Renders as: Bold text, Italic text, Bold and italic, ~~Strikethrough~~, Inline code
Line Breaks and Paragraphs
First paragraph.
Second paragraph. (blank line between = new paragraph)
Line one
Line two (two spaces at end of line one = line break)
Links
[Link text](https://example.com)
[Link with title](https://example.com "Hover tooltip")
[Reference link][ref-id]
[ref-id]: https://example.com
Autolinks (bare URLs):
<https://example.com>
<user@example.com>
Images
![Reference image][img-ref]
[img-ref]: /path/to/image.png
Lists
Unordered list (use *, -, or + — be consistent):
- Item one
- Item two
- Nested item
- Another nested item
- Item three
Ordered list:
1. First item
2. Second item
3. Third item
The actual numbers don't matter — the output will always be sequential. This is valid:
1. First
1. Second
1. Third
Code
Inline code — single backticks:
Run `npm install` to install dependencies.
Fenced code block — triple backticks with optional language:
```javascript
const greeting = 'Hello, World!'
console.log(greeting)
```
Indented code block — 4 spaces:
function hello() {
return 'Hello'
}
Common language identifiers: javascript, typescript, python, bash, json, sql, html, css, go, rust, yaml, dockerfile
Blockquotes
> This is a blockquote.
>
> It can span multiple paragraphs.
>
> > Nested blockquote.
Horizontal Rule
---
***
___
All three produce a horizontal rule. --- is the most common.
Tables (GitHub Flavored Markdown)
| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Cell | Cell | Cell |
| Cell | Cell | Cell |
Alignment:
| Left | Center | Right |
|:---------|:--------:|---------:|
| aligned | aligned | aligned |
Colons control alignment: :--- left, :---: center, ---: right.
Task Lists (GitHub Flavored Markdown)
- [x] Write the article
- [x] Add code examples
- [ ] Publish
- [ ] Share on social media
Renders as interactive checkboxes on GitHub, Notion, and most modern Markdown renderers.
Footnotes
This is a statement with a footnote.[^1]
[^1]: This is the footnote content.
Supported in GitHub Flavored Markdown, Obsidian, and many static site generators.
Definition Lists (Extended Markdown)
Term
: Definition of the term
Another Term
: First definition
: Second definition
Supported in Pandoc, Python-Markdown, and some static site generators but not GitHub.
Escaping Special Characters
Backslash escapes Markdown special characters:
\*Not italic\*
\[Not a link\]
\`Not code\`
HTML in Markdown
Raw HTML is valid in most Markdown parsers:
<details>
<summary>Click to expand</summary>
Hidden content here. This is great for long lists or spoilers in GitHub READMEs.
</details>
<kbd>Ctrl</kbd> + <kbd>C</kbd>
GitHub-Specific Extensions
Mentioning users and teams:
@username
@org/team-name
Referencing issues and PRs:
#123 → links to issue/PR #123
org/repo#123 → cross-repo reference
Emoji:
:rocket: :tada: :white_check_mark:
Alerts (GitHub Docs Markdown):
> [!NOTE]
> Useful information for users.
> [!WARNING]
> Critical information requiring attention.
> [!TIP]
> Optional tip for better results.
Markdown in Different Contexts
| Platform | Flavor | |----------|--------| | GitHub | GitHub Flavored Markdown (GFM) | | GitLab | GitLab Flavored Markdown | | Notion | Notion subset (no raw HTML) | | Slack | Slack mrkdwn (different syntax) | | Discord | Discord Markdown (subset) | | VS Code | CommonMark + some GFM | | Obsidian | CommonMark + GFM + extensions |
Always check which flavor your platform uses — what works on GitHub may not render in Notion.
Convert Markdown Online
Use our free Markdown to HTML Converter to preview rendered Markdown and export the HTML output. Useful for checking how your Markdown will look before publishing.
Summary
- Headings use
#(1–6 levels), bold uses**, italic uses* - Code blocks use triple backticks with a language identifier
- Tables, task lists, and footnotes are GitHub Flavored Markdown extensions
- Escape special characters with a backslash
- Raw HTML works in most parsers — useful for details/summary and keyboard shortcuts
References & Credits
- CommonMark Specification — John MacFarlane et al., the standardized Markdown specification
- GitHub Flavored Markdown Specification — GitHub, Inc.
- Markdown Guide — Matt Cone — comprehensive free reference
- Daring Fireball: Markdown — John Gruber, the original Markdown creator
- marked — Christopher Jeffrey, the open-source Markdown parser used on WeHelpDevs