Markdown Cheat Sheet 2026: Every Syntax You Need

Why Markdown Matters in 2026

Markdown is used in GitHub (README, issues, PRs, wikis), GitLab, Bitbucket, Notion, Obsidian, Confluence, Slack (partial), Discord, Reddit, Stack Overflow, Jekyll, Hugo, Gatsby, Docusaurus, and virtually every static site generator. It is the closest thing to a universal document format for technical writing.

Despite its simplicity, Markdown has real gotchas: two spaces vs a blank line for line breaks, the difference between an ordered list that restarts numbering vs one that continues, how to escape characters, and the many extensions added by GitHub Flavored Markdown (GFM). This reference covers all of it.

Headings

Headings use the # prefix. The number of hashes corresponds to the HTML heading level (h1–h6):

# H1 - Page title (use only one per document)
## H2 - Major section
### H3 - Subsection
#### H4
##### H5
###### H6

An alternative syntax for H1 and H2 uses underlines:

H1 Heading
==========

H2 Heading
----------

Best practice: Always include a space after the #. Some parsers are strict about this. Use only one H1 per document. Structure headings hierarchically (do not jump from H2 to H4).

Emphasis: Bold, Italic, Strikethrough

**bold text**            <!-- or __bold__ -->
*italic text*            <!-- or _italic_ -->
***bold and italic***    <!-- or ___bold and italic___ -->
~~strikethrough~~        <!-- GitHub Flavored Markdown (GFM) -->
`inline code`

Rendered output: bold text, italic text, bold and italic.

Note on underscores: In mid-word contexts, underscores do not trigger emphasis in most CommonMark parsers (e.g., snake_case_variable renders without italics). Asterisks are more reliable and preferred for consistency.

Lists

Unordered lists

- Item one
- Item two
  - Nested item (indent 2 spaces)
  - Another nested item
- Item three

* Also valid with asterisks
+ Or plus signs

Ordered lists

1. First item
2. Second item
3. Third item

1. The actual numbers don't matter
1. Markdown auto-numbers them
1. So you can use 1. for every line

Task lists (GFM)

GitHub, GitLab, Notion, and most modern renderers support interactive task lists:

- [x] Completed task
- [ ] Incomplete task
- [x] Another done item
- [ ] Another pending item

In GitHub, checking and unchecking these boxes updates the underlying Markdown source automatically.

Links and Images

