TopolearnThese features turn Markdown into a collaboration tool in issues, pull requests and READMEs.
GitHub Flavored Markdown (GFM) adds features beyond CommonMark, and GitHub adds a few more on top:
- Task lists:
- [ ] todoand- [x] donerender checkboxes; in issues and PRs they're clickable and show progress. - Strikethrough:
~~removed~~. - Extended autolinks: bare
https://...andwww.URLs become links without angle brackets. - Footnotes:
Text[^1]with[^1]: The note.anywhere in the document; rendered at the bottom with back-links. - Alerts: a blockquote starting with
[!NOTE],[!TIP],[!IMPORTANT],[!WARNING]or[!CAUTION]renders as a coloured callout. - References in issues, PRs and comments:
@usermentions,#123issue links, commit SHAs andowner/repo#123become links. - Emoji shortcodes like
:rocket:.
GFM also disallows some raw HTML tags (such as <script> and <iframe>) via its tagfilter extension.
Portability varies. Task lists, tables and strikethrough are widely supported; footnotes and alerts less so; mentions and issue references only mean something on GitHub (GitLab has similar but not identical syntax). If a document is rendered in several places, such as GitHub and a docs site, check the features against both.
Example
## Release checklist
- [x] Update the changelog
- [ ] Tag the release
- [ ] ~~Announce on the mailing list~~ (moved to the blog)
> [!WARNING]
> Version 3 removes the legacy API.
Fixes #142, thanks @ana-dev. See https://example.com/notes for details.
The parser is linear-time[^re2].
[^re2]: It uses an automaton-based engine, so no input can cause backtracking.Remember
- - [ ] and - [x] make task lists; ~~text~~ strikes through
- > [!NOTE] style blockquotes render as alerts on GitHub
- Footnotes, mentions and #refs aren't supported by every renderer
Watch out for
- Using GitHub-only features like alerts or #123 references in docs that are also rendered elsewhere.