Markdown Syntax Guide: Headings, Lists, Links, Tables and More
Markdown is a way to write formatted documents in plain text. Add a few symbols such as #, * or -, and a Markdown viewer turns them into headings, bold text and lists. README files, technical docs, blogs and note apps like Obsidian, Notion and HackMD all use Markdown, so once you learn it you can use it everywhere.
This guide covers the syntax you'll use every day, with an example for each. When you're done, drag your .md file into the Moread online Markdown viewer to see the result.
Headings
Start a line with #. The number of # characters sets the level, from # (largest) to ######. Leave a space after the last #.
# Document title
## Chapter one
### Section 1.1
Most documents use a single # title and ## / ### for structure. Moread builds the outline on the right from your headings automatically.
Paragraphs and line breaks
Consecutive lines belong to the same paragraph. Leave a blank line to start a new one. To break a line without starting a new paragraph, end it with two spaces.
Bold, italic and strikethrough
**bold text**
*italic text*
~~strikethrough~~
`inline code`
Lists
Unordered lists start with -, * or +. Ordered lists use a number and a period. Indent two to four spaces to nest items.
- Apples
- Bananas
- Plantains (nested)
1. Open the file
2. Pick a theme
3. Start reading
Task lists
GitHub Flavored Markdown (GFM) adds checkboxes, which are great for to-do lists:
- [x] Write the outline
- [ ] Add examples
- [ ] Proofread
Links and images
[Moread](https://md-viewer.amemori.win/)

An image is a link with an exclamation mark in front. The alt text appears when the image can't load and helps screen readers and search engines understand it. In Moread, use Open folder so images referenced by your document display correctly.
Blockquotes
Start a line with > for quotes, notes or key takeaways:
> Space lets words breathe.
Code blocks
Wrap code in three backticks and add the language name for syntax highlighting:
```javascript
const total = [1, 2, 3].reduce((a, b) => a + b, 0);
console.log(total);
```
Moread highlights hundreds of languages. JavaScript blocks even get a ▷ Run button that executes the code in a secure sandbox.
Tables
Separate columns with | and put a --- row under the header. Colons control alignment.
| Feature | Shortcut | Notes |
| :--- | :---: | ---: |
| Open file | Ctrl O | Choose a .md file |
| Find | Ctrl F | Search the document |
:--- aligns left, :---: centers and ---: aligns right.
Horizontal rules and escaping
Three or more - or * on a line create a horizontal rule. To show a literal symbol such as * or #, put a backslash in front of it: \*not italic\*.
Beyond the basics: diagrams and math
Standard Markdown has no diagrams or equations, but two popular extensions fill the gap, and Moread supports both:
- Mermaid diagrams – draw flowcharts, sequence diagrams and Gantt charts with text. See the Mermaid diagram guide.
- LaTeX math – write equations with
$...$and$$...$$. See LaTeX math in Markdown.
Markdown cheat sheet
| Result | Syntax |
|---|---|
| Heading | # Heading |
| Bold | **text** |
| Italic | *text* |
| Strikethrough | ~~text~~ |
| Link | [text](url) |
| Image |  |
| Bulleted list | - item |
| Numbered list | 1. item |
| Task list | - [ ] todo |
| Blockquote | > quote |
| Inline code | `code` |
| Horizontal rule | --- |
Finished writing? Drop your file into Moread to see it typeset, or save it as a PDF to share.