The Complete Markdown Guide

Markdown is a lightweight way to write formatted text using plain characters you already know — a # for a heading, an * for a bullet, ** around a word to make it bold. You write in plain text and it renders as a clean, structured document. This guide is a complete reference to Markdown syntax, from the basics you’ll use every day to the extended features supported by modern editors. Keep it open as a cheat sheet, or read it top to bottom once and you’ll know practically everything.

If you’re brand new to it, start with what Markdown is and why it’s worth learning, then come back here for the syntax.

Try it right now

Every example in this guide is live. Type in the left panel and the right one updates as you go — nothing to install, nothing to sign up for. Start here:

# My first document

Markdown is **plain text** that renders as a *clean* document.

- Edit anything on the left
- Watch the right side update as you type
- Delete this line and write your own

> Change this quote. Or add a `## heading` above it.

| It works | in tables |
|----------|-----------|
| and in   | lists     |

Nothing you type here is saved or sent anywhere — it lives in your browser and disappears when you close the tab.

One guide per element

This page is the overview. Each element also has its own page, with a live editor focused on that one thing and the edge cases that catch people out:

• Headings — the six levels, anchor links, one H1 per document
• Bold and italic — asterisks vs underscores, strikethrough
• Line breaks and paragraphs — why pressing Enter once does nothing
• Lists — nesting, numbering, tight vs loose
• Links — inline, reference and anchor links
• Images — alt text, sizing, clickable images
• Code blocks — fences, languages, showing backticks
• Tables — alignment, escaping pipes, the limits
• Task lists — checkboxes and where they are clickable
• Blockquotes — nesting, callouts, multi-paragraph quotes
• Horizontal rules — dividers and the blank-line trap
• Escaping characters — the backslash and when to skip it
• Footnotes — labels, definitions and where they work

The basics

Markdown’s original syntax, defined by John Gruber in 2004, covers the elements you need for most writing. Everything below is universal — it works in virtually every Markdown editor and on every platform.

Headings

Use # symbols at the start of a line. The number of # sets the level, from # (the largest, an <h1>) down to ###### (an <h6>).

# Heading level 1
## Heading level 2
### Heading level 3
#### Heading level 4

Leave a blank line before and after a heading so every editor parses it correctly, and use a single # only once per document — it’s the title.

→ Full guide to headings — anchor links, the Setext style and why one H1.

Emphasis: bold, italic and more

Wrap text in symbols to emphasize it:

*italic* or _italic_

**bold** or __bold__

***bold italic***

~~strikethrough~~

Stick to * for italic and ** for bold — they’re the most widely supported. Note the blank lines between those examples: without them Markdown would join all four into a single paragraph, which is the single most common surprise for newcomers. Delete one in the panel above and watch it happen.

→ Full guide to emphasis — asterisks vs underscores and intra-word emphasis.

Paragraphs and line breaks

A blank line starts a new paragraph. A single newline does not — Markdown treats it as a space and joins the lines, which is the first thing that surprises everyone.

These two lines
become one paragraph.

A blank line above starts a new one.

Two trailing spaces  
force a break inside a paragraph.

→ Full guide to line breaks — the two-spaces trap, the backslash, and how GitHub differs.

Lists

Unordered lists use -, * or +. Ordered lists use numbers followed by a period. Indent by two spaces to nest.

- First item
- Second item
  - Nested item
  - Another nested item
- Third item

1. Step one
2. Step two
3. Step three

You don’t need to number ordered lists correctly — writing 1. on every line still renders as 1, 2, 3. That makes reordering painless.

→ Full guide to lists — nesting, tight vs loose lists and numbering.

Links

Put the link text in square brackets and the URL in parentheses right after:

