Markdown syntax guide
A clear cheat sheet for everyday Markdown. Each block shows the syntax and the result you get.
What is Markdown?
Markdown is a lightweight way to add formatting to plain text. Instead of buttons and menus, you use a few simple symbols, like # for a heading or * for emphasis, that stay readable even as raw text.
Created by John Gruber and Aaron Swartz in 2004, it has become the standard for READMEs, documentation, notes, and sites like GitHub and Reddit. Because it is just text, your writing stays portable and readable anywhere.
This guide covers the syntax you will use most. Open any example in Markdown Peek and press the spacebar to flip between the source and the rendered result.
Headings
Start a line with one to six # characters. More hashes mean a smaller, deeper heading.
Markdown
# Heading 1 ## Heading 2 ### Heading 3 #### Heading 4
Result
Heading 1
Heading 2
Heading 3
Heading 4
Bold, italic, and more
Wrap text in symbols to emphasize it. Combine them freely.
Markdown
**Bold text** *Italic text* ***Bold and italic*** ~~Strikethrough~~ `Inline code`
Result
Bold text
Italic text
Bold and italic
Strikethrough
Inline code
Lists
Use a dash, asterisk, or plus for bullets, and numbers for ordered lists. Indent to nest.
Markdown
- First item - Second item - Nested item - Third item 1. Step one 2. Step two
Result
- First item
- Second item
- Nested item
- Third item
- Step one
- Step two
Links
Put the visible text in square brackets and the address in parentheses. A plain web or email address becomes a link on its own.
Markdown
[Markdown Peek](https://markdownpeek.com) https://markdownpeek.com
Images
An image is a link with a leading exclamation mark. The text in brackets is the alt text.
Markdown
Result
Blockquotes
Start a line with > to quote it. Add another > to nest a quote inside a quote.
Markdown
> A quote worth remembering. > > > And a nested one.
Result
A quote worth remembering.
And a nested one.
Code
Wrap inline code in single backticks, and whole blocks in triple backticks. Add a language name and Markdown Peek colors the code, like GitHub.
Markdown
Use `backticks` for inline code.
```js
function hi() {
console.log("Hello");
}
```Result
Use backticks for inline code.
function hi() {
console.log("Hello");
}Tables
Separate columns with pipes and underline the header row with dashes. Colons set the alignment.
Markdown
| Feature | Supported | |---------|:---------:| | Tables | Yes | | Code | Yes |
Result
| Feature | Supported |
|---|---|
| Tables | Yes |
| Code | Yes |
Horizontal rules
Three or more dashes, asterisks, or underscores on their own line draw a divider.
Markdown
Above the line. --- Below the line.
Result
Above the line.
Below the line.
Task lists
A list item with [ ] is an open task, and [x] is a done one.
Markdown
- [x] Read the guide - [ ] Set as default app
Result
Callouts
Start a blockquote with [!NOTE], [!TIP], [!IMPORTANT], [!WARNING], or [!CAUTION] to turn it into a colored callout, like on GitHub.
Markdown
> [!NOTE] > Useful to know, even when skimming. > [!WARNING] > Needs attention right away.
Result
Note
Useful to know, even when skimming.
Warning
Needs attention right away.
Footnotes
Add [^1] where a note belongs and write the note anywhere below. Markdown Peek numbers the notes, lists them at the end, and links back to where you were.
Front matter
Key and value pairs between two --- lines at the very top of a file, as in blog posts and agent skills, show as a neat table.
Markdown
--- title: Lofoten author: Sam tags: travel --- # Five nights in March
Result
| title | author | tags |
|---|---|---|
| Lofoten | Sam | travel |
Five nights in March
Escaping characters
Put a backslash before a symbol to show it literally instead of as formatting.
Markdown
\*Not italic\* \# Not a heading
Result
*Not italic*
# Not a heading
Math with LaTeX
Wrap LaTeX in single dollar signs for math inside a sentence, or double dollar signs for a formula on its own line. Markdown Peek renders both, offline.
Markdown
Inline math like $E = mc^2$ works in a sentence. $$ a^2 + b^2 = c^2 $$
Result
Inline math like E = mc2 works in a sentence.
a2 + b2 = c2
Diagrams with Mermaid
Open a fenced code block with mermaid and describe a flowchart or sequence diagram in plain text. Markdown Peek draws it for you, in light or dark mode.
Markdown
```mermaid flowchart LR A[Write] --> B[Preview] B --> C[Share] ```
Result
Read Markdown beautifully on your Mac
Markdown Peek renders any .md file in clean GitHub style, with code in color, Quick Look in Finder, and save to PDF. Free on the Mac App Store.
