Markdown Syntax Cheat Sheet: The Complete Reference

Published March 2026 · 18 min read

1. Introduction

Markdown is a lightweight markup language created by John Gruber in 2004, with significant contributions from Aaron Swartz. Its primary goal was to allow people to write in an easy-to-read, easy-to-write plain text format that could be optionally converted into structurally valid HTML. Over the past two decades, Markdown has become the de facto standard for writing documentation, README files, blog posts, forum comments, and much more.

What makes Markdown so popular? First, it is incredibly simple to learn. Unlike HTML, which requires opening and closing tags for every element, Markdown uses intuitive symbols like # for headings, * for emphasis, and - for lists. Second, Markdown files are plain text, making them version-control friendly, portable across platforms, and readable even without rendering. Third, the ecosystem is enormous — GitHub, GitLab, Stack Overflow, Reddit, Notion, Obsidian, and countless other platforms all support Markdown natively.

This cheat sheet is designed to be a comprehensive, bookmark-worthy reference. Whether you are writing a README for your open-source project, drafting documentation for your team, or composing a blog post, this guide covers every Markdown syntax element you will ever need — from the basics to advanced features like tables, footnotes, and GitHub Flavored Markdown (GFM).

2. Headers

Headers structure your document into sections and subsections. Markdown supports six levels of headers, corresponding to HTML <h1> through <h6>. You create headers by prefixing a line with one or more # characters.

ATX-Style Headers

The number of # symbols determines the heading level. Always include a space between the # and the heading text for compatibility across parsers.

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

This renders as six heading levels, from the largest (H1) to the smallest (H6). In practice, most documents use H1 for the title, H2 for major sections, and H3 for subsections.

Alternative Syntax (Setext-Style)

For H1 and H2 only, you can use an alternative underline syntax. Place any number of = characters under the text for H1, or - characters for H2:

Heading Level 1
===============

Heading Level 2
---------------

The first produces an H1 heading; the second produces an H2 heading. Both are equivalent to their ATX-style counterparts. Most developers prefer the ATX style for consistency.

3. Text Formatting

Markdown provides simple syntax for common text formatting. You can make text bold, italic, combine both, add strikethrough, or mark inline code.

Bold Text

Wrap text with double asterisks or double underscores to make it bold. Bold text renders as an HTML <strong> element.

**This text is bold**
__This is also bold__

Both produce: This text is bold. The asterisk syntax is recommended because underscores can cause issues in the middle of words.

Italic Text

Wrap text with single asterisks or single underscores for italic. This renders as an HTML <em> element.

*This text is italic*
_This is also italic_

Both produce: This text is italic. Again, asterisks are preferred for mid-word emphasis.

Bold and Italic

Combine three asterisks or three underscores for bold and italic simultaneously:

***Bold and italic***
___Also bold and italic___
**_Bold and italic mixed_**
*__Bold and italic mixed__*

All of these produce text that is both bold and italic. The triple asterisk syntax is the most common.

Strikethrough

Strikethrough is not part of the original Markdown spec but is widely supported through GitHub Flavored Markdown (GFM). Use double tildes:

~~This text is crossed out~~

This renders as: This text is crossed out. Strikethrough is useful for showing deleted or deprecated content.

Inline Code

Wrap text in backticks to render it as inline code. This applies a monospace font and typically a subtle background color:

Use the `console.log()` function for debugging.

