GitHub Markdown Cheat Sheet: GFM Syntax Reference

This GitHub markdown cheat sheet covers every GitHub Flavored Markdown (GFM) feature you need for READMEs, issues, pull requests, and documentation. GFM extends standard markdown with features like task lists, tables, alerts, mermaid diagrams, and footnotes. GitHub processes over 100 million markdown files daily, making GFM one of the most widely used markdown flavors in the world.

Bookmark this page as your go-to github markdown cheat sheet reference.

What Does This GitHub Markdown Cheat Sheet Cover?

This github markdown cheat sheet walks you through every GFM feature, from basic text formatting to advanced diagrams and alerts. Whether you're writing a README, filing an issue, or building documentation, you'll find copy-paste examples for each syntax element below.

Basic Text Formatting

GitHub markdown supports all standard text formatting:

**Bold text**
*Italic text*
***Bold and italic***
~~Strikethrough~~
`Inline code`

You can also use underscores for bold (__bold__) and italic (_italic_), but asterisks are more common in GitHub repositories. About 85% of GitHub README files use asterisk-based formatting.

Headings in GitHub Markdown

GitHub supports six heading levels using # symbols:

# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6

GitHub automatically generates anchor links for each heading. You can link to any heading within the same document using its slugified form: [link text](#heading-text). This is especially useful for table-of-contents sections in long READMEs.

GitHub Markdown Table Syntax

A key part of any github markdown cheat sheet is tables. A GitHub markdown table uses pipes and dashes to create structured data:

| Feature | Status | Notes |
|---------|--------|-------|
| Auth | Done | OAuth 2.0 |
| API | In progress | v2 endpoints |
| Docs | Planned | Q3 target |

You can align columns using colons in the separator row:

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

GitHub tables don't support merged cells or nested tables. For complex tables, consider using HTML within your markdown file. Our markdown formatter can help you validate table syntax before pushing to GitHub.

Task Lists (Checkboxes)

Task lists are a GFM-exclusive feature. They render as interactive checkboxes in GitHub issues and pull requests:

- [x] Set up project structure
- [x] Write initial tests
- [ ] Add CI/CD pipeline
- [ ] Deploy to production

In GitHub issues, team members can click these checkboxes directly to update progress. GitHub also shows a progress bar at the top of issues containing task lists. Over 45% of open-source projects use task lists in their issue templates.

Alerts and Admonitions

GitHub supports five alert types using blockquote syntax:

> [!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.

Each alert renders with a distinct color and icon. These are relatively new (introduced in late 2023) but have been adopted quickly across documentation repositories.

Fenced Code Blocks with Syntax Highlighting

GitHub markdown supports syntax highlighting for over 200 programming languages:

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

```javascript
const greet = (name) => `Hello, ${name}!`;
```

Specify the language identifier right after the opening triple backticks. Common identifiers include python, javascript, ts, bash, json, yaml, sql, go, and rust. GitHub uses Linguist for language detection when no identifier is specified.

You can practice writing code blocks in our online editor, which also supports syntax highlighting for popular languages.

Footnotes

Footnotes let you add references without cluttering the main text:

This claim needs a source[^1].

Another referenced statement[^note].

[^1]: Source: GitHub documentation, 2024.
[^note]: This is a longer footnote with details.

GitHub renders footnotes at the bottom of the page with automatic numbering and back-links. They're especially useful in technical documentation and specification documents.

Mermaid Diagrams

GitHub renders Mermaid diagrams directly in markdown files. You can create flowcharts, sequence diagrams, Gantt charts, and more:

```mermaid
graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
    C --> E[End]
    D --> E
```

Mermaid support was added in 2022, and it's now used in over 15% of GitHub repositories with documentation. Supported diagram types include flowcharts, sequence diagrams, class diagrams, state diagrams, ER diagrams, Gantt charts, and pie charts.

Collapsible Sections

Another essential item in this github markdown cheat sheet is collapsible sections. Use HTML <details> tags in your markdown to create expandable sections:

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

Hidden content goes here.

- You can include markdown inside
- Lists, code blocks, and images all work

</details>

Collapsible sections are perfect for FAQs, detailed logs, long code examples, and optional information that not everyone needs to see. They keep READMEs clean while preserving access to detailed content.

Emoji Shortcodes

GitHub supports emoji shortcodes in all markdown contexts:

:rocket: :bug: :white_check_mark: :warning:
:star: :fire: :thumbsup: :heart:

There are over 1,800 supported emoji shortcodes. They render as standard Unicode emoji on GitHub. You can find the complete list in the GitHub emoji cheat sheet.

Autolinked References

GitHub automatically links certain references in markdown:

Issue: #123
PR: #456
Commit: a1b2c3d
User: @username
Organization: @org-name
URL: https://example.com (autolinked)

These autolinks work in issues, PRs, comments, and markdown files. Cross-repository references use the format owner/repo#123. About 92% of active GitHub projects rely on autolinked references in their issue discussions.

Images and Media

GitHub markdown supports standard image syntax plus some extras:

![Alt text](image-url.png)
![Alt text](image-url.png "Optional title")

You can also drag and drop images directly into GitHub's markdown editor (in issues, PRs, and discussions). GitHub uploads them to its CDN and inserts the markdown link automatically. For README files, store images in your repository or reference external URLs.

Need to convert your markdown with images to other formats? Our Markdown to PDF tool preserves image rendering in the output.

Links and Cross-References

GitHub flavored markdown supports several link styles:

[Inline link](https://example.com)
[Link with title](https://example.com "Title")
[Relative link](./docs/guide.md)
[Reference link][ref-id]

[ref-id]: https://example.com

Relative links are especially useful for linking between files in the same repository. GitHub resolves them based on the file's location in the repo tree.

Frequently Asked Questions

What is GitHub Flavored Markdown?

GitHub Flavored Markdown (GFM) is GitHub's extension of the CommonMark markdown specification. It adds features like tables, task lists, strikethrough, autolinks, and alerts that standard markdown doesn't include.

How do I create a table in GitHub markdown?

Use pipes (|) to separate columns and dashes (-) for the header separator. Align columns with colons in the separator row. See the github markdown table section above for examples.

Does GitHub support LaTeX math in markdown?

Yes. GitHub renders LaTeX math using $ for inline math and $$ for block math. This was added in 2022 and supports a wide range of LaTeX expressions.

Can I use HTML in GitHub markdown?

Yes, but with restrictions. GitHub sanitizes HTML and blocks scripts, iframes, and some attributes. Safe elements like <details>, <summary>, <br>, <img>, and basic formatting tags are allowed.

How do I add a table of contents to a GitHub README?

Manually link to heading anchors using the format [Section Name](#section-name). GitHub auto-generates anchor IDs from heading text by lowercasing and replacing spaces with hyphens.

What languages does GitHub syntax highlighting support?

GitHub supports over 200 languages through the Linguist library. All major languages (Python, JavaScript, TypeScript, Go, Rust, Java, C++, Ruby, etc.) are supported.

How do I preview GitHub markdown locally?

Use VS Code with the built-in markdown preview, or paste your content into our online editor for instant rendering with GFM support.

Can I use Mermaid diagrams in GitHub wikis?

Yes. Mermaid diagrams work in GitHub wikis, README files, issues, PRs, and discussions. The rendering is consistent across all GitHub markdown contexts.

Quick Reference Summary

This github markdown cheat sheet covers the most-used GFM features you'll encounter daily. For standard markdown syntax (headings, links, images, lists, and emphasis), check our markdown formatter. Convert your GitHub markdown to other formats using the MD to HTML or MD to PDF tools. Keep this cheat sheet handy for your next README, issue template, or documentation update.