Markdown is a way to write formatted text using plain characters. You type # Title and a Markdown renderer shows a heading. It is used for README files, documentation, notes, blog posts, and chat messages because the source stays readable even before it is rendered.

To follow along, open the Markdown Preview editor and type the examples. The preview updates as you write, so you can see what each character does.

Headings

Put one to six # characters at the start of a line, followed by a space.

# Heading 1
## Heading 2
### Heading 3

The space after the # matters. #Heading without a space is shown as plain text in most renderers. Use one Heading 1 per document, and keep levels in order instead of jumping from 1 to 4.

Paragraphs and line breaks

A blank line separates paragraphs. A single line break inside a paragraph is usually joined into the same paragraph. To force a line break, end the line with two spaces, or use a backslash at the end of the line in renderers that support it. If your line breaks disappear, this is the reason.

Emphasis

*italic* or _italic_
**bold** or __bold__
***bold and italic***
~~strikethrough~~

Strikethrough is a common extension and may not work in every renderer.

Lists

Unordered lists use -, *, or +. Ordered lists use numbers followed by a period.

- Apples
- Oranges
  - Indent two or four spaces for a nested item

1. First step
2. Second step
3. Third step

For ordered lists, the numbers you type do not have to be consecutive in most renderers, because the output is renumbered. Nested items must be indented consistently, otherwise they become part of the parent line or a new list.

Links and images

[QuickToolsBox](https://quicktoolsbox.com/)
![A description of the image](photo.jpg)

The text in square brackets is what readers see. The address in parentheses is where it goes. An image uses the same pattern with an exclamation mark at the start, and the bracketed text becomes the alt text that screen readers and search engines use, so write something meaningful.

Code

Wrap short code in single backticks, like npm install. For several lines, use a fenced block with three backticks before and after, and optionally the language name after the first fence.

const total = prices.reduce((a, b) => a + b, 0);

Inside a code block, Markdown characters are not interpreted, which is what makes it useful for showing Markdown itself.

Quotes and horizontal rules

> A quoted line.
> Quotes can run across several lines.

---

Three or more hyphens on their own line create a horizontal rule. Leave a blank line above --- so it is not mistaken for the underline of a heading in some renderers.

Tables

Many renderers, including GitHub, support tables written with pipes and hyphens.

| Tool | Purpose |
|------|---------|
| Base64 | Encode text |
| JSON | Format data |

The second row of hyphens is required. Tables are not part of the original Markdown specification, so a few simple renderers will show them as plain text.

Task lists

GitHub-style Markdown supports checkboxes in lists:

- [x] Write the draft
- [ ] Proofread

Escaping special characters

If you want a literal * or # instead of formatting, put a backslash before it, such as \*not italic\*. This is handy for things like asterisks in math or hash signs at the start of a line.

Markdown flavors

Markdown has no single official version. The original from 2004 left many details open, which led to differences between tools. CommonMark is a strict specification that clears up the ambiguity, and GitHub Flavored Markdown builds on it with tables, task lists, and strikethrough. If something looks right in one place and wrong in another, the renderers are probably following different rules. Test where it will actually be published.

Common mistakes

  • No space after the symbol. #Title, -item, and 1.item often fail. Add the space.
  • Missing blank lines. A list, code block, or table that runs straight on from a paragraph may not be recognized. Put a blank line before it.
  • Mixed indentation. Mixing tabs and spaces in nested lists gives unpredictable results. Use spaces.
  • Raw HTML. Some platforms strip or sanitize HTML for security, so do not rely on it for important formatting.
  • Unescaped underscores. A name like snake_case_name can turn into italics in some renderers. Put it in backticks.

From Markdown to HTML

Markdown is converted to HTML before it appears on a web page. In the editor you can switch to the HTML view to see the exact output, and copy it into a CMS, an email template, or a static site. This is also a good way to learn what each piece of syntax produces.