To include a literal backtick, use double backticks: ``code with ` backtick``

The first line renders "console.log()" in a code font. The second example shows how to include a literal backtick within inline code by using double backticks as delimiters.

4. Links and Images

Links and images are fundamental to any document. Markdown makes both straightforward with a consistent bracket-and-parenthesis syntax.

Inline Links

The most common link syntax places the link text in square brackets followed by the URL in parentheses. You can optionally include a title attribute:

[Visit GitHub](https://github.com)

[Visit GitHub](https://github.com "GitHub Homepage")

<https://github.com>

<contact@example.com>

The first line creates a clickable link with the text "Visit GitHub". The second adds a tooltip that appears when hovering over the link. The third and fourth examples show automatic link and email detection using angle brackets.

Reference Links

Reference-style links separate the link definition from its usage, making your Markdown source more readable, especially when the same URL appears multiple times:

[Visit GitHub][gh]
[Read the Docs][docs]

[gh]: https://github.com "GitHub"
[docs]: https://docs.example.com "Documentation"

The link definitions (the lines starting with [gh]:) can be placed anywhere in the document. They will not be rendered in the output.

Images

Image syntax is identical to link syntax but with an exclamation mark prefix. The text inside the brackets becomes the alt text:

![Alt text for the image](https://example.com/image.png)

![Alt text](https://example.com/image.png "Image Title")

Always include meaningful alt text for accessibility. The title is optional and appears as a tooltip on hover.

Linked Images

To make an image clickable, nest the image syntax inside a link:

[![Alt text](https://example.com/logo.png)](https://example.com)

This renders an image that, when clicked, navigates to the specified URL. It is commonly used for badges in README files (e.g., build status, license, npm version).

5. Lists

Lists are one of the most frequently used Markdown elements. Markdown supports unordered lists, ordered lists, nested lists, and task lists.

Unordered Lists

Create unordered (bulleted) lists using a dash, asterisk, or plus sign followed by a space. All three markers produce identical output:

- First item
- Second item
- Third item

* First item
* Second item
* Third item

+ First item
+ Second item
+ Third item

Each produces a bulleted list with three items. For consistency, pick one marker and stick with it throughout your document. The dash is the most widely used convention.

Ordered Lists

Create ordered (numbered) lists using numbers followed by a period and a space. The actual numbers do not matter — Markdown will auto-number them sequentially:

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

1. First item
1. Second item
1. Third item

Both examples produce the same output: a numbered list from 1 to 3. Using all 1s makes it easier to reorder items without renumbering.

Nested Lists

Indent items with two or four spaces (depending on the parser) to create nested lists. You can mix ordered and unordered lists:

1. First item
   - Sub-item A
   - Sub-item B
2. Second item
   1. Sub-item 1
   2. Sub-item 2
3. Third item

This renders as a numbered list where the first and second items have nested bullet and numbered sub-lists respectively. Nesting can go as deep as needed.

Task Lists (Checkboxes)

Task lists are a GitHub Flavored Markdown extension. Use - [ ] for unchecked and - [x] for checked items:

- [x] Write the introduction
- [x] Add code examples
- [ ] Review and edit
- [ ] Publish the post

This renders as a checklist with the first two items checked and the last two unchecked. On GitHub, these checkboxes are interactive — you can toggle them directly in issues and pull requests.

6. Blockquotes

Blockquotes indicate quoted or highlighted text. They are commonly used for citing sources, adding callouts, or highlighting important notes.

Basic Blockquotes

Prefix each line with a > character followed by a space:

> Markdown is a text-to-HTML conversion tool for web writers.
> It allows you to write using an easy-to-read plain text format.

This renders as an indented block with a left border, visually distinguishing it from the surrounding text.

Nested Blockquotes

Add additional > characters to create nested blockquotes:

> First level of quoting.
>
>> Nested blockquote.
>>
>>> Deeply nested blockquote.

Each additional > adds another level of indentation. This is useful for threaded conversations or attributing quotes within quotes.

Blockquotes with Other Elements

Blockquotes can contain most other Markdown elements, including headers, lists, code blocks, and emphasis:

> ### Blockquote Heading
>
> - Item one
> - Item two
>
> **Bold text** inside a blockquote with `inline code`.

This produces a blockquote containing a heading, an unordered list, bold text, and inline code — all properly rendered within the quoted block.

7. Code

Markdown provides multiple ways to display code, from short inline snippets to multi-line blocks with syntax highlighting.

Inline Code

As shown earlier, wrap text in single backticks for inline code. This is ideal for referencing function names, variables, file paths, or short commands within a sentence:

Run `npm install` to install dependencies.

The `Array.prototype.map()` method creates a new array.

Inline code preserves whitespace and prevents Markdown from interpreting any special characters within the backticks.

Fenced Code Blocks

For multi-line code, use triple backticks (```) or triple tildes (~~~). Specify a language identifier after the opening fence to enable syntax highlighting:

```javascript
function greet(name) {
  return `Hello, ${name}!`;
}

console.log(greet("World"));
```

This renders as a code block with JavaScript syntax highlighting. Common language identifiers include javascript, python, typescript, html, css, bash, json, and sql.

Here are examples in a few more languages:

```python
def fibonacci(n):
    a, b = 0, 1
    for _ in range(n):
        yield a
        a, b = b, a + b

print(list(fibonacci(10)))
```

```bash
#!/bin/bash
for file in *.md; do
  echo "Processing $file"
  pandoc "$file" -o "${file%.md}.html"
done
```

Indented Code Blocks

An older syntax for code blocks uses four spaces of indentation. This method does not support language-specific syntax highlighting:

    function add(a, b) {
      return a + b;
    }

