Markdown Cheat Sheet: Everything You Need to Write Better Docs

Markdown is the closest thing the web has to a universal writing format. It powers READMEs, pull request descriptions, forum posts, documentation sites, and most static site generators. Yet many developers know just enough to get by. This reference covers the essentials plus the syntax people routinely get wrong.

The essentials in one glance

• # H1 through ###### H6 for headings
• **bold** and *italic*
• [text](url) for links and ![alt](image.png) for images
• --- for a horizontal rule

Lists that nest cleanly

Unordered lists use -, ordered lists use numbers. Nest by indenting four spaces (or two in most renderers). The number you type for the first item matters; everything after is auto-sequenced by most engines, which makes reordering less painful.

Code blocks done right

Inline code ticks `code` are for short fragments. Fenced code blocks with three backticks allow language highlighting and prevent the renderer from eating your formatting. Always add the language tag — ```js, ```python, ```sql — so the syntax lights up correctly.

Tables that actually render

Tables need a header row, a separator row, and pipe-delimited content:

| Feature | Status |
| ------- | ------ |
| Export | Done |

Alignment is optional (:--- left, ---: right, :---: center) but produces professional output for status reports.

Pitfalls that break renders

• Mixing tabs and spaces in lists and code blocks
• Forgetting a blank line before a table or list
• Using HTML-style line breaks where Markdown wants two spaces or a blank line
• Nesting code fences inside list items without extra indentation

Paste a draft into a live Markdown preview before committing, so rendering issues never make it into a public README or documentation page.