Skip to main content
Writing August 3, 2026 · 7 min read

What Is Markdown and How to Write It

Markdown is a lightweight markup language designed to be readable as plain text while converting cleanly to formatted HTML. Created by John Gruber in 2004, it's now the default format for GitHub READMEs, documentation, note-taking apps, and countless other tools.

Where Markdown Is Used

GitHub & GitLab READMEs
Notion, Obsidian, Bear
Discord & Slack messages
Reddit posts
Dev.to & Hashnode articles
Jekyll & Hugo sites
VS Code & JetBrains
Jupyter notebooks
Stack Overflow

Core Markdown Syntax

Headings

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

Text Formatting

Syntax Result
**bold** or __bold__ bold
*italic* or _italic_ italic
~~strikethrough~~ strikethrough
`inline code` inline code
> blockquote blockquote indented block
--- (3 dashes) horizontal rule

Lists

- Unordered item        1. Ordered item
- Another item          2. Second item
  - Nested item         3. Third item
  - Another nested         - nested under 3

Links and Images

[Link text](https://example.com)
[Link with title](https://example.com "Tooltip text")
![Alt text](image.jpg)
![Alt text](image.jpg "Image title")

Code Blocks

```python
def hello():
    print("Hello, world!")
```

```javascript
const greet = () => console.log("Hello!");
```

Tables (GFM Extension)

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Cell A   | Cell B   | Cell C   |
| Cell D   | Cell E   | Cell F   |

# Alignment (add : to the separator row)
| Left     | Center   | Right    |
|:---------|:--------:|---------:|

Markdown Flavours

CommonMark

The standardised specification. Resolves ambiguities in Gruber's original spec. Used as the base by most modern parsers.

GFM (GitHub Flavored Markdown)

Adds tables, task lists (- [ ] / - [x]), strikethrough, and auto-linked URLs. Used by GitHub, GitLab, and many tools.

MDX

Markdown + JSX components. Used in documentation sites built with Next.js, Astro, and other React-based frameworks.

MultiMarkdown / Pandoc

Extended flavors adding footnotes, citations, math, and more for academic and long-form writing.

Write and preview Markdown — free

Markdown Preview