GitHub Markdown (GFM)
A comprehensive guide to GitHub-Flavored Markdown. Master tables, task checklists, mathematical LaTeX blocks, anchor links, image adjustments, and GitHub-exclusive features.
GitHub builds upon standard CommonMark. GFM features are universally supported in README.md files, issues, pull requests, wikis, and discussion forums on GitHub.
GitHub Alert Callouts
GitHub features five distinct styled alert blockquotes to convey emphasis, tips, or hazards in your document. Syntax starts with a blockquote sign > [!TYPE] on the first line.
> [!NOTE]
> Useful information that users should know, even when skimming content.Useful information that users should know, even when skimming content.
> [!TIP]
> Helpful advice for doing things better or more easily.Helpful advice for doing things better or more easily.
> [!IMPORTANT]
> Key information users need to know to achieve their goal.Key information users need to know to achieve their goal.
> [!WARNING]
> Urgent info that needs immediate user attention to avoid problems.Urgent info that needs immediate user attention to avoid problems.
> [!CAUTION]
> Advises about risks or negative outcomes of certain actions.Advises about risks or negative outcomes of certain actions.
Tables
Create tabular data by using pipes (|) for boundaries and hyphens (-) to construct headers. Align columns by positioning colons on your dividing row.
| Left-Aligned | Centered | Right-Aligned |
|:---|:---:|---:|
| Cell 1 | Cell 2 | Cell 3 |
| Value | Value | Value || Left-Aligned | Centered | Right-Aligned |
|---|---|---|
| Cell 1 | Cell 2 | Cell 3 |
| Value | Value | Value |
Task Checklists
Construct list items with interactive checkboxes on GitHub using brackets containing an empty space [ ] (unchecked) or an x [x] (checked).
- [x] Integrate live code parsing
- [x] Standardize styling guidelines
- [ ] Deploy new platform guides
- [ ] Optimize database structuresLaTeX Math & Text Color Hacks
GitHub supports rendering LaTeX math using single dollar signs $...$ for inline equations or double $$...$$ for centered blocks.
Additionally, because GitHub strips inline CSS properties for security, developers use math color commands as a **text color hack** in markdown.
$\color{orange}{\text{This is orange text in GFM}}$$$a^2 + b^2 = c^2$$Autolink references & Mentions
GitHub automatically parses certain syntax patterns into rich hyperlinks when working within repositories, discussions, and commit notes.
| Reference Type | Syntax Example | How GitHub renders it |
|---|---|---|
| Mentions | @someguy | Links directly to user profile page |
| Issue or Pull Request | #101 | Auto-links to issue #101 in current repo |
| Cross-Repo Issue | user/repo#101 | Links to issue #101 inside user's specified repo |
| Commit Reference | a8c9b2f | Links to specific git commit hash reference |
| Universal URL Link | https://github.com | Converts raw links to clickable buttons |
HTML Image Tweaks (Resize & Align)
Standard Markdown does not have native parameters to change an image's height, width, or positioning. Because GitHub permits standard HTML components, you can resize and float your images using absolute dimensions:
<img src="https://images.unsplash.com/photo-1542831371-29b0f74f9713" width="200" alt="Code mockup" /><div align="center">
<img src="logo.png" width="150" alt="App Logo" />
<h3>Centred Text Title</h3>
</div>Interactive Dropdown Toggles
You can compress logs, configurations, and edge cases inside standard collapsible toggle widgets on GitHub utilizing HTML <details> and <summary> blocks.
<details>
<summary>Click to view system details</summary>
### System Configuration
- macOS Catalina
- Node 20.10.0
</details>Click to view system details
System Configuration
• macOS Catalina
• Node 20.10.0
Frequently Asked Questions
What is GitHub-Flavored Markdown (GFM)?
GitHub-Flavored Markdown (GFM) is GitHub's custom extension of the CommonMark spec. GFM adds native support for popular additions such as tables, task lists, autolink references (issues, PRs, users, commits), strikethroughs, and alert callouts.
How do I color text in GitHub Markdown?
GitHub strips standard HTML style attributes for security, meaning <span style="color:red"> will not render. However, you can color text on GitHub using LaTeX math equations wrapped in $...$. The syntax is: $\color{red}{\text{your text}}$. Keep in mind this renders in a math-style serif font. Alternatively, you can use semantic alert boxes (> [!NOTE] etc.) for color callouts.
Does GitHub support Markdown tables?
Yes, GFM has robust native support for tables. You can construct a table using pipes (|) for columns and hyphens (-) for header separation. You can control text alignment using colons: :--- for left alignment, ---: for right alignment, and :---: for centered text.
How do I resize an image in GitHub Markdown?
Standard Markdown syntax () doesn't support width and height attributes. To resize or align an image on GitHub, use standard HTML: <img src="your-image.png" width="300" alt="alt text" />. You can also center an image by wrapping it in <div align="center">...</div>.
How do I create a details toggle dropdown on GitHub?
You can create an interactive collapsible details box on GitHub using the standard HTML <details> and <summary> tags. Write them as follows: <details> <summary>Click to expand</summary> Your markdown content here (add a blank line before this text). </details>
Why isn't my checklist rendering correctly on GitHub?
GitHub task lists require specific formatting to render as checkboxes. Ensure that: (1) The list item starts with a dash or asterisk followed by a space, (2) The brackets are followed by a space: - [ ] for unchecked, or - [x] for checked, (3) There is a space between the bracket and the text.
Explore Other Guides
Learn how standard Markdown scales across other specialized consumer and enterprise platforms: