What Is Markdown?
Markdown is a lightweight markup language that converts plain text to formatted HTML. Created by John Gruber in 2004, it's now the standard for READMEs, documentation, blog posts, and developer notes across GitHub, GitLab, Notion, Obsidian, and most developer tools.
The philosophy: the source should be readable as-is, even without rendering.
Headings
# H1 — Page Title
## H2 — Section
### H3 — Subsection
#### H4 — Sub-subsection
Use one H1 per page (the document title). H2 for major sections, H3 for subsections.
Text Formatting
**bold text**
*italic text*
***bold and italic***
~~strikethrough~~
`inline code`
Renders as: bold, italic, bold and italic, strikethrough, inline code
Lists
Unordered:
- First item
- Second item
- Nested item (2 spaces indent)
- Another nested item
- Third item
Ordered:
1. First step
2. Second step
3. Third step
The actual numbers don't matter — Markdown auto-numbers them. Writing 1. 1. 1. still renders as 1, 2, 3.
Task lists (GitHub-Flavored Markdown):
- [x] Set up project structure
- [x] Write tests
- [ ] Add CI/CD
- [ ] Write documentation
Code Blocks
Inline code uses single backticks: const x = 1
Fenced code blocks use triple backticks with an optional language specifier for syntax highlighting:
```javascript
function greet(name) {
return `Hello, ${name}!`;
}
Common language specifiers: `javascript`, `typescript`, `python`, `bash`, `sql`, `json`, `yaml`, `css`, `html`, `diff`
**Diff syntax** highlights additions and removals:
```diff
- const old = "remove this"
+ const new = "add this"
Links and Images
Links:
[Link text](https://example.com)
[Link with title](https://example.com "Hover tooltip")
[Relative link](./docs/setup.md)
Reference-style:
[Google][google-ref]
[google-ref]: https://google.com
Images:
Add a link around an image to make it clickable:
[](https://example.com)
Tables
| Header 1 | Header 2 | Header 3 |
|-------------|-------------|-------------|
| Row 1, Col 1 | Row 1, Col 2 | Row 1, Col 3 |
| Row 2, Col 1 | Row 2, Col 2 | Row 2, Col 3 |
Alignment:
| Left | Center | Right |
|:-------------|:-------------:|-------------:|
| Left-aligned | Centered | Right-aligned |
The colons in the separator row control alignment.
Blockquotes
> This is a blockquote.
>
> It can span multiple paragraphs.
>
> > Nested blockquote
Horizontal Rules
Any of these create a horizontal divider:
---
***
___
GitHub-Flavored Markdown (GFM) Extras
GitHub's extended Markdown adds several useful features:
Mentions and references:
@username — links to a GitHub user
#123 — links to issue or PR #123
org/repo#123 — links to issue in another repo
Alerts (GitHub only, 2023+):
> [!NOTE]
> Highlights information users should notice.
> [!WARNING]
> Critical content demanding immediate attention.
> [!TIP]
> Helpful advice for better results.
Collapsible sections:
<details>
<summary>Click to expand</summary>
Hidden content here. Can contain any Markdown.
```bash
echo "Even code blocks"
Writing a Great README
A good README answers four questions immediately:
# Project Name
One-sentence description of what this does.
## Installation
```bash
npm install my-package
Usage
import { thing } from "my-package";
thing.doSomething();
API Reference
| Method | Description |
|---|---|
thing.doSomething() |
Does the thing |
License
MIT
Add badges from shields.io for build status, npm version, and license:
```markdown
Markdown Editors and Tools
- VS Code — built-in preview with Cmd/Ctrl+Shift+V. Extensions: Markdown All in One, Markdown Preview Enhanced
- Obsidian — knowledge management with Markdown at its core
- Typora — WYSIWYG Markdown editor
- markdownlint — lint your Markdown for style consistency
- Prettier — formats Markdown files (wraps long lines, normalizes syntax)
Escape Characters
To display a literal character that Markdown would normally interpret, prefix with backslash:
*Not italic*
# Not a heading
[Not a link](not-a-url)
Conclusion
Markdown is one of those rare tools where five minutes of learning pays dividends for the rest of your career. It's used in GitHub READMEs, issue trackers, pull requests, wikis, documentation sites, blog platforms, and note-taking apps. Learn the core syntax well, and you'll write clearer documentation across every tool in your workflow.
