Markdown Cheat Sheet: Complete Syntax Guide with Examples

Markdown has become the universal language of technical writing. README files, documentation, blog posts, forum comments, note-taking apps, chat messages — Markdown is everywhere. It is the lingua franca of developers, and increasingly of everyone who writes on the web.

Yet most people only know a fraction of what Markdown can do. They know bold and headers, maybe links, and that is about it. This cheat sheet covers everything — from the basics you use every day to the advanced syntax that separates a wall of text from a beautifully structured document.

Bookmark this page. You will come back to it.

If you want to practice as you read, open our Markdown Editor in another tab. It gives you live preview so you can see your Markdown rendered in real time. You can also convert existing content using HTML to Markdown or go the other direction with Markdown to HTML.

Headings#

Headings use the # symbol. The number of # characters determines the heading level, from 1 (largest) to 6 (smallest).

# Heading 1
 
## Heading 2
 
### Heading 3
 
#### Heading 4
 
##### Heading 5
 
###### Heading 6

Important: Always put a space between the # and the heading text. #Heading will not render correctly in many parsers. Also, most style guides recommend using only one H1 per document — treat it as your page title.

There is an alternative syntax for H1 and H2 using underlines:

# Heading 1
 
## Heading 2

Both styles produce identical output. The # syntax is more common because it works for all six levels and is easier to scan visually.

Text Formatting#

Bold and Italic#

**This text is bold**
**This is also bold**
 
_This text is italic_
_This is also italic_
 
**_This text is bold and italic_**
**_This is also bold and italic_**

Convention: use **asterisks** for bold and *asterisks* for italic. The underscore variants exist but can cause issues inside words (e.g., some_variable_name might accidentally italicize).

Strikethrough#

~~This text is crossed out~~

Renders as: This text is crossed out

Subscript and Superscript#

Some Markdown parsers support these (including GitHub):

H~2~O (subscript)
X^2^ (superscript)

Support varies — these work in some flavors but not all.

Paragraphs and Line Breaks#

Paragraphs are separated by a blank line:

This is the first paragraph.
 
This is the second paragraph.

For a line break within a paragraph (without starting a new paragraph), end a line with two spaces or use <br>:

This is line one.
This is line two (same paragraph).
 
This is line one.<br>
This is line two (same paragraph).

The two-trailing-spaces approach is invisible and easy to lose during editing. Many developers prefer the explicit <br> tag for clarity.

Lists#

Unordered Lists#

Use -, *, or + as bullet markers:

- Item one
- Item two
  - Nested item
  - Another nested item
    - Deeply nested
- Item three

Renders as:

• Item one
• Item two
  • Nested item
  • Another nested item
    • Deeply nested
• Item three

Ordered Lists#

1. First item
2. Second item
3. Third item
   1. Sub-item
   2. Another sub-item
4. Fourth item

A useful trick: Markdown does not care about the actual numbers. This is valid and renders as 1, 2, 3:

1. First
1. Second
1. Third

This is helpful when you frequently reorder items — no renumbering needed. Some style guides recommend using 1. for every item; others prefer sequential numbering for readability in raw form.

Mixed Lists#

You can nest ordered lists inside unordered lists and vice versa:

- Category A
  1. First item
  2. Second item
- Category B
  1. First item
  2. Second item

Links#

Inline Links#

