Markdown Cheat Sheet: Every Syntax Rule With Examples

Markdown is a lightweight markup language that converts plain text into formatted HTML using simple punctuation symbols. You write **bold** and it renders as bold. You write # Heading and it renders as an H1. Created by John Gruber in 2004, Markdown is now the standard writing format for GitHub READMEs, documentation sites, blog platforms, note-taking apps, and AI chatbots. This cheat sheet covers every syntax rule with examples you can copy immediately.

Markdown cheat sheet: complete reference

Headings

Headings are created with one to six hash symbols (#). The number of hashes determines the heading level — one hash for H1, two for H2, up to six for H6. Always leave a space between the hash and the heading text.

Best practice: use only one H1 per document (the document title). Use H2 for main sections and H3 for subsections. Skipping levels (H1 to H3 with no H2) breaks accessibility and hurts SEO on web pages.

Emphasis: bold and italic

Bold uses double asterisks or double underscores: **bold** or __bold__. Italic uses single asterisks or single underscores: *italic* or _italic_. Combine them with triple asterisks: ***bold and italic***.

The asterisk syntax is more universally supported across Markdown flavours. Stick to asterisks if your content may be rendered across multiple platforms.

Links and images

Links follow the pattern: [display text](URL). To open in a new tab, most Markdown renderers require HTML: <a href="URL" target="_blank">text</a> — standard Markdown has no new-tab syntax.

Images use the same syntax as links with an exclamation mark prefix: ![alt text](image-url.png). The alt text is important for accessibility and SEO — describe what the image shows, not just "image."

Reference-style links keep your prose readable when URLs are long: [display text][ref-label], then elsewhere in the document: [ref-label]: https://example.com.

Lists

Unordered lists use -, *, or + followed by a space. Ordered lists use numbers followed by a period. Nested lists are created by indenting with two or four spaces:

• Always leave a blank line before the first list item if it follows a paragraph
• Nested items require consistent indentation (2 or 4 spaces)
• Ordered lists do not need consecutive numbers — 1. 1. 1. renders as 1, 2, 3 — but consistent numbering is clearer for readers editing the raw text

Code: inline and block

Inline code wraps in single backticks: `console.log()`. Use inline code for function names, variable names, file paths, and short commands within a sentence.

Code blocks use three backticks on a line above and below the code. Specify the language immediately after the opening backticks for syntax highlighting:

```javascript on the first line, then the code, then ```on the last line. Supported language identifiers include: javascript, typescript, python, bash, json, sql, html, css, yaml, markdown.

An alternative for code blocks is four-space indentation, but fenced code blocks (backtick style) are more widely supported and allow language specification.

Tables

Tables use pipe characters (|) to separate columns and hyphens to create the header separator row:

The column alignment is set in the separator row: :--- for left-aligned, :---: for centred, ---: for right-aligned. Pipes at the start and end of each row are optional in most flavours but improve readability.

Blockquotes

Blockquotes prefix each line with a greater-than symbol and a space: > quoted text. Nested blockquotes use multiple > symbols: >> nested quote. Blockquotes can contain other Markdown elements including bold text, lists, and code.

Task lists (GitHub Flavoured Markdown)

Task lists are supported in GitHub, GitLab, Notion, Obsidian, and most modern Markdown editors. Use - [ ] for an unchecked item and - [x] for a checked item. In GitHub Issues and Pull Requests, checking a task list item updates the checkbox interactively.

Markdown in different tools: what works where

Common Markdown mistakes and how to fix them

• Missing blank lines before lists and headings. In many flavours, a list or heading immediately following a paragraph (no blank line) is not rendered correctly. Always add a blank line before and after lists, headings, code blocks, and tables.
• Spaces in links breaking rendering. [text](url with spaces) breaks in most renderers. Encode spaces as %20 or wrap the URL in angle brackets: [text](<url with spaces>).
• Incorrect code fence language identifiers. Using ```JS``` instead of ```javascript``` may not trigger syntax highlighting. Check the renderer's supported language list.
• Mixing tabs and spaces in indentation. Use spaces consistently for nested lists and code indentation — some renderers treat tabs differently.
• Escaping characters unintentionally. Characters like *, _, #, and ` have special meaning in Markdown. If you want them to appear literally, prefix with a backslash: \*, \_, \#.

Official references and further reading

These three sources are the canonical specifications for Markdown syntax, the CommonMark standard, and GitHub Flavoured Markdown.

• CommonMark — Official Markdown Specification and Quick Reference — The CommonMark specification resolves the ambiguities in the original John Gruber Markdown. The quick reference is the most concise single-page syntax guide for the standard that most modern Markdown tools target.
• GitHub — GitHub Flavoured Markdown Specification — The full GFM specification, which extends CommonMark with tables, task lists, autolinks, strikethrough, and fenced code blocks. GFM is the most widely used Markdown flavour as of 2026.
• Daring Fireball — Original Markdown Syntax by John Gruber — The original 2004 Markdown syntax documentation by John Gruber, who created the language. Still the primary reference for the design philosophy behind Markdown's syntax choices.

Key takeaways

• Markdown converts plain text to formatted HTML using punctuation: # for headings, ** for bold, * for italic, backticks for code.
• GitHub Flavoured Markdown (GFM) adds tables, task lists, and autolinks on top of standard CommonMark — it is the most widely used flavour.
• Always add blank lines before lists, headings, and code blocks to ensure consistent rendering across Markdown flavours.
• Specify the language after the opening backticks of code blocks for syntax highlighting: ```python, ```javascript, ```sql.
• Escape special characters with a backslash when you want them to appear literally.

Frequently asked questions

What is the difference between Markdown and HTML?

HTML (HyperText Markup Language) is a full markup language with explicit opening and closing tags. Markdown is a simplified shorthand that compiles to HTML. **bold** in Markdown produces <strong>bold</strong> in HTML. Markdown is faster to write and easier to read as plain text; HTML offers more precise control over presentation. Most Markdown renderers also accept raw HTML inline, giving you access to HTML features (new-tab links, custom attributes) when Markdown syntax is insufficient.

Does Markdown support comments?

Standard Markdown has no comment syntax. The common workaround is to use an HTML comment, which most Markdown renderers suppress from the output: <!-- This is a comment -->. In most renderers, this text will be present in the HTML source but not visible to the reader.

What is CommonMark and why does it matter?

CommonMark is a standardised specification of Markdown syntax maintained at commonmark.org. The original Markdown had no formal specification, leading to inconsistencies between implementations. CommonMark resolves most ambiguities. GitHub Flavoured Markdown (GFM) is a superset of CommonMark that adds tables, task lists, and autolinks. Most modern Markdown tools now target CommonMark or GFM compliance.

Can I use Markdown in a Google Doc?

Since 2022, Google Docs has supported Markdown auto-formatting — typing **bold** automatically converts to bold formatting. Go to Tools → Preferences → check "Automatically detect Markdown." You can also paste Markdown content and Google Docs will apply basic formatting. Full table and code block support remains limited compared to native Markdown editors.

What is the best Markdown editor?

For developers: VS Code with the built-in Markdown preview (Ctrl+Shift+V) and the Markdown All in One extension covers almost all use cases. For writers and note-takers: Obsidian (free, local-first, powerful plugin ecosystem) and Typora (paid, $15 one-time, best WYSIWYG Markdown experience) are the most popular dedicated Markdown editors. For web publishing: Ghost natively supports Markdown; WordPress supports it via the Gutenberg Markdown block.