Markdown cheatsheet: a fast, practical tutorial

Most documentation starts as a plain text file with a few asterisks and hash signs. That file is usually Markdown. It is not the only way to write for the web, but it is the default for READMEs, issue trackers, chatbots, and static sites because the source is readable before it is rendered.

This post is a fast, practical tutorial. It assumes you have ten minutes and a text editor. No installation required.

What Markdown is

Markdown is a lightweight markup syntax. John Gruber published the original spec in 2004 with one goal: a format that looks good in plain text and converts cleanly to HTML. Since then it has become the input format for GitHub, Obsidian, Notion, many static site generators, and most large language model outputs.

The core idea is simple. You mark structure with punctuation instead of tags:

# This is a heading

This is a paragraph.

- This is a list item
- This is another one

A parser turns that into HTML. Different parsers support different extensions, which is where the standards come in.

Markdown standards matter

Markdown has no single official standard. Gruber's original spec leaves gaps, so different tools filled them in incompatible ways. If you write a table in one app and paste it into another, it may break. Know which flavor you are targeting.

CommonMark. A strict, well-tested specification started in 2014. It defines core syntax precisely. If you want portability, write CommonMark.
GitHub Flavored Markdown (GFM). Adds tables, task lists, strikethrough, fenced code blocks, and autolinks. This is what you see in GitHub READMEs and issue comments.
Pandoc Markdown. Adds citations, footnotes, definition lists, subscripts, superscripts, and math. Common in academic writing.
Obsidian / Quarto / MDX. These add wiki links, callouts, executable code cells, or embedded components. They are powerful but not portable.

For most daily work, GFM is the safest target. For long-form documentation that may move between tools, CommonMark plus a documented extension set is better.

Markdown basics

Headings

Use one to six hash signs. One is the largest.

# Heading 1

## Heading 2

### Heading 3

Paragraphs and line breaks

Separate paragraphs with a blank line. End a line with two spaces or a backslash to force a line break.

This is the first paragraph.

This is the second.

Emphasis

_italic_ or _italic_
**bold** or **bold**
**_bold and italic_**
~~strikethrough~~ (GFM only)

Lists

Unordered lists use -, *, or +:

- Item one
- Item two
  - Nested item

Ordered lists use numbers:

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

The numbers do not have to be correct. Markdown renumbers them on render. Still, use sequential numbers so the source is readable.

Links and images

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

For internal links, use relative paths:

[Convert Markdown to PDF](/tools/markdown-to-pdf)

Code

Inline code uses single backticks: `console.log("hi")`.

Code blocks use triple backticks:

```python
def hello():
    return "hello"
```


Add a language identifier after the opening backticks so syntax highlighters can do their job.

## Common tricks and examples

### Blockquotes

```markdown
> This is a quote.
> It can span lines.

You can nest them:

> Outer quote
>
> > Nested quote

Horizontal rules

---

Use three or more dashes, asterisks, or underscores on a line by themselves.

Task lists

GFM supports checkboxes:

- [x] Write the draft
- [ ] Review the tables
- [ ] Publish the post

They render as disabled checkboxes in HTML. Do not use them as a substitute for real form inputs.

Escaping characters

Prefix Markdown characters with a backslash when you want them literally:

\*not italic\*
\# not a heading

Advanced tricks and examples

Tables

Tables are a GFM extension, not part of the original Markdown spec.

| Feature    | CommonMark | GFM |
| ---------- | ---------- | --- |
| Tables     | No         | Yes |
| Task lists | No         | Yes |

Alignment is optional:

| Left | Center | Right |
| :--- | :----: | ----: |
| A    |   B    |     C |

Keep tables simple. Nested tables, row spans, and column spans are not standard and often fail.

Footnotes

Pandoc and some GFM parsers support footnotes:

Here is a statement.[^1]

[^1]: This is the footnote text.

If you need footnotes in a rendered PDF, use a converter that supports Pandoc-style syntax or embed them manually.

Math

Pandoc and many modern editors support LaTeX math:

Inline math: $E = mc^2$

Block math:

$$
\int_a^b f(x) \, dx = F(b) - F(a)
$$

Math rendering depends on the parser and the output format. HTML usually needs MathJax or KaTeX. PDF converters often need a LaTeX backend.

Definition lists

Another Pandoc extension:

Term
: Definition of the term.

Another term
: Another definition.

HTML inside Markdown

When Markdown falls short, you can drop into HTML:

<p style="color: red;">This is red text.</p>

This works for layout, embedded video, or attributes that Markdown does not support. It also kills portability, so use it sparingly.

When to convert Markdown

Markdown is great for writing and version control. It is not great for final documents that must look identical everywhere. That is why converters exist.

If you have a Markdown draft that needs to become a shareable PDF, use the Markdown to PDF converter. It runs in the browser, so your file never leaves your machine.

If you have a PDF and need editable Markdown, use the PDF to Markdown converter. It extracts headings, lists, and paragraphs without uploading anything to a server.