Headings

# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6

Always put a space after the #. Most Markdown processors require it.

Alternative syntax for H1 and H2:

Heading 1
=========

Heading 2
---------

Text Formatting

**Bold text**
*Italic text*
***Bold and italic***
~~Strikethrough~~

You can also use underscores: _italic_ and __bold__. Asterisks are more common and work in more contexts (mid-word emphasis).

Links

[Link text](https://example.com)
[Link with title](https://example.com "Hover text")
<https://example.com>

Reference-style links for cleaner source:

[Link text][ref]

[ref]: https://example.com "Optional title"

Images

![Alt text](image.png)
![Alt text](image.png "Optional title")

To resize images, you need HTML:

<img src="image.png" alt="Alt text" width="400">

Lists

Unordered:

- Item one
- Item two
  - Nested item
  - Another nested
- Item three

Ordered:

1. First
2. Second
3. Third

Ordered lists auto-number — you can use 1. for every item and the renderer will count correctly.

Task lists (GitHub Flavored):

- [x] Done
- [ ] Not done
- [ ] Also not done

Blockquotes

> This is a blockquote.
>
> It can span multiple lines.
>
> > Nested blockquotes work too.

Code

Inline code:

Use `backticks` for inline code.

Code blocks with syntax highlighting:

function greet(name) {
    return `Hello, ${name}!`;
}

```javascript
function greet(name) {
    return `Hello, ${name}!`;
}
```

Common language identifiers: javascript, python, bash, json, html, css, swift, go, rust, sql, yaml, markdown.

Tables

| Header 1 | Header 2 | Header 3 |
|----------|----------|----------|
| Cell 1   | Cell 2   | Cell 3   |
| Cell 4   | Cell 5   | Cell 6   |

Alignment:

| Left     | Center   | Right    |
|:---------|:--------:|---------:|
| text     | text     | 123      |

For a deep dive, see our full guide: Markdown Table Syntax.

Horizontal Rules

---

All three syntaxes produce the same line: ---, ***, ___. Use --- — it’s the most common convention.

Line Breaks

End a line with two spaces to create a line break (soft return):

First line··
Second line (same paragraph)

The ·· above represents two trailing spaces. Or use a blank line for a new paragraph:

First paragraph.

Second paragraph.

Escaping Characters

Use a backslash to display literal Markdown characters:

\* Not italic \*
\# Not a heading
\[Not a link\]
\| Not a table pipe

Characters you can escape: \ ` * _ {} [] () # + - . ! |

GitHub Flavored Markdown (GFM) Extras

These features are supported by GitHub, GitLab, and most modern Markdown apps:

Autolinked URLs:

https://example.com

Renders as a clickable link without bracket syntax.

Footnotes:

Here is a statement[^1].

[^1]: This is the footnote text.

Emoji (GitHub):

:thumbsup: :rocket: :warning:

Alerts (GitHub, new):

> [!NOTE]
> Useful information.

> [!WARNING]
> Important warning.

Extended Syntax

Some Markdown renderers support additional features beyond GFM:

Mermaid diagrams:

```mermaid
graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Do thing]
    B -->|No| D[Don't]
```

Supported by GitHub, GitLab, Obsidian, and MDViewer.

Math (KaTeX/LaTeX):

Inline: $E = mc^2$

Display:
$$
\sum_{i=1}^{n} x_i = x_1 + x_2 + \cdots + x_n
$$

Supported by GitHub, Obsidian, Jupyter, and MDViewer.

Definition lists:

Term
: Definition text

Supported by some processors (PHP Markdown Extra, Pandoc). Not standard GFM.

Quick Reference Table

Try MDViewer

Writing Markdown is easy. Seeing how it renders without pushing to GitHub or opening a heavy editor — that’s where a dedicated viewer helps. Try the online Markdown viewer for a quick check, or grab the full app. MDViewer is a native macOS app that renders everything on this page — tables, code blocks, Mermaid diagrams, KaTeX math. Double-click any .md file in Finder and see it rendered instantly. Currently free for early adopters.

Requires macOS 13.0 or later. Intel and Apple Silicon.