<!-- Inline link -->
[Link text](https://example.com)
[Link with title](https://example.com "Tooltip text")

<!-- Reference-style link (cleaner for repeated URLs) -->
[Link text][reference-id]
[reference-id]: https://example.com "Optional title"

<!-- Auto-link -->
<https://example.com>
<user@example.com>

<!-- Image: same syntax as link, prefixed with ! -->
![Alt text](image.png)
![Alt text](image.png "Optional title")

<!-- Image with link -->
[![Alt text](image.png)](https://example.com)

Code

Inline code

Use `backticks` for inline code.
Use ``double backticks if the code contains a `backtick` itself``.

Fenced code blocks

Use triple backticks or triple tildes. Adding a language identifier after the opening fence enables syntax highlighting in most renderers:

```javascript
const greet = (name) => `Hello, ${name}!`;
console.log(greet('World'));
```

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

```bash
echo "Hello, World!"
curl -X POST https://api.example.com/data
```

```sql
SELECT id, name, email
FROM users
WHERE created_at > '2026-01-01'
ORDER BY name;
```

Commonly supported language identifiers: javascript, typescript, python, bash, sh, sql, json, yaml, html, css, go, rust, java, php, ruby, cpp, c, diff.

Blockquotes

> This is a blockquote.
> It can span multiple lines.
>
> And multiple paragraphs.

> Nested blockquote:
>> This is nested one level.
>>> And another level.

Horizontal Rules

---
***
___

<!-- All three produce a <hr> element -->

Tables (GFM)

Tables are a GitHub Flavored Markdown extension, not part of original Markdown. They are supported by GitHub, GitLab, Notion, Obsidian, and most modern renderers.

| Column 1    | Column 2    | Column 3    |
| ----------- | ----------- | ----------- |
| Row 1, C1   | Row 1, C2   | Row 1, C3   |
| Row 2, C1   | Row 2, C2   | Row 2, C3   |

<!-- Alignment with colons in the separator row -->
| Left        | Center      | Right       |
| :---------- | :---------: | ----------: |
| Left text   | Center text | Right text  |
| More left   | More center | More right  |

The pipes do not need to be aligned - the renderer handles spacing. However, aligned pipes make the raw source much easier to read and edit.

Footnotes (Extended Markdown)

Supported by GitHub, Pandoc, and several static site generators:

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

Another sentence with a different note.[^note]

[^1]: This is the first footnote.
[^note]: Footnotes can have descriptive labels too.

Definition Lists (Extended)

Supported by Pandoc and some renderers (not GitHub):

Term
:   Definition of the term.

Another term
:   Another definition.
:   A second definition for the same term.

Escaping Special Characters

Prefix any Markdown special character with a backslash to render it literally:

\*not italic\*
\# not a heading
\[not a link\](not-a-url)
\`not code\`
\\ backslash itself

Characters that need escaping: \ ` * _ { } [ ] ( ) # + - . !

HTML in Markdown

Most Markdown renderers allow raw HTML inline. This is useful for features Markdown cannot express natively:

<!-- Centered text (not standard Markdown) -->
<div align="center">Centered content</div>

<!-- Details / summary collapsible -->
<details>
<summary>Click to expand</summary>

Hidden content goes here. Supports **Markdown** inside.

</details>

<!-- Superscript / subscript -->
H<sub>2</sub>O
E = mc<sup>2</sup>

Note: GitHub sanitizes HTML and blocks unsafe tags. Basic structural HTML (div, details, summary, sub, sup) works; script, style, and event handlers are stripped.

GitHub Flavored Markdown (GFM) Extensions Summary

GFM is the standard on GitHub, GitLab, and most developer platforms. It extends CommonMark with:

• Tables - pipe syntax with alignment
• Task lists - - [x] and - [ ]
• Strikethrough - ~~text~~
• Autolinks - bare URLs become clickable links
• @mentions - @username links to a GitHub profile
• #issue references - #123 links to an issue or PR
• Syntax highlighting - fenced code blocks with language identifiers
• Footnotes - [^1] style references
• Collapsed sections - via <details> HTML

Markdown for README Files: Best Practices

A well-structured GitHub README typically includes:

1. Project title and one-line description (H1)
2. Badges (build status, npm version, license) - using shield.io or similar
3. Short introduction and key features
4. Installation instructions (fenced bash code block)
5. Usage examples (fenced code blocks with your primary language)
6. Configuration reference (table or list)
7. Contributing guide and license

# Project Name

A brief description of what this project does and who it's for.

[![Build Status](https://img.shields.io/github/actions/workflow/status/user/repo/ci.yml)](...)
[![npm version](https://img.shields.io/npm/v/package-name)](...)

## Installation

```bash
npm install package-name
```

## Usage

```javascript
const pkg = require('package-name');
pkg.doSomething({ option: true });
```

## License

MIT

Frequently Asked Questions

What is the difference between CommonMark and GitHub Flavored Markdown?

CommonMark is a strict, unambiguous specification for Markdown that resolves many of the edge cases in John Gruber's original 2004 spec. GitHub Flavored Markdown (GFM) is a superset of CommonMark that adds tables, task lists, strikethrough, auto-linking, and GitHub-specific features like @mentions and issue references. Most platforms implement either CommonMark or GFM (or both).

How do I add a line break inside a paragraph in Markdown?

There are two ways: end a line with two or more trailing spaces (hard to see and maintain), or use a backslash at the end of the line (\) which is the GFM approach. For a paragraph break, leave a blank line between two blocks of text.

Can I use Markdown inside HTML tags?

It depends on the renderer. In standard CommonMark, Markdown inside block-level HTML tags (like <div>) is not processed. In some renderers, adding a blank line before and after the content inside the HTML tag enables Markdown parsing within it. The <details> tag with a blank line after <summary> is the most reliable case.

How do I create a table of contents in Markdown?

GitHub automatically generates anchor IDs for headings. You can link to them manually: [Section Name](#section-name) - the heading text converted to lowercase with spaces replaced by hyphens. Many editors and tools (VSCode, Obsidian) can auto-generate a TOC. Some renderers like Pandoc have built-in TOC generation flags.

Why does my Markdown not render correctly?

The most common causes: 1) Missing blank line before or after a block element (code fence, list, heading). 2) Mixed indentation (tabs vs spaces) inside lists. 3) Using renderer-specific extensions on a platform that does not support them. 4) Special characters that need escaping. Use our Markdown Preview tool to debug rendering issues against the CommonMark spec.

Preview and convert your Markdown instantly: Markdown Preview →