Skip to content
d.devtul.fun
中文
Markdown · 2026-09-26

Markdown Syntax Cheat Sheet for Developers

2026-09-26~853 words

If you write code, you write Markdown — READMEs, pull-request descriptions, issue templates, docs. Most of it is GitHub Flavored Markdown (GFM), a superset of CommonMark with a handful of extras. This cheat sheet pairs the source with what it renders to, so you can confirm the syntax at a glance.

Headings

Use one to six # characters. A blank line before a heading keeps parsers happy.

# H1
## H2
### H3

On this site the page title supplies the H1, so body content starts at H2.

Emphasis: * vs _

Both produce bold and italic, but the underscore forms are sensitive to word boundaries, so they only trigger when they sit at a word edge.

*italic*     _italic_
**bold**     __bold__
***both***

Source above renders as: italic, bold, both. Asterisks work mid-word (un*real*istic → unrealistic); underscores do not (un_real_istic stays literal). You can nest them, but keep the inner and outer markers different or the parser gets confused.

Lists

Unordered lists take -, * or +; ordered lists take a number and a dot. Nesting is purely about indentation — and that is where people get burned.

1. first
2. second
   - nested a
   - nested b
3. third

- item
- item
  - deeper

Wrong indentation is the classic trap: a child line must be indented further than its parent, and mixing tabs with spaces shifts everything. If a nested item renders as a code block instead of a sublist, your indentation is off by one level.

Task lists

- [ ] todo
- [x] done

Renders as checkboxes: - [x] is checked, - [ ] is not. GitHub makes them interactive in issues.

Links

[inline](https://example.com)
<https://example.com>
[ref][1]

[1]: https://example.com "title"

Inline links wrap text in brackets and the URL in parentheses; bare URLs become autolinks when wrapped in < >. Reference-style links define the URL once at the bottom and keep the prose clean. Note the autolink angle brackets are escaped above so they show as text rather than being parsed away.

Images

![alt text](image.png "tooltip")

The syntax is identical to a link with a leading exclamation mark. The first string is alt text, the quoted part is an optional title.

Code

Inline code uses single backticks; a fenced block uses triple backticks with an optional language tag for highlighting.

`inline code`

```python
def f(x):
    return x * 2
```

Never put unescaped HTML inside prose where you mean literal text — inside a code fence it is shown verbatim, which is exactly why this cheat sheet escapes its angle brackets.

Tables

The header row is followed by a separator row whose colons set alignment.

| Left | Right | Center |
|:-----|------:|:------:|
| a    | b     | c      |

A colon on the left aligns left, on the right aligns right, on both centers. Tables cannot contain block elements like code fences or nested tables — a fenced block inside a cell breaks the table.

Blockquotes and rules

> a quoted line
> spanning two lines

---

A > prefix makes a blockquote; three or more dashes, asterisks or underscores on their own line make a horizontal rule. The > here is escaped so the example shows the source rather than becoming a quote.

Escaping

To show a literal character that Markdown would otherwise interpret, backslash-escape it: \*not italic\* renders as \*not italic\*. This is how you write "C++" without fear, or show a literal hash at the start of a line.

Footnotes

GFM and CommonMark differ here. On GitHub you write:

Text with a footnote.[^1]

[^1]: The footnote content.

Strict CommonMark has no footnote syntax at all, so the same text simply shows the brackets literally on renderers that follow the spec exactly. If portability matters, spell the note out inline.

Mixing in raw HTML

Because Markdown is a superset of HTML, you can drop raw HTML blocks straight in. This is useful for things Markdown lacks, like a line break or a definition list. Remember the page may sanitise tags, so do not assume every element survives.

GitHub-specific extras

  • @mentions like @octocat notify a user or team.
  • Issue references like #123 link to an issue or PR in the same repo.
  • Task lists - [x] render as checkboxes in issues and PRs.
  • Strikethrough ~~done~~ renders as done.
  • Autolinked references like SHA, username/repo#1 and #123 are linked automatically.

Things that look like they work but don't

  • A code fence inside a table cell. Tables only hold inline content; a fence breaks the row into garbage.
  • Indentation that looks aligned but is not. Four spaces at the start of a line is a code block, not a sublist — if your nested list turned into monospace text, that is why.
  • Underscores inside words. file_name stays literal, but file-name is fine; only asterisks give you mid-word emphasis.
  • Multiple paragraphs in one table cell. Not supported by GFM; the newline ends the cell.

Keep this sheet handy the next time a README renders wrong: nine times out of ten it is an indentation or escaping slip, not a Markdown bug.

Keep reading