[Link text](https://example.com)
[Link with title](https://example.com "Hover tooltip text")

Reference Links#

For documents with many links, reference-style keeps the text clean:

Read the [official documentation][docs] for details.
Also check the [FAQ][faq].
 
[docs]: https://example.com/docs "Documentation"
[faq]: https://example.com/faq

The reference definitions can go anywhere in the document — most people put them at the bottom.

Autolinks#

Most Markdown parsers automatically convert URLs into clickable links:

https://example.com

You can also use angle brackets for explicit autolinks:

<https://example.com>
<user@example.com>

Images#

Images use the same syntax as links, prefixed with !:

![Alt text](image-url.jpg)
![Alt text](image-url.jpg "Optional title")

Always include alt text. It is essential for accessibility and good practice for SEO. The alt text should describe the image content for users who cannot see it.

Images with Links#

Wrap the image syntax in a link:

[![Alt text](image.jpg)](https://example.com)

Reference-Style Images#

![Alt text][logo]
 
[logo]: /images/logo.png "Company Logo"

Code#

Inline Code#

Use single backticks for inline code:

Use the `console.log()` function for debugging.
The `<div>` element is a block container.

Code Blocks#

Use triple backticks (fenced code blocks) with an optional language identifier for syntax highlighting:

```javascript
function greet(name) {
  return `Hello, ${name}!`;
}
 
console.log(greet("World"));
```

Common language identifiers: javascript, typescript, python, bash, html, css, json, sql, rust, go, java, c, cpp, markdown.

You can also create code blocks by indenting every line with four spaces:

    function example() {
      return true;
    }

The fenced style with language tags is strongly preferred — it enables syntax highlighting and is much easier to read in raw form.

Diff Syntax#

Some parsers support diff highlighting:

```diff
- const oldValue = 42;
+ const newValue = 100;
```

This is great for showing code changes. If you need to compare longer texts, our Text Diff tool can generate visual diffs for you.

Blockquotes#

Prefix lines with >:

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

Renders as:

This is a blockquote. It can span multiple lines.

And include multiple paragraphs.

Nested Blockquotes#

> First level
>
> > Second level
> >
> > > Third level

Blockquotes with Other Elements#

Blockquotes can contain any other Markdown elements:

> #### A heading inside a quote
>
> - List item one
> - List item two
>
> **Bold text** and `inline code` work too.

Tables#

Tables use pipes | and hyphens -:

| Feature | Markdown     | HTML       |
| ------- | ------------ | ---------- |
| Bold    | `**text**`   | `<strong>` |
| Italic  | `*text*`     | `<em>`     |
| Code    | `` `text` `` | `<code>`   |

Renders as:

Column Alignment#

Use colons in the separator row:

| Left-aligned | Center-aligned | Right-aligned |
| :----------- | :------------: | ------------: |
| Left         |     Center     |         Right |
| Data         |      Data      |          Data |

The table does not need to look pretty in raw Markdown. This ugly version renders identically:

| Name  | Age | City |
| ----- | --- | ---- |
| Alice | 30  | NYC  |
| Bob   | 25  | LA   |

But readable raw formatting is considered good practice, especially in collaborative projects.

Horizontal Rules#

Any of these create a horizontal line:

---
 
---
 
---

Use horizontal rules to create visual separation between sections. Three hyphens --- is the most common convention.

Task Lists#

Task lists (checkboxes) are a GitHub-Flavored Markdown extension that is now widely supported:

- [x] Write the introduction
- [x] Add code examples
- [ ] Review for typos
- [ ] Publish the post

Renders as:

• Write the introduction
• Add code examples
• Review for typos
• Publish the post

Task lists are incredibly useful in GitHub issues and pull request descriptions for tracking progress.

Footnotes#

Footnotes let you add references without cluttering the main text:

Here is a sentence with a footnote.[^1]
 
And another with a named footnote.[^note]
 
[^1]: This is the first footnote content.
 
[^note]: Footnotes can have any identifier, not just numbers.

Footnotes are rendered at the bottom of the document with automatic numbering and back-links. They are supported in GitHub-Flavored Markdown, Jekyll, Hugo, and most modern parsers.

Escaping Characters#

To display a literal character that would otherwise be interpreted as Markdown formatting, prefix it with a backslash:

\* This is not italic \*
\# This is not a heading
\[This is not a link\](not-a-url)

Characters you can escape: \ ` * _ { } [ ] ( ) # + - . ! |

HTML in Markdown#

Markdown supports inline HTML for anything that Markdown syntax cannot handle:

<details>
<summary>Click to expand</summary>
 
This content is hidden by default.
 
- You can use **Markdown** inside HTML blocks.
- Just make sure to leave blank lines around Markdown content.
 
</details>

Other useful HTML in Markdown:

<kbd>Ctrl</kbd> + <kbd>C</kbd>
 
<mark>Highlighted text</mark>
 
<abbr title="Hypertext Markup Language">HTML</abbr>

Use HTML sparingly. The whole point of Markdown is readability in raw form — if your document is mostly HTML, you might as well write HTML.

GitHub-Flavored Markdown Extras#

GitHub extends standard Markdown with several features that have become widely adopted.

Alerts / Admonitions#

> [!NOTE]
> Useful information that users should know.
 
> [!TIP]
> Helpful advice for doing things better.
 
> [!WARNING]
> Urgent info that needs immediate attention.
 
> [!CAUTION]
> Advises about risks or negative outcomes.

Emoji Shortcodes#

:rocket: :star: :white_check_mark: :warning:

Some platforms render these as emoji. On others, you can paste Unicode emoji directly: 🚀 ⭐ ✅ ⚠️

Automatic URL Linking#

GitHub and most modern parsers automatically turn URLs into clickable links without any special syntax needed.

Mentioning Users and Issues#

In GitHub specifically:

@username mentioned this in #42.
Fixes #123.

Advanced Patterns#

Definition Lists#

Supported by some parsers (PHP Markdown Extra, Pandoc):

Term
: Definition of the term.
 
Another term
: Another definition.

Table of Contents#

Many tools auto-generate a table of contents from headings. You can also create one manually:

## Table of Contents
 
- [Introduction](#introduction)
- [Getting Started](#getting-started)
- [Advanced Usage](#advanced-usage)

The anchor links are auto-generated from heading text: lowercase, spaces replaced with hyphens, special characters removed.

Embedding Videos and Media#

Standard Markdown has no video support, but you can use an image as a clickable thumbnail:

[![Video title](thumbnail.jpg)](https://youtube.com/watch?v=VIDEO_ID)

Or use HTML directly:

<video src="video.mp4" controls width="600"></video>

Quick Reference Table#

Here is a compact reference you can scan quickly:

Which Markdown Flavor Should You Use#

Not all Markdown is created equal. Here are the main variants:

CommonMark is the standardized specification. If you want maximum portability, write CommonMark.

GitHub-Flavored Markdown (GFM) extends CommonMark with tables, task lists, strikethrough, and autolinks. It is the de facto standard for developer documentation.

MultiMarkdown adds footnotes, definition lists, math, and metadata. Popular in academic writing.

Pandoc Markdown is the Swiss Army knife — it supports practically everything and can convert between dozens of formats.

For most people, writing GFM-compatible Markdown covers 95% of use cases and renders correctly on GitHub, GitLab, VS Code, Notion, Obsidian, and almost every other tool.

Markdown Best Practices#

Use blank lines generously. Separate every block element (headings, paragraphs, lists, code blocks) with blank lines. Some parsers require this; all parsers handle it correctly.

Be consistent with list markers. Pick - or * for unordered lists and stick with it throughout your document.

Use fenced code blocks over indented ones. The fenced style with language identifiers enables syntax highlighting and is unambiguous.

Use reference links for repeated URLs. If the same URL appears multiple times, define it once as a reference.

Write meaningful alt text for images. Screen readers depend on it. Search engines use it. Your future self will appreciate knowing what that image was supposed to show.

Keep lines under 80-120 characters in source files when possible. This makes diffs cleaner and the raw text easier to read. Many Markdown editors soft-wrap, but version control diffs work line by line.

Tools to Make Markdown Easier#

Writing Markdown in a plain text editor is fine, but the right tools make it faster:

• Markdown Editor — Write Markdown with live preview, syntax highlighting, and export options. Great for drafting blog posts and documentation.
• HTML to Markdown — Convert existing web content into clean Markdown. Useful when migrating documentation or capturing content from websites.
• Markdown to HTML — Generate HTML from your Markdown for embedding in places that do not render Markdown natively.
• Text Diff — Compare two versions of a document to see exactly what changed, line by line.

Wrapping Up#

Markdown is one of those rare tools that is simple enough to learn in five minutes and powerful enough to use for the rest of your career. The syntax is minimal by design — the goal is to write content that is readable both as source text and as rendered output.

You do not need to memorize every element in this guide. Bookmark it, come back when you need something specific, and over time the syntax will become muscle memory. Start with headings, bold, lists, links, and code blocks — those five elements handle 90% of what you will ever need.

The remaining 10% — tables, footnotes, task lists, HTML blocks — are there when you need them. And now you know exactly where to find them.