GitHub Markdown Guide

Markdown is the lingua franca of developer documentation. GitHub Flavored Markdown (GFM) extends the CommonMark spec with extra features like task lists, tables, and syntax-highlighted code blocks. This guide is a concise reference for everything you need.

Headers

Use # symbols to create headings. One # is the largest (H1), six is the smallest (H6):

# Heading 1
## Heading 2
### Heading 3
#### Heading 4

Text Formatting

**Bold text**
*Italic text*
~~Strikethrough~~
**_Bold and italic_**
`inline code`

Renders as: Bold text, Italic text, Strikethrough, and inline code.

Lists

Unordered list

- Item one
- Item two
  - Nested item
  - Another nested item
- Item three

Ordered list

1. First item
2. Second item
3. Third item

Links and Images

[Link text](https://example.com)
[Link with title](https://example.com "Hover tooltip")

![Alt text](image.jpg)
![Alt text](image.jpg "Image title")

Tip: For images in GitHub READMEs, store assets in a docs/ or .github/ folder in your repository and reference them with a relative path.

Code Blocks

Wrap code in triple backticks and specify the language for syntax highlighting:

```javascript
function greet(name) {
  return `Hello, ${name}!`
}
```

```python
def greet(name):
    return f"Hello, {name}!"
```

GitHub supports syntax highlighting for dozens of languages including JavaScript, TypeScript, Python, C#, Go, Rust, SQL, and more.

Tables

Create tables using pipes and hyphens:

| Column 1 | Column 2 | Column 3 |
| -------- | -------- | -------- |
| Cell A   | Cell B   | Cell C   |
| Cell D   | Cell E   | Cell F   |

Align columns with colons in the separator row:

| Left     | Center   | Right    |
| :------- | :------: | -------: |
| Left     | Center   | Right    |

Task Lists

Task lists are a GitHub-specific extension — useful for tracking work in Issues and PRs:

- [x] Completed task
- [ ] Incomplete task
- [ ] Another item to do

These render as interactive checkboxes on GitHub.

Blockquotes

> This is a blockquote.
> It can span multiple lines.
>
> And have multiple paragraphs.

Horizontal Rules

---
***
___

Any of these create a horizontal divider line.

Collapsible Sections

GitHub supports HTML <details> tags, which create expandable sections:

<details>
<summary>Click to expand</summary>

Hidden content goes here. Markdown works inside too.

</details>

Mentions and References

@username          # Mention a GitHub user
#123               # Reference an issue or PR by number
org/repo#123       # Cross-repository reference
SHA                # Reference a commit

Emoji

GitHub supports emoji shortcodes:

:rocket:  :white_check_mark:  :warning:  :bulb:  :book:

README Best Practices

• Start with a clear project title and one-line description
• Include a badges section (build status, licence, version)
• Add a quick-start or installation section early
• Document environment variables and configuration
• Include a contributing guide and licence statement
• Use a table of contents for long READMEs (GitHub auto-generates one for markdown headings)