Markdown Cheat Sheet & Complete Guide for 2026

Published February 11, 2026 · 18 min read

Markdown is the most widely used lightweight markup language in the world. Whether you are writing documentation on GitHub, taking notes in Obsidian, crafting a README, composing a Reddit post, or authoring a blog, Markdown lets you format text quickly without touching any HTML. This comprehensive guide covers every Markdown syntax element you will ever need, from the absolute basics to advanced features, with clear examples for each.

⚙ Try it: Practice as you read: Open our Markdown Preview tool in another tab to try every example in real-time and see the rendered output instantly.

Table of Contents

1. What is Markdown and Why Use It

Markdown was created by John Gruber in 2004 with the goal of making it easy to write content that is readable as plain text and can also be converted to structurally valid HTML. The original design philosophy was simple: the source text should be publishable as-is, without looking like it has been littered with tags or formatting instructions.

Two decades later, Markdown has become the de facto standard for writing on the web. It is used in:

Why Use Markdown Instead of a Rich Text Editor?

There are several compelling reasons to use Markdown over traditional WYSIWYG editors:

The Markdown specification has evolved over the years. The original Markdown by John Gruber left some edge cases ambiguous, which led to the creation of CommonMark in 2014 — a strongly defined, highly compatible specification. Most modern platforms follow CommonMark, often with their own extensions (such as GitHub Flavored Markdown, or GFM).

2. Headings

