Markdown Cheat Sheet: GitHub-Flavored Syntax With Examples

Markdown lets you write formatted text that is still perfectly readable as plain text. README files, documentation, notes, chat messages and static sites all use it. This cheat sheet covers the syntax you will actually use, with a focus on GitHub-Flavored Markdown (GFM) — the dialect supported by GitHub, GitLab, most documentation tools and Markdown Preview Editor.

Paste any example below into the online editor and the result appears right next to it.

Headings

Start a line with one to six # characters followed by a space. One # is the page title, ## a section, ### a subsection.

markdown# Page title
## Section
### Subsection
#### Smaller heading

Keep a single # heading per document and don’t skip levels (for example ## straight to ####). The heading structure helps screen readers and search engines understand the page, and most previewers turn it into a table of contents.

Paragraphs and line breaks

A paragraph is one or more lines of text separated by a blank line. A single line break inside a paragraph is ignored — the lines are joined. To force a line break, end the line with two spaces or a backslash:

markdownFirst line with two trailing spaces  
Second line in the same paragraph.

A new paragraph starts after a blank line.

Emphasis

Many editors, including Markdown Preview Editor, also support a few popular extensions: ==highlight==, H~2~O for subscript, x^2^ for superscript and :smile: style emoji shortcodes. These are not part of GFM itself, so check your target platform before relying on them.

Lists

Use -, * or + for bullet lists and numbers for ordered lists. Indent by two to four spaces to nest items.

markdown- Milk
- Bread
  - Whole grain
  - Rye
- Coffee

1. Clone the repository
2. Install dependencies
3. Run the build

Ordered lists don’t need the correct numbers — 1. on every line still renders as 1, 2, 3. Starting with a different number (for example 5.) makes the list start there.

Task lists

Task lists are a GFM extension that turns list items into checkboxes. They work well in READMEs, release plans and meeting notes.

markdown- [x] Write the draft
- [x] Add screenshots
- [ ] Publish the post

Links

markdown[Link text](https://example.com)
[Link with a title](https://example.com "Shown on hover")
<https://example.com>

Read the [installation guide][install].

[install]: https://example.com/docs/install

The last form is a reference link: the URL is defined once at the bottom of the document, which keeps long paragraphs readable. Relative links such as [Setup](docs/setup.md) point to other files in the same project; in Markdown Preview Editor they switch to that document if it is open in another tab.

Images

Images use link syntax with an exclamation mark in front. The text in square brackets is the alternative text — describe the image for people who can’t see it.

markdown![Editor with live preview](images/screenshot.png)
![Logo](https://example.com/logo.svg "Optional title")

When you preview a document that references local images, open the whole folder or drop the images together with the .md file so the previewer can resolve the relative paths.

Code

Inline code uses single backticks. For blocks, wrap the code in triple backticks and add the language name for syntax highlighting:

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

Common language names: js, ts, python, bash, json, yaml, html, css, sql, go, rust, diff. If your code itself contains triple backticks, fence it with four backticks, as in the example above.

Tables

Separate columns with pipes and put a line of dashes under the header. Colons in the separator line set the alignment.

markdown| Feature   | Free | Notes              |
|:----------|:----:|-------------------:|
| Preview   |  ✅  | Updates as you type |
| Export    |  ✅  | HTML, PDF, .md      |

:--- aligns left, :---: centers and ---: aligns right. The columns don’t need to line up in the source — but a good editor keeps them readable. Markdown Preview Editor has a table button in the toolbar that inserts a ready-made template.

Blockquotes and alerts

Prefix lines with > to quote text. GitHub also supports alerts — blockquotes with a special first line that render as colored callouts:

markdown> A regular quote.

> [!NOTE]
> Useful information that users should know.

> [!TIP]
> Helpful advice for doing things better.

> [!WARNING]
> Urgent info that needs immediate attention.

The five alert types are NOTE, TIP, IMPORTANT, WARNING and CAUTION. Use them sparingly: a single alert in a section catches the eye, while five in a row turn into noise.

Footnotes

Footnotes move side remarks out of the main text. The note can be defined anywhere; it is rendered at the end of the document.

markdownMarkdown was created in 2004.[^1]

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

Horizontal rules and escaping

Three or more dashes, asterisks or underscores on their own line make a horizontal rule: ---. Put a blank line before it, otherwise --- under a line of text turns that text into a heading.

To show a character that Markdown would otherwise interpret, escape it with a backslash: \*not italic\*, \# not a heading, \$5 (useful when math is enabled).

Math and diagrams

Two extensions have become standard in technical writing:

• Math — $E = mc^2$ for inline formulas and $$ … $$ for display equations. See the full guide to writing math in Markdown.
• Diagrams — a fenced block with the mermaid language draws flowcharts, sequence diagrams, Gantt charts and more. See Mermaid diagrams in Markdown.

Front matter

Static site generators read metadata from a YAML block at the very top of the file:

yaml---
title: My post
date: 2026-09-27
tags: [markdown, docs]
---

A good previewer hides this block instead of rendering it as text. Markdown Preview Editor does exactly that.

Where to go next

The syntax is only half the job; the other half is seeing the result as you write. Read how to preview Markdown online without uploading your files, and when your document is ready, learn how to convert Markdown to HTML or PDF.