Markdown is the universal language of developer documentation. Whether you are writing a GitHub README, project wiki, or pull request description, mastering Markdown syntax lets you create professional, readable documentation in minutes. This cheat sheet covers every Markdown feature GitHub supports -- from basic formatting to Mermaid diagrams, math equations, and collapsible sections.
1. Basic Syntax: Headings, Bold, Italic, Links, Images
These are the foundational Markdown elements you will use in every document. They work identically across GitHub, GitLab, Bitbucket, and most Markdown renderers.
Headings
Source:
# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6Renders as: Six levels of headings, from largest (H1) to smallest (H6). Use only one H1 per document (typically your project name).
Bold & Italic
Source:
**bold text**
__also bold__
*italic text*
_also italic_
***bold and italic***
___also bold and italic___
~~strikethrough~~Renders as: bold text, italic text, bold and italic, and strikethrough.
Links
Source:
[Link text](https://example.com)
[Link with title](https://example.com "Hover title text")
[Relative link](./docs/guide.md)
[Reference-style link][ref-id]
[Section anchor link](#section-name)
<!-- Reference definition (placed anywhere in the doc) -->
[ref-id]: https://example.com "Optional title"Renders as: Clickable hyperlinks. Reference-style links let you define URLs once and reuse them. Anchor links jump to headings within the same page.
Images
Source:
<!-- Sized image using HTML -->
<img src="https://example.com/logo.png" alt="Logo" width="200">
<!-- Centered image -->
<p align="center">
<img src="./banner.png" alt="Banner" width="600">
</p>
<!-- Image as a link -->
[](https://example.com)Renders as: Inline images. Use HTML <img> when you need to control width, height, or alignment. Wrap an image in a link to make it clickable.
Lists
Source:
<!-- Unordered list -->
- Item one
- Item two
- Nested item
- Another nested
- Item three
<!-- Ordered list -->
1. First step
2. Second step
3. Third step
1. Sub-step A
2. Sub-step B
<!-- Mixed -->
1. Main item
- Detail A
- Detail B
2. Next itemRenders as: Bulleted and numbered lists. Indent with 2-4 spaces to create nested levels. You can mix ordered and unordered lists.
Blockquotes
Source:
> This is a blockquote.
> It can span multiple lines.
>
> > Nested blockquotes work too.Renders as: Indented text blocks with a left border, commonly used for quoting text or adding contextual notes.
Horizontal Rules
Source:
---
***
___Renders as: A horizontal divider line. All three syntaxes produce identical output. Use them to separate major sections.
Inline Code
Source:
Use `npm install` to install dependencies.
To escape backticks inside inline code, use double backticks:
``Use `code` here``Renders as: Monospaced text like npm install. Perfect for referencing commands, variables, filenames, and short code snippets within paragraphs.
2. GitHub Flavored Markdown (GFM)
GitHub extends standard Markdown with additional features called GitHub Flavored Markdown. These include task lists, strikethrough text, autolinks, and more.
Task Lists (Checkboxes)
Source:
- [x] Design the database schema
- [x] Implement REST API endpoints
- [ ] Write unit tests
- [ ] Deploy to production
- [ ] Update documentationRenders as: Interactive checkboxes. Checked items show a filled checkbox, unchecked items show an empty one. In GitHub Issues and PRs, these are clickable to toggle state.
Strikethrough
Source:
~~This text is struck through~~
~~Deprecated: Use newFunction() instead~~Renders as: This text is struck through. Useful for marking deprecated information or crossed-out items.
Autolinks
Source:
https://github.com
user@example.com
#123 (links to issue/PR #123)
@username (mentions a GitHub user)
SHA: a1b2c3d (links to a commit if valid)Renders as: GitHub automatically converts URLs, email addresses, issue numbers, @mentions, and commit SHAs into clickable links. No special syntax needed.
Footnotes
Source:
This claim needs a source[^1]. Another reference here[^note].
[^1]: Source: https://example.com/research
[^note]: This is a longer footnote with multiple paragraphs.
Indent subsequent paragraphs with 4 spaces.Renders as: Superscript numbers that link to footnote definitions at the bottom of the page. Great for citations and additional context without cluttering the main text.
3. Tables: Syntax, Alignment, Multi-Line Cells
Markdown tables are essential for documenting APIs, configuration options, and comparison matrices. GitHub supports column alignment and complex table structures.
Basic Table
Source:
| Feature | Free Plan | Pro Plan | Enterprise |
|---------------|-----------|----------|------------|
| Users | 5 | 50 | Unlimited |
| Storage | 1 GB | 100 GB | 1 TB |
| Support | Community | Email | 24/7 Phone |
| Custom domain | No | Yes | Yes |Renders as: A formatted table with a header row and data rows. Columns are separated by pipes (|) and the header is separated from data by a row of dashes.
Column Alignment
Source:
| Left-aligned | Center-aligned | Right-aligned |
|:-------------|:--------------:|--------------:|
| Left | Center | Right |
| Text | Text | Text |
| Data | Data | Data |Renders as: Columns aligned left (default), center, or right. Add colons to the separator row: :--- for left, :---: for center, ---: for right.
Tables with Formatting
Source:
| Method | Endpoint | Description |
|----------|-------------------|--------------------------|
| `GET` | `/api/users` | **List** all users |
| `POST` | `/api/users` | **Create** a new user |
| `GET` | `/api/users/:id` | Get user by *ID* |
| `PUT` | `/api/users/:id` | **Update** user |
| `DELETE` | `/api/users/:id` | ~~Remove~~ **Delete** user |Renders as: Tables support inline formatting inside cells -- bold, italic, code, strikethrough, and links all work inside table cells.
Multi-Line Cells (HTML)
Source:
<table>
<tr>
<th>Command</th>
<th>Description</th>
</tr>
<tr>
<td>
```bash
npm install
```
</td>
<td>
Install all dependencies from **package.json**.
Runs `preinstall` and `postinstall` scripts.
</td>
</tr>
<tr>
<td>
```bash
npm run build
```
</td>
<td>
Build the project for production.
Output goes to the `dist/` directory.
</td>
</tr>
</table>Renders as: HTML tables allow multi-line content, code blocks, and complex formatting inside cells that pure Markdown tables cannot handle.
4. Code Blocks: Language Hints & Diff Syntax Highlighting
Code blocks are arguably the most important feature for developer documentation. GitHub supports syntax highlighting for hundreds of languages and a special diff format for showing changes.
Fenced Code Blocks with Language
Source:
```javascript
function greet(name) {
return `Hello, ${name}!`;
}
console.log(greet('World'));
```
```python
def greet(name: str) -> str:
return f"Hello, {name}!"
print(greet("World"))
```
```bash
#!/bin/bash
echo "Installing dependencies..."
npm install
npm run build
```Renders as: Syntax-highlighted code blocks. Add the language identifier after the opening triple backticks. GitHub supports 200+ languages including javascript, python, bash, typescript, go, rust, java, c, cpp, csharp, ruby, php, swift, kotlin, sql, yaml, json, html, css, and more.
Diff Syntax Highlighting
Source:
```diff
- const API_URL = 'http://localhost:3000';
+ const API_URL = process.env.API_URL || 'https://api.example.com';
function fetchData() {
- return fetch(API_URL + '/data');
+ return fetch(API_URL + '/v2/data', {
+ headers: { 'Authorization': 'Bearer ' + token }
+ });
}
```Renders as: Lines starting with - are highlighted in red (removed), lines starting with + are highlighted in green (added), and unchanged lines have no highlight. Perfect for showing code changes in documentation.
Code Block with Filename
Source:
> **`src/config.ts`**
```typescript
export const config = {
port: parseInt(process.env.PORT || '3000'),
database: process.env.DATABASE_URL,
redis: process.env.REDIS_URL,
};
```Renders as: While Markdown does not natively support filenames on code blocks, you can use a bold inline code heading right above the block to simulate this common pattern.
5. Badges: shields.io Syntax & Common Badges
Badges provide at-a-glance project status information. They are powered by shields.io and are a staple of professional README files.
shields.io Basic Syntax
Source:
<!-- Static badge -->
<!-- Examples -->
<!-- Badge with logo -->
Renders as: Colored badges with labels, messages, and optional logos. The format is https://img.shields.io/badge/LABEL-MESSAGE-COLOR. Common colors: brightgreen, green, yellow, orange, red, blue, lightgrey.
Common Dynamic Badges
Source:
<!-- npm version -->
<!-- npm downloads -->
<!-- GitHub stars -->
<!-- GitHub issues -->
<!-- GitHub license -->
<!-- Build status (GitHub Actions) -->
<!-- Code coverage -->
<!-- Bundle size -->
Renders as: Dynamic badges that automatically update based on live data from npm, GitHub, Codecov, and other services. Replace owner/repo and package-name with your actual values.
Badge Layout in README
Source:
<!-- Badges on same line -->
  
<!-- Centered badges -->
<p align="center">
<a href="https://npmjs.com/package/my-lib"><img src="https://img.shields.io/npm/v/my-lib" alt="npm version"></a>
<a href="https://github.com/me/my-lib/blob/main/LICENSE"><img src="https://img.shields.io/github/license/me/my-lib" alt="license"></a>
<a href="https://github.com/me/my-lib/actions"><img src="https://img.shields.io/github/actions/workflow/status/me/my-lib/ci.yml" alt="build status"></a>
</p>Renders as: Badges arranged horizontally. Use HTML for centered badges or to make badges clickable links. Place badges right below your project title for maximum visibility.
6. Collapsible Sections: details/summary HTML
Collapsible sections keep your README clean by hiding verbose content behind a clickable toggle. GitHub renders the HTML <details> and <summary> elements natively.
Basic Collapsible
Source:
<details>
<summary>Click to expand</summary>
This content is hidden by default.
You can put **any Markdown** here:
- Lists
- Code blocks
- Tables
- Images
```javascript
console.log('Hidden code example');
```
</details>Renders as: A clickable triangle/arrow with the summary text. Clicking it reveals the hidden content. The content supports full Markdown formatting.
Open by Default
Source:
<details open>
<summary>Expanded by default</summary>
This content is visible when the page loads.
Users can click to collapse it.
</details>Renders as: Same as above, but the section starts expanded. Add the open attribute to the <details> tag.
Nested Collapsibles & Practical Examples
Source:
<details>
<summary><strong>Environment Variables</strong></summary>
| Variable | Required | Default | Description |
|-----------------|----------|-------------|-----------------------|
| `DATABASE_URL` | Yes | - | PostgreSQL connection |
| `REDIS_URL` | No | localhost | Redis connection |
| `PORT` | No | 3000 | Server port |
| `NODE_ENV` | No | development | Environment mode |
</details>
<details>
<summary><strong>Full Changelog</strong></summary>
### v2.0.0 (2025-01-15)
- Breaking: Renamed `config.js` to `config.ts`
- Added TypeScript support
- Removed deprecated `legacyMode` option
### v1.5.0 (2024-12-01)
- Added Redis caching
- Fixed memory leak in WebSocket handler
- Updated dependencies
</details>Renders as: Collapsible sections with rich content like tables and changelogs. Use bold text in the summary for emphasis. This pattern is ideal for environment variable docs, changelogs, and verbose configuration details.
7. Alerts / Callouts: [!NOTE], [!TIP], [!WARNING], [!CAUTION]
GitHub supports special blockquote-based alerts that render with colored icons. These are perfect for highlighting important information, tips, warnings, and breaking changes.
All Alert Types
Source:
> [!NOTE]
> Useful information that users should know,
> even when skimming content.
> [!TIP]
> Helpful advice for doing things better
> or more easily.
> [!IMPORTANT]
> Key information users need to know to
> achieve their goal.
> [!WARNING]
> Urgent info that needs immediate user
> attention to avoid problems.
> [!CAUTION]
> Advises about risks or negative outcomes
> of certain actions.Renders as: Five styled callout boxes with distinct colors and icons. NOTE is blue, TIP is green, IMPORTANT is purple, WARNING is yellow, and CAUTION is red. These only work on GitHub (not all Markdown renderers).
Alerts with Rich Content
Source:
> [!WARNING]
> **Breaking Change in v3.0**
>
> The `config.legacy` option has been removed.
> Migrate to the new format:
>
> ```diff
> - legacy: true
> + mode: 'modern'
> ```
>
> See the [Migration Guide](./MIGRATION.md) for details.Renders as: Alerts can contain bold text, code blocks, links, and other Markdown formatting. They are ideal for migration notices and deprecation warnings in README files.
8. Mermaid Diagrams: Flowchart, Sequence, Gantt
GitHub natively renders Mermaid diagrams inside fenced code blocks. You can create flowcharts, sequence diagrams, Gantt charts, and more without any external tools.
Flowchart
Source:
```mermaid
flowchart TD
A[Start] --> B{Is authenticated?}
B -->|Yes| C[Show Dashboard]
B -->|No| D[Show Login Page]
D --> E[Enter Credentials]
E --> F{Valid?}
F -->|Yes| C
F -->|No| G[Show Error]
G --> D
C --> H[End]
```Renders as: A visual flowchart with boxes, diamonds (decision points), and arrows. TD means top-down direction. Use LR for left-to-right. Node shapes: [rectangular], {diamond}, (rounded), ([stadium]).
Sequence Diagram
Source:
```mermaid
sequenceDiagram
participant Client
participant API
participant Auth
participant DB
Client->>API: POST /login {email, password}
API->>Auth: Validate credentials
Auth->>DB: Query user
DB-->>Auth: User record
Auth-->>API: JWT token
API-->>Client: 200 OK {token}
Client->>API: GET /data (Bearer token)
API->>Auth: Verify token
Auth-->>API: Valid
API->>DB: SELECT * FROM data
DB-->>API: Results
API-->>Client: 200 OK {data}
```Renders as: A sequence diagram showing interactions between participants over time. Solid arrows (->>) represent requests, dashed arrows (-->>) represent responses. Perfect for documenting API flows and authentication sequences.
Gantt Chart
Source:
```mermaid
gantt
title Project Roadmap Q1 2025
dateFormat YYYY-MM-DD
section Backend
API Design :a1, 2025-01-01, 14d
Implementation :a2, after a1, 21d
Testing :a3, after a2, 7d
section Frontend
UI Mockups :b1, 2025-01-01, 7d
Component Development:b2, after b1, 28d
Integration :b3, after a2, 14d
section DevOps
CI/CD Pipeline :c1, 2025-01-15, 7d
Staging Deploy :c2, after a3, 3d
Production Deploy :milestone, after b3, 0d
```Renders as: A Gantt chart with tasks, durations, dependencies, and milestones. Sections group related tasks. Use after taskId to define dependencies between tasks.
Other Mermaid Diagrams
Source:
<!-- Class Diagram -->
```mermaid
classDiagram
class User {
+String name
+String email
+login()
+logout()
}
class Admin {
+deleteUser()
+banUser()
}
User <|-- Admin
```
<!-- Pie Chart -->
```mermaid
pie title Language Distribution
"TypeScript" : 45
"Python" : 25
"Go" : 15
"Rust" : 10
"Other" : 5
```Renders as: Mermaid also supports class diagrams, pie charts, entity-relationship diagrams, state diagrams, and more. Check the Mermaid documentation for the full list of supported diagram types.
9. Math Equations: $inline$ and $$block$$
GitHub supports LaTeX math expressions using dollar-sign delimiters. Use single dollars for inline math and double dollars for block equations.
Inline Math
Source:
The quadratic formula is $x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$ where $a \neq 0$.
Einstein's famous equation: $E = mc^2$
The time complexity is $O(n \log n)$ in the average case.Renders as: Mathematical expressions rendered inline within a paragraph of text. Single dollar signs delimit inline math. The expressions render as properly formatted mathematical notation with fractions, square roots, superscripts, and symbols.
Block Math
Source:
$$
\sum_{i=1}^{n} i = \frac{n(n+1)}{2}
$$
$$
\int_{0}^{\infty} e^{-x^2} dx = \frac{\sqrt{\pi}}{2}
$$
$$
\begin{bmatrix}
a & b \\
c & d
\end{bmatrix}
\times
\begin{bmatrix}
e \\
f
\end{bmatrix}
=
\begin{bmatrix}
ae + bf \\
ce + df
\end{bmatrix}
$$Renders as: Centered, display-mode math equations. Double dollar signs create block-level equations. Supports summation notation, integrals, matrices, and virtually any LaTeX math expression. Equations appear on their own line and are centered.
Math in Code Blocks (Alternative)
Source:
```math
\left( \sum_{k=1}^n a_k b_k \right)^2
\leq
\left( \sum_{k=1}^n a_k^2 \right)
\left( \sum_{k=1}^n b_k^2 \right)
```Renders as: An alternative syntax using a fenced code block with the math language identifier. This is useful when dollar-sign delimiters conflict with currency symbols in your document.
10. Emoji: :emoji_name: Shortcodes
GitHub supports emoji shortcodes that render as emoji in Markdown files, issues, and pull requests. They add visual flair to your documentation.
Common Emoji Shortcodes
Source:
<!-- Status & Feedback -->
:white_check_mark: :x: :warning: :bulb: :memo:
<!-- Reactions -->
:+1: :-1: :heart: :star: :fire: :rocket:
<!-- Development -->
:bug: :wrench: :hammer: :gear: :package: :lock:
<!-- People & Gestures -->
:wave: :clap: :muscle: :eyes: :tada:
<!-- Arrows & Symbols -->
:arrow_right: :arrow_left: :arrow_up: :arrow_down:
:heavy_check_mark: :heavy_multiplication_x:
:information_source: :link:Renders as: Emoji icons corresponding to each shortcode. For example, :rocket: renders as a rocket icon, :bug: renders as a bug icon. GitHub supports hundreds of emoji shortcodes. You can also paste Unicode emoji directly.
Emoji in Context
Source:
## :rocket: Quick Start
### :package: Installation
```bash
npm install my-awesome-lib
```
### :gear: Configuration
See [config docs](./CONFIG.md).
### :bug: Known Issues
- :warning: Memory leak in v2.1 (fixed in v2.2)
- :white_check_mark: All tests passing
### :heart: Contributing
PRs welcome! :tada:Renders as: Emoji used as section icons in headings and inline markers for status. This is a popular pattern in open-source README files to make sections visually scannable.
11. README Template
A well-structured README is the front door to your project. Here is a complete template you can copy and customize for any repository.
<p align="center">
<img src="./assets/logo.png" alt="Project Logo" width="120">
</p>
<h1 align="center">Project Name</h1>
<p align="center">
<strong>One-line description of what your project does.</strong>
</p>
<p align="center">
<a href="https://npmjs.com/package/your-pkg"><img src="https://img.shields.io/npm/v/your-pkg" alt="npm"></a>
<a href="https://github.com/you/repo/actions"><img src="https://img.shields.io/github/actions/workflow/status/you/repo/ci.yml" alt="build"></a>
<a href="https://github.com/you/repo/blob/main/LICENSE"><img src="https://img.shields.io/github/license/you/repo" alt="license"></a>
</p>
---
## :sparkles: Features
- **Feature 1** -- Brief description
- **Feature 2** -- Brief description
- **Feature 3** -- Brief description
## :package: Installation
```bash
# npm
npm install project-name
# yarn
yarn add project-name
# pnpm
pnpm add project-name
```
## :rocket: Quick Start
```typescript
import { something } from 'project-name';
const result = something({
option1: 'value',
option2: true,
});
console.log(result);
```
## :book: API Reference
### `something(options)`
| Parameter | Type | Default | Description |
|-----------|-----------|---------|-----------------------|
| option1 | `string` | `-` | Required. Main input |
| option2 | `boolean` | `false` | Enable advanced mode |
| option3 | `number` | `10` | Max retry count |
**Returns:** `Promise<Result>`
<details>
<summary><strong>Full Options Reference</strong></summary>
| Parameter | Type | Default | Description |
|-----------|----------|--------------|--------------------------|
| timeout | `number` | `5000` | Request timeout (ms) |
| retries | `number` | `3` | Number of retry attempts |
| baseURL | `string` | `'/api'` | API base URL |
| headers | `object` | `{}` | Custom request headers |
</details>
## :wrench: Configuration
<details>
<summary><strong>Environment Variables</strong></summary>
| Variable | Required | Default | Description |
|---------------|----------|-------------|----------------------|
| `API_KEY` | Yes | - | Your API key |
| `DEBUG` | No | `false` | Enable debug logging |
| `PORT` | No | `3000` | Server port |
</details>
## :test_tube: Running Tests
```bash
# Run all tests
npm test
# Run with coverage
npm run test:coverage
# Run specific test file
npm test -- --grep "feature"
```
## :handshake: Contributing
Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) before submitting a PR.
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## :scroll: License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
---
<p align="center">
Made with :heart: by <a href="https://github.com/yourname">Your Name</a>
</p>Renders as: A complete, professional README with logo, badges, features, installation instructions, API reference, configuration, test commands, contributing guide, and license section. Copy this template and replace the placeholder values with your project details.
12. Frequently Asked Questions
What is the difference between Markdown and GitHub Flavored Markdown (GFM)?
Standard Markdown (CommonMark) defines core syntax like headings, bold, italic, links, and images. GitHub Flavored Markdown extends this with task lists, tables, strikethrough, autolinks, alerts, Mermaid diagrams, and math equations. GFM is a superset -- all standard Markdown works in GFM, but GFM features may not render on other platforms.
How do I add a table of contents to my GitHub README?
GitHub automatically generates a table of contents icon in the top-left corner of any Markdown file with multiple headings. For a manual TOC, create a list of links using anchor syntax: [Section Name](#section-name). GitHub auto-generates anchors from heading text by lowercasing and replacing spaces with hyphens.
Can I use HTML in GitHub Markdown?
Yes, GitHub supports a subset of HTML in Markdown files. Commonly used elements include <details>/<summary> for collapsible sections, <img> with width/height attributes for sized images, <br> for line breaks, <kbd> for keyboard keys, and <sub>/<sup> for subscript/superscript. However, <script>, <style>, and most event handler attributes are stripped for security.
How do I display images side by side in a README?
Use an HTML table with no borders: <table><tr><td><img src="img1.png" width="300"></td><td><img src="img2.png" width="300"></td></tr></table>. Alternatively, use the HTML <p align="center"> wrapper with multiple <img> tags. Standard Markdown does not support side-by-side images natively.
Why are my Markdown line breaks not showing on GitHub?
In Markdown, a single newline between lines is treated as a space, not a line break. To create a line break (soft return), end the line with two spaces before pressing Enter, or use an HTML <br> tag. To create a new paragraph, leave a blank line between text blocks. This is one of the most common Markdown gotchas for beginners.
Bookmark this cheat sheet and refer back to it whenever you are writing GitHub documentation. With these techniques, your README files will be clear, professional, and informative.