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

Where Does Markdown Work?

Not every platform supports every Markdown feature. This table shows what renders where — useful when you're writing for a specific audience.

Ext. = requires an extension. Slack and Discord support a limited subset of Markdown — bold, italic, code, links, and lists — but not full GFM features like tables or headings.

When writing Markdown that needs to work everywhere, stick to the basics: headings, bold, italic, links, lists, and code blocks. For tables, Mermaid diagrams, and math, verify that your target platform supports them.

Common Mistakes

These are the formatting issues that trip up both beginners and experienced writers.

Missing blank line before a list

Most Markdown processors require a blank line before a list. Without it, the list may render as plain text:

Items to buy:
- Milk
- Bread

Items to buy:

- Milk
- Bread

The second version (with a blank line) works reliably across all renderers.

No space after #

#Heading is not a heading — you need # Heading with a space. Some processors are forgiving, but GitHub and the spec require the space.

Nested list indentation

Nested items must be indented by exactly 2 or 4 spaces (depending on the processor). Tabs may or may not work. GitHub uses 2 spaces:

- Parent item
  - Child item (2 spaces)
    - Grandchild (4 spaces)

Forgetting to close a code fence

If you open a code block with ``` but forget the closing ```, everything after it becomes code. This is easy to miss in long documents.

Links inside angle brackets

Raw URLs work on GitHub (https://example.com auto-links), but not in all Markdown processors. For maximum compatibility, use the full link syntax: [text](url).

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. Lite is free; Pro adds editing, Git history, and PDF export for $9.99 one-time.

Requires macOS 13.0 or later. Intel and Apple Silicon.