Your table renders as a wall of pipes. Your callout box shows the word NOTE as literal text. Nothing is wrong with your markdown — you are using a guide written for a different flavour of it.
The GitHub Flavored Markdown Cheat Sheet You Actually Need
GitHub adds features on top of standard markdown, and those extras are where things break.
Basic syntax — headings, bold, links, code fences — works everywhere and needs no cheat sheet. This covers what GitHub adds.
| Feature | GitHub-only? |
|---|---|
| Tables | Yes, an extension |
| Task lists | Yes |
| Alert callouts | Yes |
| Mermaid diagrams | Yes |
| Footnotes | Yes |
| Emoji shortcodes | Yes |
| Autolinked URLs | Yes |
| Strikethrough | Yes |
Every row in that table renders as plain text on npm, PyPI, or anywhere else your README is mirrored. Worth knowing before you build a page around one.
To draft and preview markdown freely, our online markdown editor gives you a live pane.
GitHub Alerts and Callouts
Five coloured boxes, built from blockquote syntax.
> [!NOTE]
> Useful information a reader should know.
> [!WARNING]
> Something that could cause a problem.The five types are NOTE, TIP, IMPORTANT, WARNING and CAUTION. Each gets its own colour and icon.
Two rules trip people up. The marker must be on its own first line, and the whole block must be one blockquote — a blank line between the marker and the text breaks it into a plain quote.
Use one or two per document. A README where every paragraph is a warning box reads like an error log.
Markdown Table Syntax on GitHub
Pipes and a separator row. Alignment goes in the separator.
| Option | Type | Default |
| :--- | :---: | ---: |
| verbose | boolean | false |
| retries | number | 3 |Left, centre and right come from where the colons sit in the second row. That row is not optional — without it you get literal pipes.
Column widths do not need to line up in the source. Aligning them makes the raw file readable, and GitHub ignores the whitespace entirely.
The real limitation: no multi-line cells. A paragraph inside a table cell needs an HTML break tag, and anything longer than a sentence usually wants to be a list instead.
Collapsible Sections and Footnotes
The details element is the most underused thing in GitHub markdown.
<details>
<summary>Full configuration options</summary>
Markdown inside still works, as long as you leave a blank line
after the summary tag.
</details>That blank line is mandatory. Without it GitHub treats the contents as raw HTML and your markdown renders as literal text.
Collapsible blocks solve the length problem directly — troubleshooting sections and long option tables can stay in the README without dominating it.
Footnotes work too, using a bracket-caret reference and a matching definition anywhere in the file. Good for citations that would otherwise interrupt a sentence.
Mermaid Diagrams in a GitHub README
A code fence labelled mermaid renders as a diagram.
```mermaid
flowchart LR
A[Request] --> B{Cached?}
B -->|yes| C[Return cache]
B -->|no| D[Fetch and store]
```No image files, no build step, and the diagram lives in version control as text you can diff. It works in READMEs, issues, pull requests and discussions.
The caveat is portability. Mermaid does not render on npm, PyPI or most mirrors, so a diagram carrying essential information should also exist as an image.
Rendering an SVG version for those cases? Our SVG to PNG converter handles the export.
The Two Rules That Break Silently
Heading anchors and dark mode. Neither gives you an error.
GitHub builds an anchor from each heading by lowercasing it, turning spaces into hyphens and dropping punctuation. Add an emoji to a heading and every link pointing at it stops working, with no warning.
Dark mode is the other one. A logo with dark strokes and a transparent background disappears entirely for roughly half of GitHub users.
<picture>
<source media="(prefers-color-scheme: dark)" srcset="logo-dark.png">
<img alt="Project logo" src="logo-light.png">
</picture>Fully supported, almost never used. We check this on every README we review and it is wrong more often than not.
Badges follow the same portability rules as images — see our markdown badge maker for the syntax.
Wrapping Up
A GitHub flavored markdown cheat sheet is really a list of extensions. Tables, task lists, alerts, mermaid and footnotes are all GitHub additions, and none of them travel.
Remember the two silent failures: emoji in headings breaks anchor links, and transparent logos vanish in dark mode.
Putting a README together? Start with README best practices, or let the readme.md generator assemble the structure.