Headings are created by placing one or more hash symbols (#) before your heading text. The number of hashes determines the heading level, from 1 (largest) to 6 (smallest).

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

This renders as the HTML equivalents <h1> through <h6>.

Heading Best Practices

Alternative Heading Syntax

For heading levels 1 and 2 only, you can also use an underline style:

Heading 1
=========

Heading 2
---------

This is called "Setext-style" headings. While valid, the ATX-style (#) is preferred because it supports all six levels and is more visually obvious in source text.

Heading IDs for Anchors

Many Markdown processors (including GitHub) automatically generate anchor IDs from headings. A heading like ## Getting Started becomes <h2 id="getting-started">, which you can link to with [link text](#getting-started). This is essential for creating table-of-contents navigation in long documents.

3. Paragraphs and Line Breaks

Paragraphs in Markdown are simply one or more consecutive lines of text, separated by one or more blank lines.

This is the first paragraph. It can span
multiple lines in the source and will be
rendered as a single paragraph.

This is the second paragraph. The blank line
above separates the two paragraphs.

Line Breaks

To create a line break within a paragraph (a <br> tag) without starting a new paragraph, you have two options:

This line has two trailing spaces at the end
so this appears on the next line.

This line uses a backslash at the end\
so this also appears on the next line.

The two-trailing-spaces method is the original Markdown approach. The backslash method is a CommonMark addition that is easier to see in source text. Both produce the same <br> output.

Important: Simply pressing Enter once does not create a line break or a new paragraph in most Markdown parsers. The text will continue on the same line in the output. This catches many beginners off guard.

This line
and this line
will render as a single line of text.

But this line

and this line are separate paragraphs.

4. Emphasis: Bold, Italic, and Strikethrough

Markdown provides simple syntax for emphasizing text. You can use either asterisks (*) or underscores (_), though asterisks are the more common convention.

Italic (Emphasis)

*This text is italic*
_This text is also italic_

Bold (Strong Emphasis)

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

Bold and Italic Combined

***This text is bold and italic***
___This text is also bold and italic___
**_You can also mix them like this_**
*__Or like this__*

Strikethrough

Strikethrough is not part of the original Markdown spec, but it is supported by GitHub Flavored Markdown (GFM) and most modern parsers:

~~This text has a strikethrough~~

Emphasis Best Practices

⚙ Try it: Need to convert existing HTML to Markdown? Use our HTML to Markdown Converter to automatically transform formatted HTML back into clean Markdown syntax.

5. Lists: Ordered, Unordered, and Nested

Lists are one of the most frequently used Markdown elements. They are straightforward to create and can be nested to any depth.

Unordered Lists

Use a dash (-), asterisk (*), or plus sign (+) followed by a space:

- First item
- Second item
- Third item

* First item
* Second item
* Third item

+ First item
+ Second item
+ Third item

All three markers produce identical output. Pick one and be consistent throughout your document. The dash (-) is the most common choice in practice.

Ordered Lists

Use a number followed by a period and a space:

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

Here is something surprising: the actual numbers do not matter. Markdown will always render a sequential numbered list regardless of the numbers you type:

1. First item
1. Second item
1. Third item
8. Fourth item

This renders as 1, 2, 3, 4 in the output. Some people use 1. for every item so they do not have to renumber when inserting items. Others prefer actual sequential numbers for source readability. Both approaches work.

Nested Lists

Indent by two or four spaces (or one tab) to create nested lists:

- Fruits
  - Apples
    - Granny Smith
    - Fuji
  - Bananas
  - Oranges
- Vegetables
  - Carrots
  - Broccoli

1. First step
   1. Sub-step A
   2. Sub-step B
2. Second step
   - An unordered sub-item
   - Another sub-item
3. Third step

You can mix ordered and unordered lists when nesting. This is useful for step-by-step guides where some steps have bulleted details.

Adding Content Inside List Items

You can include paragraphs, code blocks, images, and even blockquotes inside list items by indenting them to align with the first character of the list item text:

1. First item

   This is a paragraph that belongs to the first item.
   It is indented to align with the item text.

   ```
   This code block also belongs to item 1
   ```

2. Second item

Links are essential in any document. Markdown supports several link styles.

Inline Links

The most common link format uses square brackets for the text and parentheses for the URL:

[DevToolbox](https://devtoolbox.dedyn.io/)
[Markdown Guide](https://www.markdownguide.org "Optional title text")

The optional title text appears as a tooltip when hovering over the link.

Reference Links

For documents with many links, reference-style links keep the text clean and the URLs organized at the bottom:

Check out [DevToolbox][1] for free developer tools.
Also see the [Markdown specification][spec].

[1]: https://devtoolbox.dedyn.io/
[spec]: https://commonmark.org/ "CommonMark Spec"

The reference labels are case-insensitive and can be numbers, words, or phrases. They do not appear in the rendered output.

Autolinks

Wrap a URL or email address in angle brackets to create an automatic link:

<https://devtoolbox.dedyn.io>
<contact@example.com>

Most modern Markdown parsers (including GFM) also autolink bare URLs without angle brackets, but using angle brackets is more portable.

Section Links (Anchors)

Link to headings within the same document using the heading text converted to lowercase, with spaces replaced by hyphens:

[Jump to the Tables section](#tables)
[See Best Practices](#tips-and-best-practices)

7. Images

Images use the same syntax as links, but with an exclamation mark (!) in front:

![Alt text for the image](https://example.com/image.png)
![Logo](./images/logo.png "Optional title")

The alt text is critical for accessibility. Screen readers use it to describe the image to visually impaired users, and it displays when the image fails to load.

Image with a Link

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

[![Alt text](image-url.png)](https://destination-url.com)

Reference-Style Images

![Screenshot of the dashboard][dashboard]

[dashboard]: ./screenshots/dashboard.png "Dashboard view"

Image Sizing

Standard Markdown does not support image dimensions. If you need to control size, you have two options:

<!-- HTML approach (works in most Markdown renderers) -->
<img src="photo.jpg" alt="Photo" width="400">

<!-- Some parsers support non-standard attributes -->
![Photo](photo.jpg){width=400}

8. Code: Inline and Blocks

Markdown has excellent support for displaying code, which is one of the main reasons it became so popular among developers.

Inline Code

Wrap text in single backticks to format it as inline code:

Use the `console.log()` function to debug.
The `<div>` element is a block-level container.
Run `npm install` to install dependencies.

Inline code is rendered in a monospace font and is typically displayed with a subtle background highlight. Use it for variable names, function names, commands, file names, keyboard shortcuts, and short code snippets.

Backticks Inside Inline Code

If your code contains a backtick, use double backticks:

``Use a single backtick (`) for inline code.``
`` `template literals` use backticks in JavaScript ``

Fenced Code Blocks

For multi-line code, use three backticks (or three tildes) on their own lines before and after the code:

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

Syntax Highlighting

Add a language identifier after the opening backticks to enable syntax highlighting:

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

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

```css
.container {
    display: flex;
    justify-content: center;
    align-items: center;
    gap: 1rem;
}
```

```bash
#!/bin/bash
echo "Hello, World!"
for i in {1..5}; do
    echo "Count: $i"
done
```

```sql
SELECT users.name, COUNT(orders.id) AS order_count
FROM users
LEFT JOIN orders ON users.id = orders.user_id
GROUP BY users.name
HAVING order_count > 5
ORDER BY order_count DESC;
```

Common language identifiers include: javascript (or js), python (or py), typescript (or ts), html, css, bash (or shell), json, yaml, sql, go, rust, java, c, cpp, csharp, ruby, php, swift, kotlin, markdown (or md), dockerfile, xml, and diff.

Indented Code Blocks

The original Markdown syntax for code blocks uses four spaces of indentation:

    function oldSchool() {
        return "This is an indented code block";
    }

Fenced code blocks (with backticks) are strongly preferred over indented code blocks because they support syntax highlighting and do not require indentation of every line.

⚙ Try it: Want to convert your Markdown to HTML? Use our Markdown to HTML Converter to instantly generate clean, semantic HTML from any Markdown text.

9. Tables

Tables are part of GitHub Flavored Markdown (GFM) and are supported by most modern parsers. They use pipes (|) and hyphens (-) to define columns and rows.

Basic Table

| Feature     | Markdown | HTML    |
|-------------|----------|---------|
| Headings    | #        | <h1>    |
| Bold        | **text** | <strong>|
| Italic      | *text*   | <em>    |
| Link        | [text]() | <a>     |
| Image       | ![alt]() | <img>   |

Column Alignment

Use colons in the separator row to control alignment:

| Left Aligned | Center Aligned | Right Aligned |
|:-------------|:--------------:|--------------:|
| Left         |    Center      |         Right |
| text         |     text       |          text |
| more         |     more       |          more |

Table Tips

| Shorthand | Aligned columns not required |
| --- | --- |
| This works | even if columns are messy |
| **Bold** and `code` | work inside cells |
⚙ Try it: Tired of hand-crafting Markdown tables? Our Markdown Table Generator lets you build tables visually with a spreadsheet-like interface and exports perfect Markdown syntax.

10. Blockquotes

Blockquotes are created by prefixing lines with a greater-than sign (>). They are used for quoting text, highlighting important notes, or creating callout boxes.

Basic Blockquote

> This is a blockquote. It can span
> multiple lines and will be rendered
> as a single indented block.

Multi-Paragraph Blockquote

> First paragraph of the quote.
>
> Second paragraph of the quote.

Nested Blockquotes

> Outer quote
>
> > Nested quote inside the outer quote
> >
> > > Even deeper nesting is possible
>
> Back to the outer quote

Blockquotes with Other Elements

You can use most Markdown elements inside blockquotes:

> ### Blockquote Heading
>
> This quote contains **bold text** and a list:
>
> - Item one
> - Item two
>
> And even `inline code`.

Callout Patterns

Many platforms (GitHub, Obsidian, and others) support special callout syntax inside blockquotes:

> [!NOTE]
> This is a note callout on GitHub.

> [!WARNING]
> This is a warning callout on GitHub.

> [!TIP]
> This is a tip callout on GitHub.

> [!IMPORTANT]
> This is an important callout on GitHub.

> [!CAUTION]
> This is a caution callout on GitHub.

These render with special colored styling on GitHub (introduced in late 2023). On platforms that do not support callouts, they render as normal blockquotes with the label text visible.

11. Horizontal Rules

A horizontal rule (<hr>) creates a visual divider between sections. Use three or more hyphens, asterisks, or underscores on a line by themselves:

---

***

___

- - -

* * *

All five produce the same output. Hyphens (---) are the most common choice. Make sure to have a blank line before and after the horizontal rule, especially before, because --- directly below text will be interpreted as a Setext-style heading.

12. Task Lists and Checkboxes

Task lists (also called checkbox lists or to-do lists) are a GitHub Flavored Markdown extension supported by most modern platforms. They are extremely useful in issues, pull requests, and project management documents.

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

Use [x] for checked (completed) items and [ ] for unchecked (pending) items. On GitHub, these render as interactive checkboxes that can be toggled directly in the rendered view.

Nested Task Lists

- [ ] Project setup
  - [x] Initialize repository
  - [x] Configure linting
  - [ ] Set up CI/CD pipeline
- [ ] Core features
  - [x] User authentication
  - [ ] Dashboard
  - [ ] API integration
- [ ] Testing
  - [ ] Unit tests
  - [ ] Integration tests

Task lists are particularly powerful in GitHub issues because the platform shows progress (e.g., "3 of 7 tasks completed") in the issue list view.

13. Footnotes

Footnotes allow you to add references and annotations without cluttering the main text. They are supported by GitHub (since 2021), PHP Markdown Extra, Pandoc, and many other processors.

Markdown was created by John Gruber[^1] with contributions
from Aaron Swartz[^2].

The CommonMark specification[^spec] was established to
standardize Markdown parsing.

[^1]: John Gruber is the author of the Daring Fireball blog.
[^2]: Aaron Swartz was a programmer and internet activist.
[^spec]: CommonMark: https://commonmark.org/

Footnote references are rendered as superscript numbers that link to the footnote content at the bottom of the page. The footnote definitions can be placed anywhere in the document — the renderer will always collect them at the end.

Multi-Line Footnotes

[^long]: This is a longer footnote with multiple paragraphs.

    Indent subsequent paragraphs by four spaces so they
    belong to the same footnote.

    You can even include code blocks:

        console.log("Inside a footnote!");

14. Markdown on Different Platforms

While the core Markdown syntax is universal, different platforms add their own extensions and sometimes have subtle differences in rendering. Here is what you need to know about the most popular platforms.

GitHub Flavored Markdown (GFM)

GitHub's Markdown flavor is the most widely adopted extension. It adds:

```mermaid
graph LR
    A[Start] --> B{Decision}
    B -->|Yes| C[Action]
    B -->|No| D[End]
```

This is an inline math expression: $E = mc^2$

$$
\sum_{i=1}^{n} x_i = x_1 + x_2 + \cdots + x_n
$$

GitLab Flavored Markdown

GitLab supports all GFM features plus:

Reddit

Reddit uses a somewhat limited Markdown variant. Key differences:

This is a >!spoiler on Reddit!<
This is ^superscript text
This is ^(superscript with spaces)

Discord

Discord supports a subset of Markdown for chat messages:

||This is a spoiler on Discord||
__This is underlined on Discord__

Note: Discord's underline syntax (__text__) conflicts with Markdown's bold-via-underscores convention, so Discord treats double underscores as underline, not bold.

Slack

Slack uses its own variant called "mrkdwn" that is significantly different from standard Markdown:

# Slack vs Standard Markdown

Standard:  **bold**    Slack: *bold*
Standard:  *italic*    Slack: _italic_
Standard:  ~~strike~~  Slack: ~strike~
Standard:  [text](url) Slack: <url|text>

Be careful when switching between platforms. The same syntax can produce different results.

Platform Comparison Table

Feature GitHub GitLab Reddit Discord Slack
Bold / Italic Yes Yes Yes Yes Different syntax
Tables Yes Yes Yes No No
Task Lists Yes Yes No No No
Footnotes Yes Yes No No No
Code Highlighting Yes Yes Partial Yes No
Diagrams Mermaid Mermaid + PlantUML No No No
Math / LaTeX Yes Yes No No No
Spoiler Tags No No Yes Yes No
Headings h1-h6 h1-h6 h1-h6 h1-h3 No

15. Advanced: HTML in Markdown, Escape Characters, and More

Markdown was designed to be a superset of HTML for block-level elements. This means you can freely use HTML tags when Markdown syntax falls short.

Using HTML in Markdown

You can use any HTML tag in a Markdown document. This is useful for features that Markdown does not natively support:

<!-- Collapsible section -->
<details>
<summary>Click to expand</summary>

This content is hidden by default.

- It supports **Markdown** inside!
- Lists work too.

</details>

<!-- Centered text -->
<div align="center">

# Centered Heading

This paragraph is centered.

</div>

<!-- Keyboard shortcuts -->
Press <kbd>Ctrl</kbd> + <kbd>C</kbd> to copy.

<!-- Subscript and superscript -->
H<sub>2</sub>O is water.
E = mc<sup>2</sup>

<!-- Definition list -->
<dl>
  <dt>Markdown</dt>
  <dd>A lightweight markup language.</dd>
  <dt>HTML</dt>
  <dd>HyperText Markup Language.</dd>
</dl>

<!-- Colored text (GitHub does NOT support this, some other renderers do) -->
<span style="color: red;">Red text</span>

Important: Block-level HTML elements (<div>, <table>, <pre>, <p>, etc.) must be separated from surrounding Markdown content by blank lines, and the opening and closing tags should not be indented. Markdown inside block-level HTML is not processed by default in original Markdown, but many modern parsers (including GitHub) do process it.

Escape Characters

If you want to display a literal character that has special meaning in Markdown, prefix it with a backslash:

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

Characters you can escape:
\   backslash
`   backtick
*   asterisk
_   underscore
{}  curly braces
[]  square brackets
()  parentheses
#   hash mark
+   plus sign
-   minus sign (hyphen)
.   dot
!   exclamation mark
|   pipe

Front Matter

Many static site generators and documentation tools support YAML front matter at the start of Markdown files:

---
title: "My Blog Post"
date: 2026-02-11
author: "Jane Developer"
tags: [markdown, tutorial, guide]
description: "A comprehensive guide to Markdown syntax"
draft: false
---

# My Blog Post

Content starts after the front matter...

Front matter is enclosed in triple dashes (---) and contains metadata in YAML format. Hugo, Jekyll, Astro, Next.js, and many other tools use front matter to configure page properties.

Definition Lists

Some Markdown processors (PHP Markdown Extra, Pandoc, and some others) support definition lists:

Term 1
: Definition for term 1

Term 2
: Definition for term 2
: Alternate definition for term 2

This is not part of CommonMark or GFM, so use HTML <dl>/<dt>/<dd> tags if you need broad compatibility.

Emoji

Most platforms support emoji in Markdown in two ways:

Unicode emoji: Copy and paste directly - Hello!
Shortcodes: :wave: :rocket: :thumbsup: :heart:

Shortcodes work on GitHub, GitLab, Slack, and Discord. Unicode emoji work everywhere.

Automatic Table of Contents

Some parsers support auto-generated table of contents:

GitHub:  No native support (use a TOC generator)
GitLab:  [[_TOC_]]
Pandoc:  --toc flag
VS Code: Markdown All in One extension
Obsidian: Built-in with [[toc]] or outline pane
⚙ Try it: Working with mixed-case text in your documents? Our Text Case Converter can quickly transform text between Title Case, UPPERCASE, lowercase, camelCase, and more.

16. Tips and Best Practices

Knowing the syntax is only the beginning. Here are proven best practices for writing effective Markdown documents.

Document Structure

README Best Practices

For project README files, include these sections (in this order):

# Project Name

Brief one-liner description.

## Features

- Key feature 1
- Key feature 2

## Getting Started

### Prerequisites

- Node.js 18+
- npm or yarn

### Installation

```bash
git clone https://github.com/user/project.git
cd project
npm install
```

### Usage

```bash
npm start
```

## Configuration

Describe config options here.

## Contributing

How to contribute to the project.

## License

MIT License - see [LICENSE](LICENSE) for details.

Writing Effective Documentation

Consistency Guidelines

Linting Your Markdown

Use a Markdown linter to enforce consistency across your project. The most popular option is markdownlint:

# Install markdownlint CLI
npm install -g markdownlint-cli

# Lint a file
markdownlint README.md

# Lint all Markdown files in a directory
markdownlint docs/**/*.md

# Fix auto-fixable issues
markdownlint --fix README.md

You can also use the markdownlint VS Code extension for real-time linting as you write. Configure rules in a .markdownlint.json file:

{
    "MD013": false,
    "MD033": false,
    "MD041": true,
    "MD024": {
        "siblings_only": true
    }
}

Markdown Editors

Some excellent editors with Markdown support include:

Quick Reference Cheat Sheet

Here is every Markdown syntax element at a glance:

Element Markdown Syntax
Heading 1 # Heading
Heading 2 ## Heading
Heading 3 ### Heading
Bold **bold text**
Italic *italic text*
Bold + Italic ***bold and italic***
Strikethrough ~~strikethrough~~
Unordered List - Item
Ordered List 1. Item
Task List - [x] Done / - [ ] Todo
Link [text](url)
Image ![alt](url)
Inline Code `code`
Code Block ```lang ... ```
Blockquote > Quote
Horizontal Rule ---
Table | Col | Col |
Footnote [^ref] ... [^ref]: text
Line Break Two trailing spaces or \
Escape Character \*, \#, \[, etc.

Conclusion

Markdown has earned its place as the universal language for writing on the web. Its genius lies in its simplicity — the syntax is intuitive enough to learn in minutes, yet powerful enough to express complex documentation, technical guides, and rich content.

Start with the basics: headings, emphasis, lists, links, and code blocks. These five elements cover 90% of everyday Markdown writing. Then gradually explore tables, task lists, footnotes, and HTML integration as your needs grow.

The best way to learn Markdown is to use it. Pick a project — whether it is writing a README, taking notes, or starting a blog — and start writing in Markdown today. You will wonder how you ever lived without it.

Related DevToolbox resources: Preview your Markdown in real-time with Markdown Preview, convert Markdown to clean HTML with Markdown to HTML Converter, build tables visually with Markdown Table Generator, and convert HTML back to Markdown with HTML to Markdown Converter.

Related Resources

Markdown Preview
Live preview of your Markdown with rendered output
Markdown to HTML Converter
Convert Markdown to clean, semantic HTML
Markdown Table Generator
Build Markdown tables with a visual editor
HTML to Markdown Converter
Convert HTML back to clean Markdown syntax
Text Case Converter
Transform text between different cases
JSON vs YAML vs TOML
Compare configuration file formats