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.

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.

Emphasis: bold, italic and more

Wrap text in symbols to emphasize it:

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

This renders as italic, bold, bold italic and strikethrough. Stick to * for italic and ** for bold — they’re the most widely supported.

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.

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

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 calm writing desk](/images/desk.jpg)

Blockquotes

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

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

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}`
}
```

Horizontal rule

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

---

Escaping characters

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

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.

Task lists

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

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

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.

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.