Markdown is a lightweight markup language for writing content that converts to HTML. You can learn the basics in minutes and use it in blogs, docs, and READMEs. This guide walks you through the most useful syntax with examples.
What you’ll learn: headings, paragraphs, images, blockquotes, tables, code blocks, lists, and inline HTML.
Headings
Use one to six # characters at the start of a line. One # is the largest (like <h1>), six is the smallest (like <h6>).
Syntax: # through ###### at the beginning of a line.
H1
H2
H3
H4
H5
H6
Paragraphs
Plain text is a paragraph. Separate paragraphs with a blank line. No extra syntax needed.
Syntax: Just type. Use a blank line between paragraphs.
Images
To add an image, use an exclamation mark, alt text in square brackets, then the path or URL in parentheses. Alt text is used by screen readers and when the image can’t load.
Syntax:
Example:
Blockquotes
Blockquotes are for quoted text. Start each line with >. You can use other Markdown inside (bold, italic, links).
Blockquote without attribution
Syntax:
> Your quoted text here.
> **Note** that you can use _Markdown syntax_ inside a blockquote.Output:
Tiam, ad mint andaepu dandae nostion secatur sequo quae.
Note that you can use Markdown syntax within a blockquote.
Blockquote with attribution
Syntax:
> Don't communicate by sharing memory, share memory by communicating.<br>
> — <cite>Rob Pike[^1]</cite>Output:
Don’t communicate by sharing memory, share memory by communicating.
— Rob Pike1
Tables
Tables use pipes | for columns and a row of dashes under the header. Alignment is optional.
Syntax:
| Italics | Bold | Code |
| --------- | -------- | ------ |
| _italics_ | **bold** | `code` |Output:
| Italics | Bold | Code |
|---|---|---|
| italics | bold | code |
Code
Inline code
Wrap code in single backticks: `code` for short snippets like variable or command names.
Code blocks
Use a line of three backticks, optionally add a language name for highlighting, then your code, then three backticks to close.
Syntax: Open with ``` on its own line, optionally add a language (e.g. html, javascript, css, markdown, typescript, bash), then close with ``` on a new line.
```html
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<title>Example HTML5 Document</title>
</head>
<body>
<p>Test</p>
</body>
</html>
```Output:
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<title>Example HTML5 Document</title>
</head>
<body>
<p>Test</p>
</body>
</html>Lists
Ordered list
Use numbers followed by a period and a space. The actual number doesn’t matter for output; list order is what counts.
Syntax:
1. First item
2. Second item
3. Third itemOutput:
- First item
- Second item
- Third item
Unordered list
Use -, *, or + at the start of each line.
Syntax:
- List item
- Another item
- And another itemOutput:
- List item
- Another item
- And another item
Nested list
Indent list items with two or four spaces to nest them under a parent item.
Syntax:
- Fruit
- Apple
- Orange
- Banana
- Dairy
- Milk
- CheeseOutput:
- Fruit
- Apple
- Orange
- Banana
- Dairy
- Milk
- Cheese
Inline formatting and HTML
- Bold:
**text**or__text__ - Italic:
*text*or_text_ - Link:
[link text](https://example.com)
When you need more control, you can use HTML. Most Markdown parsers allow inline HTML.
Syntax examples:
<abbr title="Graphics Interchange Format">GIF</abbr> is a bitmap image format.
H<sub>2</sub>O
X<sup>n</sup> + Y<sup>n</sup> = Z<sup>n</sup>
Press <kbd>CTRL</kbd> + <kbd>ALT</kbd> + <kbd>Delete</kbd> to end the session.
Most <mark>salamanders</mark> are nocturnal.Output:
GIF is a bitmap image format.
H2O
Xn + Yn = Zn
Press CTRL + ALT + Delete to end the session.
Most salamanders are nocturnal, and hunt for insects, worms, and other small creatures.
Next step: Once you’re comfortable with Markdown, try Learning MDX to add components and JavaScript inside your content.