GitHub Markdown Guide & Syntax Reference

GitHub uses "GitHub Flavored Markdown" (GFM) — a superset of standard Markdown with a few extra features, and a few standard Markdown features that behave differently once rendered inside a README on github.com.

Core syntax that works reliably

**bold** and *italic* for emphasis
`inline code` and triple-backtick fenced code blocks with language hints
- item or 1. item for lists
[text](url) for links, ![alt](url) for images
Tables using pipe syntax

GFM extensions specific to GitHub

Task lists — - [x] Done renders as a checked checkbox
Emoji shortcodes — :rocket: renders as 🚀
Automatic linking of issue and PR numbers like #42 within a repository
Mentions — @username auto-links to a GitHub profile

What doesn't work in a README

Custom CSS or <style> blocks — GitHub strips these
JavaScript — completely stripped for security reasons
Most HTML attributes beyond a small allow-list (align, width, height on img tags are fine; most others are stripped)

Centering content — the one workaround worth knowing

<p align="center">
  <img src="banner.png" width="600" />
</p>

Because flexbox and CSS aren't available, the align HTML attribute is the standard way to center content in a README — it's one of the few HTML attributes GitHub doesn't strip.

Frequently Asked Questions

Does GitHub support standard CSS in Markdown files?

No, style blocks and external stylesheets are stripped when a README is rendered on github.com.

What's the difference between GFM and standard Markdown?

GFM adds features like task lists, automatic issue linking, and emoji shortcodes on top of the CommonMark standard Markdown spec.

Can I use raw HTML in a README?

A limited, sanitized subset — common tags like img, p, div, table, and a handful of safe attributes work; script tags and most CSS-related attributes are stripped.

GitHub Markdown Guide