Markdown is the standard way to format text on GitHub. Whether you're writing README files, creating issues, commenting on pull requests, or building documentation, understanding GitHub Flavored Markdown (GFM) is essential for effective communication in the developer community.
What You'll Learn: In this comprehensive guide, you'll master:
- Basic Markdown syntax (headings, paragraphs, emphasis)
- Text styling (bold, italic, strikethrough)
- Creating links and images
- Code blocks and syntax highlighting
- Lists (ordered, unordered, nested)
- Task lists for tracking progress
- Tables for organized data
- Blockquotes and alerts
- GitHub-specific features
What is GitHub Flavored Markdown?
GitHub Flavored Markdown (GFM) is GitHub's extension of standard Markdown. It adds features like:
- Task lists with checkboxes
- Tables
- Syntax-highlighted code blocks
- Auto-linking URLs
- Strikethrough text
- Emoji support
Where GFM is Used: README.md files, Issues, Pull Requests, Comments, Wiki pages, Gists, and GitHub Discussions.
Headings
Create headings using # symbols. More # means smaller heading:
# Heading 1 (Largest)
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6 (Smallest)
Best Practice: Use headings hierarchically. Don't skip levels (e.g., don't go from H1 to H4).
Text Styling
Bold Text
**This is bold text**
__This is also bold__
Result: This is bold text
Italic Text
*This is italic*
_This is also italic_
Result: This is italic
Bold and Italic
***Bold and italic***
___Also bold and italic___
**_Another way_**
Result: Bold and italic
Strikethrough
~~This text is crossed out~~
Result: ~~This text is crossed out~~
Combining Styles
This is **bold**, this is *italic*, and this is ~~strikethrough~~.
You can also do ***bold italic*** or **_bold italic_**.
Quoting Text
Blockquotes
Use > to create blockquotes:
> This is a quote.
> It can span multiple lines.
> You can also have
>
> Multiple paragraphs in a quote.
Result:
This is a quote. It can span multiple lines.
Nested Blockquotes
> First level quote
>> Nested quote
>>> Even deeper
Code
Inline Code
Use backticks for inline code:
Use the `git status` command to check your repository.
Result: Use the git status command to check your repository.
Code Blocks
Use triple backticks for code blocks:
```
This is a code block
Multiple lines work here
```
Syntax Highlighting
Specify the language after the opening backticks:
```python
def hello():
print("Hello, World!")
```
```javascript
function greet(name) {
console.log(`Hello, ${name}!`);
}
```
```bash
git clone https://github.com/user/repo.git
cd repo
npm install
```
Common language identifiers: python, javascript, js, typescript, ts, bash, shell, json, yaml, html, css, sql, go, rust, java, c, cpp, ruby, php
Links
Basic Links
[Link Text](https://example.com)
Result: Link Text
Links with Titles
[GitHub](https://github.com "Visit GitHub")
Hover over the link to see the title.
Auto-linking
GitHub automatically converts URLs to links:
Visit https://github.com for more info.
Reference-Style Links
[GitHub][1] is where developers collaborate.
[1]: https://github.com
Useful for keeping text readable when you have many links.
Section Links
Link to headings within the same document:
See the [Installation](#installation) section below.
GitHub automatically creates anchors for headings (lowercase, spaces become hyphens).
Images
Basic Image
Image with Title
Image from Repository
Linking an Image
[](https://example.com)
Lists
Unordered Lists
Use -, *, or +:
- Item 1
- Item 2
- Item 3
* Also works
* With asterisks
+ Or plus signs
+ Your choice
Ordered Lists
1. First item
2. Second item
3. Third item
Numbers don't have to be sequential:
1. First
1. Second (still renders as 2)
1. Third (still renders as 3)
Nested Lists
- Parent item
- Child item
- Another child
- Grandchild
- Another parent
Result:
- Parent item
- Child item
- Another child
- Grandchild
- Another parent
Mixed Lists
1. First ordered item
- Unordered sub-item
- Another sub-item
2. Second ordered item
1. Ordered sub-item
2. Another ordered sub-item
Task Lists
GitHub's special feature for tracking progress:
- [x] Completed task
- [x] Another completed task
- [ ] Incomplete task
- [ ] Another todo item
Result:
- [x] Completed task
- [x] Another completed task
- [ ] Incomplete task
- [ ] Another todo item
Pro Tip: In GitHub Issues and PRs, you can click the checkboxes to toggle them!
Task Lists in Issues
## Sprint Tasks
- [x] Set up development environment
- [x] Create database schema
- [ ] Implement user authentication
- [ ] Write unit tests
- [ ] Deploy to staging
GitHub shows a progress bar for issues containing task lists!
Tables
Create tables using pipes | and hyphens -:
| Header 1 | Header 2 | Header 3 |
|----------|----------|----------|
| Cell 1 | Cell 2 | Cell 3 |
| Cell 4 | Cell 5 | Cell 6 |
Column Alignment
| Left | Center | Right |
|:-----|:------:|------:|
| L | C | R |
| Left | Center | Right |
:---= Left align:---:= Center align---:= Right align
Table Example
| Command | Description |
|---------|-------------|
| `git status` | Show working tree status |
| `git add` | Add files to staging |
| `git commit` | Record changes |
| `git push` | Upload to remote |
Horizontal Rules
Create dividers with three or more hyphens, asterisks, or underscores:
---
***
___
All produce a horizontal line.
Escaping Characters
Use backslash to show literal characters:
\*Not italic\*
\# Not a heading
\[Not a link\]
Result: *Not italic*
Characters that can be escaped: \, `, *, _, {}, [], (), #, +, -, ., !, |
GitHub-Specific Features
Mentioning Users
@username will be notified about this comment.
Referencing Issues and PRs
This fixes #123
Related to #456
See PR #789
GitHub auto-links these to the corresponding issues/PRs.
Cross-Repository References
owner/repo#123
Commit References
Full SHA: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0
Short SHA: a1b2c3d
Emoji
:smile: :rocket: :tada: :bug: :fire:
Result: :smile: :rocket: :tada: :bug: :fire:
Find Emoji Codes: Visit emoji-cheat-sheet.com for a complete list.
Alerts (GitHub Specific)
> [!NOTE]
> Useful information that users should know.
> [!TIP]
> Helpful advice for doing things better.
> [!IMPORTANT]
> Key information users need to know.
> [!WARNING]
> Urgent info that needs immediate attention.
> [!CAUTION]
> Advises about risks or negative outcomes.
README.md Best Practices
A good README should include:
# Project Name
Brief description of what the project does.
## Features
- Feature 1
- Feature 2
- Feature 3
## Installation
\`\`\`bash
git clone https://github.com/user/project.git
cd project
npm install
\`\`\`
## Usage
\`\`\`javascript
const project = require('project');
project.doSomething();
\`\`\`
## Contributing
1. Fork the repository
2. Create your feature branch
3. Commit your changes
4. Push to the branch
5. Open a Pull Request
## License
MIT License - see LICENSE file for details.
README Badges
Add status badges:
Quick Reference
| Element | Syntax |
|---|---|
| Heading | # H1 ## H2 ### H3 |
| Bold | text |
| Italic | text |
| Strikethrough | ~~text~~ |
| Link | text |
| Image | |
| Inline code | |
| Code block | |
| Quote | > quote |
| Unordered list | - item |
| Ordered list | 1. item |
| Task list | - [x] done - [ ] todo |
| Horizontal rule | --- |
Learn More
For complete documentation, visit the official GitHub Markdown guide:
Summary
GitHub Flavored Markdown is your tool for clear communication on GitHub:
- Text styling: Bold, italic, strikethrough for emphasis
- Structure: Headings, lists, and tables for organization
- Code: Inline and blocks with syntax highlighting
- Links/Images: Connect to resources and show visuals
- Task lists: Track progress in issues and PRs
- GitHub features: Mentions, references, and emoji
Master these basics and your README files, issues, and documentation will be professional and easy to read!
