Markdown Guide

What is Markdown?

Markdown is a lightweight markup language that uses plain text formatting to produce structured HTML output. Created by John Gruber in 2004, it was designed to be readable as-is — the syntax looks like natural writing conventions rather than code tags.

Today Markdown is used everywhere: GitHub READMEs, documentation sites, note-taking apps (Notion, Obsidian), comment systems, and content management platforms. Learning the syntax takes under an hour and is one of the highest-return writing skills for developers and writers alike.

Headings

Use # symbols followed by a space. One # = H1, two = H2, up to six = H6.

# Heading 1
## Heading 2
### Heading 3
#### Heading 4

Emphasis

*italic* or _italic_
**bold** or __bold__
***bold italic***
~~strikethrough~~

Lists

<!-- Unordered (use -, *, or +) -->
- First item
- Second item
  - Nested item (indent 2 spaces)

<!-- Ordered -->
1. First item
2. Second item
3. Third item

<!-- Task list (GitHub Flavored Markdown) -->
- [x] Completed task
- [ ] Incomplete task

Links and images

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

<!-- Image -->
![Alt text](https://example.com/image.png)
![Alt text](./local-image.png "Optional title")

<!-- Reference-style link -->
[Link text][ref]
[ref]: https://example.com

Code

<!-- Inline code (backticks) -->
Use the `console.log()` function.

<!-- Fenced code block with language -->
```javascript
function greet(name) {
  return `Hello, ${name}!`;
}
```

```python
def greet(name):
    return f"Hello, {name}!"
```

The language identifier after the opening backticks enables syntax highlighting on platforms that support it (GitHub, VS Code, most documentation tools).

Blockquotes and horizontal rules

<!-- Blockquote -->
> This is a blockquote.
> It can span multiple lines.
>
> Even multiple paragraphs.

<!-- Horizontal rule (three or more dashes, asterisks, or underscores) -->
---

Tables (GitHub Flavored Markdown)

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Cell     | Cell     | Cell     |
| Cell     | Cell     | Cell     |

<!-- Alignment using colons in the separator row -->
| Left     | Center   | Right    |
|:---------|:--------:|--------:|
| text     | text     | text     |

Tables are a GitHub Flavored Markdown (GFM) extension — not part of original Markdown. They work on GitHub, GitLab, Notion, and most modern Markdown renderers, but not on all platforms.

Frequently asked questions

What's the difference between Markdown and HTML?

Markdown compiles to HTML — it's a shorthand for writing HTML without angle brackets. Markdown is easier to read and write as plain text. Most Markdown processors also allow raw HTML inline, so you can mix them when Markdown doesn't have a shorthand for something (e.g., custom CSS classes, colored text).

Why does my Markdown look different on different platforms?

There is no single Markdown standard. The original spec left many edge cases undefined, so different platforms implement their own variants. GitHub uses GitHub Flavored Markdown (GFM), which adds tables, task lists, and strikethrough. Reddit, Discord, and Slack use their own subsets. CommonMark is a modern attempt at a consistent specification.

How do I add a line break in Markdown?

A single return in Markdown does not create a line break — it renders as a space. To force a line break within a paragraph, end the line with two or more spaces before pressing Return, or use a backslash (\) at the end of the line in some parsers. To start a new paragraph, leave a blank line between them.

Can I use Markdown in emails?

Not natively — email clients render HTML, not Markdown. However, some email clients and services (HEY, Superhuman, some Gmail extensions) support Markdown input and convert it to HTML before sending. For most email clients, you'll need to convert your Markdown to HTML first.