Quick Guide – GitHub‑Flavored Markdown (GFM)

TL;DR: If you write READMEs, issues, or PRs, this cheat‑sheet‑turned‑guide shows exactly how to format things in GitHub. Copy/paste the snippets. Ship better docs.

Why GFM?

GitHub Flavored Markdown (GFM) is the dialect GitHub renders across READMEs, issues, PR descriptions, comments, and wikis. It’s a superset of CommonMark with pragmatic extras—tables, task lists, autolinks, alerts, and math—so you can write clean docs without leaving your keyboard.

Headings & Text

Use # for headings (H1–H6). Underscores or asterisks for emphasis; tildes for strikethrough.

Pro tip: Keep one # H1 per document (the page title), then start at ##.

Lists (including checklists)

Unordered, ordered, nested, and task lists are all supported. Task lists render clickable checkboxes in issues/PRs.

Workflow tip: In PR descriptions, checking off tasks communicates progress without extra comments.

Links, Images, Mentions, and References

Relative links keep READMEs portable across branches. Mentions and shorthand references auto‑link.

• #123 → current repo issue/PR.
• user/repo#123 → other repo issue/PR.
• user/repo@deadbeef → commit permalink.

Code & Syntax Highlighting

Use backticks for inline code; triple backticks for blocks. Add a language for highlighting.

Tip: For shell snippets, prefer copy-friendly commands and show the expected output separately.

Tables (lightweight layout)

Alignment uses colons on the separator row.

Note: Keep tables small; large ones are hard to maintain in diffs.

Blockquotes

Use blockquotes for callouts, not multi‑paragraph layout.

Alerts (a.k.a. callouts)

These render with icons and color in GitHub UI.

House style: Use alerts sparingly—one or two per doc to highlight the highest‑value info.

Footnotes

Great for definitions and citations without cluttering your main flow.

Math (LaTeX)

Inline $...$ or block $$...$$. You can also use a math code fence.

Tip: If your example needs backslashes (e.g., \int, \frac), some blog engines require escaping inside examples.

Emojis & Shortcodes

Use for tone; avoid replacing important words with emoji.

HTML (when you really need it)

You can mix in safe HTML like <details> and <summary> for collapsible sections. Avoid heavy HTML; GitHub sanitizes unsupported tags.

Patterns We Recommend

1) README skeleton

Start every repo with a minimal but complete README.

2) Issue template snippet

3) PR description checklist

Accessibility & Style Notes

• Use real headings (not bold lines) for structure and screen reader navigation.
• Don’t rely on color alone; use text labels and icons.
• Keep line length readable (~80–100 chars) for nicer diffs.
• Prefer relative links for intra‑repo docs; use absolute links only when necessary.

Common Pitfalls

• Multiple H1s: pick one title.
• Over‑formatted tables: hard to diff—favor lists or code blocks.
• Screenshots without alt text: always add descriptive alt text.
• Raw HTML everywhere: causes portability issues; stick to Markdown features first.

Copy‑Paste Appendix

A compact snippet set you can drop into any doc.

Wrap‑up

GFM hits a sweet spot: expressive enough for real docs, simple enough to type quickly. With a few conventions and snippets, your READMEs, issues, and PRs will be easier to read, search, and maintain.