Markdown cheat sheet with examples

The basics in one table

Markdown was designed so that a text file stays readable even before it is converted. A heading looks like a heading because it starts with a hash sign, and a list looks like a list because each line starts with a hyphen. When the text is shown on GitHub, in a notes app or in the editor below, the marks turn into real formatting.

The table covers the marks you will need most often. Copy any example into the editor to see what it produces.

Headings, paragraphs and line breaks

Start a line with one to six hash signs followed by a space to make a heading; the number of hash signs is the level. Most documents use one level 1 heading for the title and level 2 and 3 headings for sections. Leaving out the space after the hash sign is the most common mistake: #Title stays plain text on GitHub.

A paragraph is one or more lines of text separated from the next paragraph by an empty line. A single line break inside a paragraph is ignored when the text is converted, which surprises many people. To force a line break, end the line with two spaces or a backslash. GitHub comments and some chat apps treat every line break as a break; in the editor above, turn on Line breaks like GitHub comments to get the same behavior.

On GitHub and in the editor above, every heading also gets an anchor, a lowercase version of its text with spaces turned into hyphens. A heading called Getting started can be linked with [see setup](#getting-started), which is how tables of contents in README files work.

Lists and task lists

Bulleted lists start each line with a hyphen, an asterisk or a plus sign and a space. Numbered lists use a number and a period. The numbers do not have to be correct: a list written as 1. 1. 1. is still shown as 1, 2, 3, but the first number counts, so a list starting with 3. begins at 3.

To nest a list, indent the inner items so they line up with the text of the item above, which means two spaces under a hyphen and three under 1. Four spaces work in most tools too. An empty line between items makes a loose list with more space between the items; without empty lines the list stays compact.

Task lists are a GitHub addition: write - [ ] for an open task and - [x] for a finished one. They turn into checkboxes. In the editor on this page you can tick a checkbox in the preview and the [ ] in your text changes to [x].

Links, images and references

A link is the visible text in square brackets followed by the address in round brackets: [Anyfeat](https://anyfeat.com). A title that appears when hovering goes in quotes after the address. An address in angle brackets, such as <https://anyfeat.com>, becomes a link showing the address itself, and on GitHub plain addresses starting with https:// or www. are linked automatically.

Images use the same pattern with an exclamation mark in front: . The text in the brackets is the alternative text read by screen readers and shown when the image cannot load, so describe what the picture shows.

For long documents, reference links keep the text readable: write [the guide][1] in the text and put [1]: https://example.com on its own line anywhere in the file. The definition line itself does not appear in the result.

Tables

Tables are part of GitHub Flavored Markdown and work on GitHub, GitLab, most documentation tools and in the editor above, but not in every Markdown app. Write the header cells separated by vertical bars, then a separator row with hyphens, then one line per row:

| Plan | Price |, then |:-|-:|, then | Team | 49 |. Each cell of the separator row needs at least one hyphen; three are common because they are easier to read. A colon on the left side of the hyphens aligns the column to the left, colons on both sides center it, and a colon on the right aligns it to the right, which suits numbers.

The bars do not need to line up, and the outer bars are optional. To put a vertical bar inside a cell, write it as \|. Line breaks inside a cell are not possible in Markdown itself; use <br> where HTML is allowed. The Table button in the editor inserts a ready table with three columns that you can fill in.

Code and quotes

For a short piece of code inside a sentence, wrap it in single backticks: `git status`. For several lines, put three backticks on the line before and after the code. A language name right after the opening backticks, such as js, python or sql, lets GitHub and highlighters color the code; the editor on this page keeps it as a class on the code element in the exported HTML. Lines indented by four spaces are also shown as code.

Everything inside code is shown exactly as typed, so it is the right place for symbols that Markdown would otherwise interpret, such as asterisks and underscores. Outside code, put a backslash in front of a symbol to show it literally: \* gives a plain asterisk.

Quotes start with > and can contain other Markdown, including lists and further quotes with >>. They are used for citations, notes and replies in discussions.

Differences between Markdown apps

The core syntax above works almost everywhere. The differences are in the extensions: GitHub supports tables, task lists, strikethrough, automatic links and alerts written as > [!NOTE]; Obsidian adds links between notes in double square brackets; some tools support footnotes and math formulas. The editor on this page follows GitHub for tables, task lists, strikethrough, automatic links and heading anchors, and does not support footnotes, math or alerts.

Most Markdown apps also accept some HTML. Tags such as <br>, <sub>, <sup>, <kbd> and <details> work in the editor above, while scripts, styles and event attributes are always removed, as they are on GitHub.