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).

See full bold guide →

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.

See full code block guide →

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.

See full line break guide →

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.

Collapsible sections:

<details>
<summary>Click to expand</summary>

Hidden content goes here.
Markdown **formatting** works inside.

</details>

Supported by GitHub, GitLab, Obsidian, and MDViewer. The blank line after </summary> is required — without it, Markdown inside renders as plain text.

Highlight Text

Markdown has no native highlight syntax. Two approaches exist, and they work on different platforms:

==highlighted text==

<mark>highlighted text</mark>

==text== works in Obsidian, Bear, and iA Writer. It does not work on GitHub or GitLab — use <mark> there instead. The <mark> tag is the portable option and renders anywhere that allows inline HTML.

Underline

Markdown deliberately omits underline syntax because underlined text looks like a link. Use HTML tags instead:

<u>Underlined text</u>

<ins>Inserted text (also underlined)</ins>

<u> is a visual underline. <ins> means “inserted text” and is semantically correct for edits or additions. Both render as underlined on GitHub, GitLab, VS Code, Obsidian, and MDViewer. Discord is the only platform with native underline syntax: __text__.

See full underline guide →

Subscript & Superscript

H<sub>2</sub>O

E = mc<sup>2</sup>

No native Markdown syntax exists. The HTML <sub> and <sup> tags work on GitHub, GitLab, and most renderers. For complex math, use KaTeX instead: $H_2O$ and $E = mc^2$.

Comments

Hide notes from rendered output. Two methods:

<!-- This is an HTML comment -->

<!-- Multi-line comment:
     hidden from rendered output,
     but visible in page source -->

[//]: # (This comment is stripped from all output)

<!-- --> works everywhere but stays in the HTML source — don’t put sensitive notes there. The [//]: # hack is a link reference that resolves to nothing, so it vanishes from both rendered and source output. In MDX files, use {/* comment */} instead.

Collapsible Sections

Use HTML <details> and <summary> to create expandable content:

<details>
<summary>Click to expand</summary>

Hidden content with **Markdown** formatting.

- Lists work
- So do `code spans`

</details>

The blank line after </summary> is required. Without it, Markdown inside renders as literal text (asterisks instead of bold). This is not a GitHub quirk — it’s the CommonMark HTML-block boundary rule.

For an accordion (multiple sections), stack several <details> blocks. There is no native way to close one when another opens — each section is independent.

Works on GitHub, GitLab, Obsidian, MDViewer, and most static site generators. Does not work on Bitbucket Cloud or Slack.

See full collapsible section guide →

Center & Align Text

Markdown has no alignment syntax. Use HTML:

<div align="center">

Centered text, images, or badges.

</div>

<p align="right">Right-aligned text</p>

The align attribute is the most portable method — it works on GitHub, GitLab, VS Code, Obsidian, and MDViewer. Do not use style="text-align: center" on GitHub — their sanitizer strips inline CSS, and the text silently renders left-aligned. The <center> tag is deprecated and also stripped by GitHub.

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. * Discord uses __text__ for underline (native syntax, not the HTML tag). 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.