Each line must be indented by at least four spaces or one tab. Fenced code blocks are generally preferred because they support syntax highlighting and are more explicit.

8. Tables

Tables are a GitHub Flavored Markdown extension. They use pipes and hyphens to define columns and rows.

Basic Table

Create a table by separating columns with pipes (|) and using hyphens for the header separator row:

| Feature    | Markdown   | HTML         |
| ---------- | ---------- | ------------ |
| Bold       | **text**   | <strong>     |
| Italic     | *text*     | <em>         |
| Code       | `text`     | <code>       |
| Link       | [text](url)| <a>          |

The first row defines column headers. The second row (with hyphens) is required and separates headers from data. Subsequent rows contain the data. The pipes do not need to be perfectly aligned, but alignment improves readability of the source.

Column Alignment

Control text alignment within columns by adding colons to the separator row:

| Left Aligned | Center Aligned | Right Aligned |
| :----------- | :------------: | ------------: |
| Left         |    Center      |         Right |
| Text         |    Text        |          Text |
| Data         |    Data        |          Data |

A colon on the left (:---) means left-aligned (default). Colons on both sides (:---:) means center-aligned. A colon on the right (---:) means right-aligned.

9. Horizontal Rules

Horizontal rules create a visual divider in your document. They render as an HTML <hr> element. There are three ways to create them:

---

***

___

All three produce identical horizontal lines. Use at least three characters. You can also include spaces between them (e.g., - - -). Place blank lines before and after a horizontal rule to prevent it from being interpreted as a setext-style heading.

10. Advanced Syntax

Beyond the basics, many Markdown processors support extended syntax features. Availability varies by platform and parser.

Footnotes

Footnotes allow you to add notes and references without cluttering the main text. They are supported by many processors including GitHub:

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

Another sentence with a named footnote.[^note]

[^1]: This is the first footnote content.
[^note]: This is a named footnote. You can use any identifier.

The footnote references appear as superscript numbers in the rendered output, and clicking them jumps to the footnote content, which is typically collected at the bottom of the page.

Definition Lists

Some Markdown processors (such as PHP Markdown Extra and Pandoc) support definition lists. This syntax is not part of the CommonMark spec and is not supported on GitHub:

Markdown
: A lightweight markup language for formatting plain text.

HTML
: The standard markup language for documents designed to be displayed
  in a web browser.

The term appears on its own line, followed by a line starting with a colon and a space containing the definition. This renders as an HTML <dl> element with <dt> and <dd> children.

Abbreviations

Abbreviations are supported by some extended Markdown processors. Hovering over the abbreviation shows the full text as a tooltip:

The HTML specification is maintained by the W3C.

*[HTML]: Hyper Text Markup Language
*[W3C]: World Wide Web Consortium

When rendered by a supporting processor, every instance of "HTML" and "W3C" in the document will have a tooltip with the full form.

Emoji Shortcodes

Many platforms support emoji shortcodes — special keywords wrapped in colons that are replaced with their corresponding emoji:

:smile: :rocket: :thumbsup: :warning: :heavy_check_mark:

:heart: :star: :fire: :bug: :memo:

GitHub, Slack, Discord, and many other platforms support this syntax. The available shortcodes vary by platform. On GitHub, you can find the complete list in the emoji cheat sheet documentation.

11. GitHub Flavored Markdown (GFM)

GitHub Flavored Markdown is a superset of standard Markdown maintained by GitHub. It adds several features that are particularly useful for software development workflows. GFM is based on the CommonMark spec with additional extensions.

Task Lists

As covered in the Lists section, GFM supports interactive task lists in issues and pull requests:

### Release Checklist
- [x] Update version number
- [x] Run test suite
- [ ] Update changelog
- [ ] Create release tag
- [ ] Deploy to production

Autolinks

GFM automatically converts URLs and email addresses into clickable links without requiring any special syntax:

Visit https://github.com for more information.

Send feedback to support@example.com.

In standard Markdown, you would need angle brackets around these URLs. GFM handles them automatically.

@Mentions and #References

On GitHub, you can reference users, teams, issues, and pull requests directly in Markdown:

@username - Mentions a user and sends them a notification
@org/team-name - Mentions an entire team

#123 - Links to issue or PR number 123
GH-123 - Alternative syntax for issue references

username/repo#123 - Cross-repo issue reference

SHA: a1b2c3d - Links to a specific commit

These references are rendered as clickable links and, in the case of @mentions, trigger notifications. This is essential for collaboration and code review workflows.