[Visit the Markdown guide](https://inkiostro.app/markdown-guide)

You can also add a title: [hover me](https://inkiostro.app "Inkiostro")

Bare URLs like https://inkiostro.app are auto-linked in most editors. For repeated links, use reference style to keep paragraphs readable:

Read the [guide][mdg] and the [PDF tips][pdf].

[mdg]: https://inkiostro.app/markdown-guide
[pdf]: https://inkiostro.app/markdown-to-pdf

→ Full guide to links — reference links, anchors and awkward URLs.

Images

Images are links with an exclamation mark in front. The bracketed text is the alt text — always write it, both for accessibility and SEO.

![A sheet of paper and a pen on a desk](/images/desk.jpg)

→ Full guide to images — alt text, sizing and clickable images.

Blockquotes

Start a line with >. Quotes can span multiple paragraphs and can contain other Markdown.

> Writing is thinking made visible.
>
> — someone wise

→ Full guide to blockquotes — nesting, multi-paragraph quotes and callouts.

Code

For a short snippet inside a sentence, wrap it in single backticks: `like this`. For a whole block, fence it with three backticks. Add a language name after the opening fence for syntax highlighting:

```js
function hello(name) {
  return `Hi, ${name}`
}
```

function hello(name) {
  return `Hi, ${name}`
}

→ Full guide to code — fences, languages and showing backticks.

Horizontal rule

Three or more dashes, asterisks or underscores on their own line create a divider:

---

→ Full guide to horizontal rules — the blank-line trap and front matter.

Escaping characters

To show a Markdown character literally, put a backslash before it. \*not italic\* renders as *not italic*.

→ Full guide to escaping characters — the full list and when you can skip it.

Extended syntax

Beyond the original spec, most modern tools support extensions — largely popularized by GitHub Flavored Markdown (GFM). These are the ones worth knowing.

Tables

Build a table with pipes | and a divider row of dashes. Colons in the divider set column alignment:

| Feature   | Free | Pro |
|:----------|:----:|----:|
| Preview   |  ✓   |  ✓  |
| Export    |  ✓   |  ✓  |
| Focus mode|  —   |  ✓  |

The pipes don’t need to line up in your source — an editor with a live preview renders it neatly either way.

→ Full guide to tables — alignment, escaping pipes and what tables cannot do.

Task lists

Checkboxes are a list item with [ ] or [x]:

- [x] Write the draft
- [ ] Edit it
- [ ] Export to PDF

→ Full guide to task lists — nesting and where the boxes are clickable.

Fenced code with language

As shown above, naming the language after the opening fence (```python, ```bash, ```json) turns on syntax highlighting in the preview and in exports.

Footnotes

Add a reference in the text and define it anywhere in the document:

Markdown was created in 2004.[^1]

[^1]: By John Gruber, with input from Aaron Swartz.

→ Full guide to footnotes — labels, multi-paragraph notes and support.

Automatic links and strikethrough

GFM auto-links raw URLs and email addresses, and ~~text~~ renders as strikethrough — both shown earlier.

CommonMark, GFM and other flavors

Because Gruber’s original description left some edge cases ambiguous, CommonMark was created to define Markdown precisely. Most modern editors follow CommonMark and then add extensions. GitHub Flavored Markdown is CommonMark plus tables, task lists, strikethrough and auto-links. Some tools go further with LaTeX math and diagrams — see writing math in Markdown and diagrams from plain text.

In practice: learn the basics and GFM extensions above and your documents will render correctly almost everywhere.

Markdown cheat sheet

Everything on one screen — bookmark this table.

Tips for writing better Markdown

• Leave blank lines between block elements (headings, paragraphs, lists). It’s the single most common fix for “why won’t this render?”.
• Use a live preview. Seeing the formatted result as you type catches mistakes instantly and lets you focus on the words.
• Keep it portable. Prefer the universal syntax and the GFM extensions above; avoid tool-specific quirks so your files open cleanly anywhere.
• Write alt text on every image.
• One # per file. Treat it as the document title and structure the rest with ## and ###.

A good editor makes all of this effortless — a formatting toolbar inserts the right symbols, syntax highlighting keeps long files readable, and a live preview shows the result. Inkiostro does exactly that on Mac, iPad and iPhone, and even keeps a built-in cheat sheet one keystroke away.

FAQ

Is Markdown hard to learn?

No. You can learn the essentials — headings, bold, italic, lists and links — in a couple of minutes, and they cover most everyday writing. The rest you pick up as you need it. Markdown was specifically designed to be readable as plain text, so even the raw syntax is easy to follow.

What’s the difference between Markdown and CommonMark?

Markdown is the original 2004 syntax by John Gruber. CommonMark is a strict, unambiguous specification of that syntax created so every editor renders the same input identically. Most modern tools follow CommonMark and add extensions like tables and task lists on top.

Can I use Markdown for more than notes?

Yes. Markdown is used for documentation, blog posts, books, README files, technical papers with math, and more. With extensions you can add tables, footnotes, LaTeX equations and diagrams, then export to PDF, HTML or EPUB — so a plain-text note becomes a polished document.

How do I convert Markdown to a PDF or Word document?

Use a Markdown editor with export. Inkiostro exports to PDF, HTML, TXT and Markdown (and EPUB on Mac) with control over headers, footers and margins — see the Markdown to PDF guide for a step-by-step walkthrough.

Which characters do I need to escape in Markdown?

Put a backslash before any character you want shown literally instead of interpreted — most often *, _, #, `, [, ], (, ) and \. For example, \*star\* displays the asterisks instead of italicizing the word.