Markdown Cheat Sheet: Syntax, Tables, and Extended Features

Quick reference tables

Headings

Always put a space after #. Most parsers require it; some are forgiving, but all accept it.

Text emphasis

Lists

Always put a blank line before the first list item if it follows a paragraph.

Links and images

Blockquotes

Code

Tables (GFM)

Horizontal rules

Any of these on their own line produces <hr>:

Put blank lines before and after to avoid being parsed as a heading underline.

Escaping special characters

Prefix any Markdown special character with \ to render it literally:

Special characters: \ * _ {} [] () # + - . !

Detailed sections

Fenced code blocks — language tags

Always specify the language after the opening fence. It enables syntax highlighting in GitHub, VS Code previews, and most site generators.

```javascript
const greet = (name) => `Hello, ${name}!`;
```

```python
def greet(name):
    return f"Hello, {name}!"
```

```bash
echo "Hello, world!"
```

```sql
SELECT name, email FROM users WHERE active = true;
```

For a diff block, lines starting with + render green and lines with - render red:

```diff
- const url = "http://example.com";
+ const url = "https://example.com";
```

To show a code fence inside a code fence, use more backticks on the outer fence:

````markdown
```js
// this renders as a code block inside the example
```
````

Tables — alignment and tips

A full table example with mixed alignment:

| Name       | Role      |   Salary |
|:-----------|:----------|----------:|
| Alice      | Engineer  |   $95,000 |
| Bob        | Designer  |   $88,000 |
| Carol      | Manager   |  $110,000 |

Tips:

• Pipes don’t need to align — Markdown ignores extra spaces around them
• Every row must have the same number of cells as the header
• You can’t have multi-line cells or merged cells in standard Markdown — use HTML <table> for that
• The separator row (|---|) must exist; it’s what tells the parser this is a table

GitHub Flavored Markdown (GFM) extensions

GFM is GitHub’s superset of CommonMark. It adds:

Task lists — rendered as interactive checkboxes on GitHub:

- [x] Write the README
- [x] Add CI workflow
- [ ] Write tests
- [ ] Deploy to production

Strikethrough — ~~text~~ renders as text

Autolinks — bare URLs and email addresses become clickable without <>:

Visit https://example.com or email hello@example.com

@mentions and #issue references — only render on GitHub, not in local previews:

Thanks @username for fixing #42.

Syntax highlighted fenced code blocks — already standard in most parsers, but GFM standardized the spec.

Footnotes (extended Markdown)

Supported in GitHub, Obsidian, Pandoc, and many static site generators. Not part of CommonMark.

Here is a sentence with a footnote.[^1]

[^1]: This is the footnote content. It can span multiple lines
if you indent the continuation.

Footnote references can appear anywhere in the document; they always render at the bottom.

Markdown in different contexts

Same source, different behavior — know which parser you’re targeting:

For this site (Astro + MDX), the parser is CommonMark + remark-gfm + remark directives. All GFM extensions work. JSX component imports work in .mdx files only.

Common pitfalls

Blank line before a list — without it, many parsers attach the list to the preceding paragraph:

This will break:
- item one
- item two

This works:

- item one
- item two

Indentation inside a list item — continuation paragraphs need 4 spaces (or tab) of indentation to stay inside the item:

1. First item

    This paragraph is part of item 1 (4 spaces indent).

2. Second item

Setext headings vs thematic breaks — a line of --- immediately after text is a heading, not a rule:

This becomes H2
---

---

This is a horizontal rule above.

Trailing spaces for line breaks — two trailing spaces create a <br>. Invisible and easy to lose when editors strip whitespace. Use \ (backslash) as an alternative in CommonMark, or just use a blank line for a new paragraph.

Pipe characters in table cells — escape with \| or use |:

| Command | Example |
|---|---|
| `echo` | `echo "Hello \| world"` |

Related: Vim Cheat Sheet | Git Cheat Sheet | Linux Bash Cheat Sheet

Related Articles

Deepen your understanding with these curated continuations.

View All Articles

Cheatsheet5 min read

uv Cheat Sheet: The Fast Python Package Manager (2026)

Complete uv reference — install packages, manage projects, run scripts, pin Python versions, and migrate from pip, poetry, and pyenv with working commands.

RachelMay 21, 2026

Cheatsheet5 min read

Warp Terminal Cheat Sheet: Shortcuts, Workflows & AI Features

Complete Warp reference — block-based terminal, command palette, workflow commands, AI autocomplete, custom themes, and team features in 2026.

Darsh JariwalaMay 21, 2026

Cheatsheet5 min read

React Hooks Cheat Sheet: All Hooks with React 19

Complete React Hooks reference — useState, useEffect, useMemo, useCallback, custom hooks, and React 19's new use(), useOptimistic, and useActionState.

ScarlettMay 20, 2026