Syntax Highlighting in Code Blocks

GFM supports syntax highlighting for hundreds of programming languages. Specify the language after the opening fence for proper highlighting:

```typescript
interface User {
  id: number;
  name: string;
  email: string;
  roles: string[];
}

function getDisplayName(user: User): string {
  return user.name || user.email;
}
```

```sql
SELECT u.name, COUNT(o.id) AS order_count
FROM users u
LEFT JOIN orders o ON u.id = o.user_id
WHERE u.created_at > '2025-01-01'
GROUP BY u.name
HAVING COUNT(o.id) > 5
ORDER BY order_count DESC;
```

```diff
- const oldValue = "before";
+ const newValue = "after";

  function unchanged() {
-   return oldValue;
+   return newValue;
  }
```

The diff language identifier is particularly useful for showing changes, with lines prefixed by - highlighted in red and + highlighted in green.

Tables in GFM

While we covered table syntax earlier, it is worth noting that tables are a GFM extension — they are not part of the original Markdown spec. GFM tables support formatting within cells:

| Method   | Endpoint         | Description              |
| -------- | ---------------- | ------------------------ |
| `GET`    | `/api/users`     | List all users           |
| `POST`   | `/api/users`     | Create a new user        |
| `GET`    | `/api/users/:id` | Get user by ID           |
| `PUT`    | `/api/users/:id` | Update user              |
| `DELETE` | `/api/users/:id` | **Permanently** delete   |

You can use inline code, bold, italic, links, and images inside table cells. However, block-level elements like lists, blockquotes, and code blocks cannot be used inside cells.

Alerts (Admonitions)

GitHub recently introduced alert syntax for highlighting important information using special blockquote markers:

> [!NOTE]
> Useful information that users should know.

> [!TIP]
> Helpful advice for doing things better.

> [!IMPORTANT]
> Key information users need to know.

> [!WARNING]
> Urgent info that needs immediate attention.

> [!CAUTION]
> Advises about risks or negative outcomes.

Each alert type renders with a distinct color and icon on GitHub, making them excellent for documentation, READMEs, and wiki pages.

12. Tips for Better Markdown

Writing clean, consistent Markdown makes your documents easier to read, maintain, and collaborate on. Here are best practices to adopt.

Maintain a Consistent Style

• Pick one list marker and use it everywhere (- is the most common)
• Use ** for bold and * for italic consistently (avoid underscores)
• Use ATX-style headers (#) rather than setext-style
• Use fenced code blocks instead of indented code blocks
• Add a blank line before and after headings, lists, and code blocks

Line Breaks and Paragraphs

Understanding line breaks in Markdown is crucial because it behaves differently from what you might expect:

This is a single paragraph
even though it spans two lines in the source.

This is a new paragraph because of the blank line above.

This line has a hard break
(two trailing spaces before the line break).

This line uses a backslash\
for a hard line break.

A single newline in the source is treated as a space (soft wrap). A blank line creates a new paragraph. For a line break within a paragraph, add two trailing spaces or a backslash at the end of the line.

Escaping Special Characters

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

\* This is not a list item
\# This is not a heading
\[This is not a link](not-a-url)
\> This is not a blockquote

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

The backslash tells the parser to treat the following character literally rather than as a Markdown formatting symbol.

Recommended Editors and Tools

Having the right tools makes writing Markdown more productive. Here are some popular options:

• VS Code — built-in Markdown preview with extensions like Markdown All in One and markdownlint
• Obsidian — knowledge base and note-taking app built entirely on Markdown
• Typora — WYSIWYG-style Markdown editor that renders as you type
• Dillinger — online Markdown editor with live preview and export options
• markdownlint — a linter that enforces consistent Markdown style in your projects
• Pandoc — a universal document converter that can convert Markdown to PDF, DOCX, HTML, and more

Quick Reference Table

Here is a condensed reference table of the most common Markdown syntax:

13. Try It Yourself

The best way to learn Markdown is to practice. Take any of the examples from this guide and paste them into a live editor to see how they render. Experiment by combining different syntax elements — nest a list inside a blockquote, add bold text to a table cell, or create a complex document structure with multiple heading levels.

We built a free, browser-based Markdown preview tool specifically for this purpose. It renders your Markdown in real time as you type, supports GitHub Flavored Markdown, and requires no account or installation.

Markdown mastery comes with repetition. Once the syntax becomes second nature, you will find yourself writing documentation, README files, and notes faster than ever before. Bookmark this cheat sheet and come back whenever you need a quick reference.