Markdown Reference
What is Markdown?
Markdown is a plain-text formatting syntax. You write in an ordinary text file
using a few simple marks — # for a heading, * for emphasis, - for a list — and
a Markdown processor turns it into formatted output (usually HTML).
It was created in 2004 by John Gruber, with input from Aaron Swartz, with one goal: the source should be readable as-is, without looking like it’s been marked up with tags. A Markdown document is legible in any text editor, survives copy-paste, diffs cleanly in version control, and will still open in fifty years.
Because the original description left some cases undefined, several flavours emerged. The most important is CommonMark, a precise specification that most modern tools follow, and GitHub Flavored Markdown (GFM), which adds tables, task lists, strikethrough and autolinking on top of CommonMark. Markdown Reader follows CommonMark + GFM, plus the extensions listed at the end of this page.
Markdown files use the extensions .md or .markdown (Markdown Reader also opens .mdown,
.mkd, .mkdn and .mdwn).
Core syntax
Headings
# Heading 1
## Heading 2
### Heading 3
#### Heading 4
Use one # for the title and work down. Don’t skip levels — it matters for the
contents sidebar and for screen readers.
Paragraphs and line breaks
Separate paragraphs with a blank line. A single newline inside a paragraph is
ignored (the text reflows). To force a line break, end a line with two spaces, or
use a backslash \ at the end of the line.
Emphasis
*italic* or _italic_
**bold** or __bold__
***bold italic***
~~strikethrough~~
Blockquotes
> A quote.
>
> > Quotes can nest.
Lists
- Unordered item
- Another item
- Indent two spaces to nest
- Back to the top level
1. Ordered item
1. The numbers you type don't matter —
1. they're renumbered automatically
- [ ] An unchecked task
- [x] A completed task
Links
[Link text](https://example.com)
[Link with a title](https://example.com 'Shown on hover')
[Reference-style link][ref]
<https://example.com> (an automatic link)
[ref]: https://example.com
In Markdown Reader, a link to another local .md file or to a #heading opens in a new tab.
Images
Always write meaningful alt text — it’s what screen-reader users hear and what
shows if the image fails to load. For a purely decorative image, use empty alt:
.
Code
Inline: wrap with single backticks — `like this`.
Fenced blocks: three backticks, optionally with a language for syntax highlighting:
```js
function hello(name) {
return `Hi, ${name}`;
}
```
Indent by four spaces for a code block without a fence.
Horizontal rule
Three or more -, * or _ on their own line:
---
Tables (GFM)
| Left | Center | Right |
| :--- | :----: | ----: |
| a | b | c |
| d | e | f |
The : positions in the divider row set column alignment. The outer pipes are
optional; the cell widths in the source don’t need to line up.
Escaping
Put a backslash before a character to show it literally: \*not italic\*,
\#not a heading.
HTML
CommonMark allows raw HTML in Markdown. Markdown Reader disables inline HTML for safety — tags are shown as text. Use Markdown syntax or the extensions below instead.
Markdown Reader’s extensions
GitHub-style alerts / callouts
> [!NOTE]
> Useful information the reader should notice.
> [!TIP]
> A helpful suggestion.
> [!IMPORTANT]
> Essential information.
> [!WARNING]
> Something that needs attention.
> [!CAUTION]
> A risk or negative consequence.
Math (KaTeX)
Inline: $E = mc^2$
Display:
$$
\int_0^\infty x^2 \, dx
$$
Diagrams (Mermaid)
```mermaid
flowchart LR
A[Start] --> B{Decision}
B -->|yes| C[Do a thing]
B -->|no| D[Do nothing]
```
Flowcharts, sequence diagrams, Gantt charts, class diagrams and more — see mermaid.js.org.
Footnotes
Here is a claim.[^1]
[^1]: And here is the supporting note.
Definition lists
Term
: The definition of the term.
Another term
: Its definition.
Subscript, superscript, highlight, inserted text
H~2~O and E = mc^2^
==highlighted text==
++inserted text++
Abbreviations
The HTML spec is maintained by the W3C.
*[HTML]: HyperText Markup Language
*[W3C]: World Wide Web Consortium
Hover HTML or W3C in the rendered text to see the expansion.
Emoji shortcodes
:rocket: :sparkles: :white_check_mark:
Automatic heading anchors
Every heading gets an id derived from its text, so you can link to it with
[jump](#the-heading-text) from anywhere in the document.
YAML front matter
A block fenced by --- at the very top of the file holds metadata:
---
title: My Document
author: Ada Lovelace
date: 2026-01-01
tags: [notes, draft]
---
# My Document
Markdown Reader folds this into an info card at the top of the reading view (toggle with
⌘⇧I).
Wikilinks
[[Other Note]]
[[Other Note|shown as this text]]
When a folder is open, [[Other Note]] links to Other Note.md in that folder.
A minimal, complete example
---
title: Release notes
---
# Release notes
## Version 2.0
- New **dark mode**
- Fixed a crash when opening large files [^perf]
> [!TIP]
> Hold `⌥` while clicking to open in the background.
[^perf]: Files over 100 MB now stream instead of loading at once.
See the Markdown Reader Guide for how to use the app itself.