Markdown has a small vocabulary, and most documents use fewer than a dozen elements. This cheat sheet covers the ones you will actually reach for, with notes on the spots where people commonly go wrong. Examples use the CommonMark specification and GitHub Flavored Markdown (GFM) extensions; where something is an extension, it says so.
Headings
Start a line with one to six # characters followed by a space:
# Heading 1
## Heading 2
### Heading 3
The space after the # matters. #Heading is treated as plain text by CommonMark-compliant parsers, although some older tools accept it. Use one level-1 heading per document and do not skip levels, which helps both readers and screen readers.
Emphasis
*italic*or_italic_**bold**or__bold__***bold italic***~~strikethrough~~(GFM extension)
Underscores inside a word, such as snake_case_name, are usually left alone by modern parsers, but asterisks are the safer choice for emphasis in the middle of a word.
Lists
Unordered lists use -, * or +. Ordered lists use a number followed by a period:
- First item
- Second item
- Nested item (indent by two or four spaces)
1. Step one
2. Step two
Ordered lists renumber themselves when rendered, so you can write 1. on every line and let the renderer count. Leave a blank line before a list that follows a paragraph; some parsers will not start the list otherwise.
Links and images
[link text](https://example.com)
[link with title](https://example.com "Tooltip")
An image is a link with a ! in front. Always write meaningful alt text, because it is what screen readers announce and what appears when the image fails to load. More detail is in our guide to Markdown links and images.
Code
Wrap inline code in single backticks. For a block, use three backticks on their own lines, optionally followed by a language name for syntax highlighting:
```json
{ "name": "docento" }
```
The older style, indenting every line by four spaces, also creates a code block but cannot carry a language name.
Block quotes
Start each line with >:
> A quoted passage.
> It can span several lines.
Horizontal rule
Three or more hyphens, asterisks or underscores on their own line: ---. Note that a line of text directly followed by --- turns the text into a level-2 heading in the older "setext" style, so put a blank line between them.
Tables (GFM extension)
| Name | Role |
|-------|--------|
| Ada | Admin |
| Linus | Editor |
Tables are not part of core CommonMark. See how to write Markdown tables for alignment and escaping.
Task lists (GFM extension)
- [x] Write the draft
- [ ] Proofread
Renderers that support task lists show checkboxes. Others show the literal brackets.
Line breaks and paragraphs
A blank line starts a new paragraph. A single newline inside a paragraph is normally treated as a space, not a break. To force a line break, end the line with two spaces or a backslash. This catches many people out when a poem or address collapses into one line.
Escaping
To show a literal special character, put a backslash before it: \*not italic\*. Characters that can need escaping include \, `, *, _, #, [, ], (, ), +, -, . and !, but only where they would otherwise be read as formatting.
Try it as you type
The fastest way to learn the syntax is to see it rendered. Open Docento's Text & Markdown Editor, type an element, and switch to Preview. The formatting toolbar inserts bold, italics, headings, lists, quotes, code and links for you, and shows which markers it adds.
Takeaway
Headings, emphasis, lists, links, code and quotes cover most documents. Remember the blank line before lists and the space after #, and check the preview before you share.
