Markdown Syntax Guide: Complete Reference

What is Markdown?

Markdown is a lightweight markup language that lets you write formatted content using plain text. Created by John Gruber in 2004, it has become the standard for documentation, READMEs, blog posts, and note-taking across the web.

The beauty of Markdown lies in its simplicity: what you type reads naturally as plain text, yet renders as rich HTML.

Headings

Use # symbols to create headings. The number of # symbols sets the heading level.

# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6

Best practice: use one # heading per document as the title, then start sections with ##.

Emphasis

Add emphasis with asterisks or underscores:

Tip: prefer asterisks (*) over underscores for consistency — they work in all contexts without spacing issues.

Lists

Unordered Lists

Use -, *, or + for bullet points:

- First item
- Second item
  - Nested item
  - Another nested item
- Third item

Ordered Lists

Use numbers followed by periods:

1. First step
2. Second step
3. Third step

Task Lists (GFM)

Add checkboxes with [ ] and [x]:

- [x] Write the guide
- [ ] Review the draft
- [ ] Publish the article

Links and Images

Links

[Link text](https://example.com)
[Link with title](https://example.com "Hover text")
[Reference link][ref]

[ref]: https://example.com

Images

![Alt text describing the image](image.png)
![Alt text](image.png "Optional title")

Always write descriptive alt text — it improves accessibility and SEO. Avoid vague descriptions like "image" or "screenshot."

Code

Inline Code

Wrap code in single backticks:

Use the `console.log()` function to debug.

Code Blocks

Use triple backticks with an optional language hint for syntax highlighting:

```javascript
function greet(name) {
  return `Hello, ${name}!`
}
```

Always specify the language. Syntax highlighting makes code significantly easier to read.

Supported Language Hints

Blockquotes

Use > for blockquotes:

> This is a blockquote.
>
> It can span multiple paragraphs.
>
> > And even nest.

Blockquotes work well for callouts, notes, and quoted text.

Tables

Create tables with pipes and hyphens:

| Column 1 | Column 2 | Column 3 |
|----------|:--------:|----------|
| Left     | Center   | Right    |
| Aligned  | Aligned  | Aligned  |

Alignment colons:

• :--- = left (default)
• :---: = center
• ---: = right

Keep tables simple. If a table gets too wide, consider a list instead.

Horizontal Rules

Use three or more hyphens, asterisks, or underscores:

---
***
___

All three render the same way. Choose one style and stick with it across your project.

Escaping Characters

To display a literal Markdown character, precede it with a backslash:

\*Not italic\*
\# Not a heading

Characters you may need to escape: \, `, *, _, {}, [], (), #, +, -, ., !, |.

Advanced Syntax

Footnotes

Here is a claim.[^1]

[^1]: This is the footnote content.

Definition Lists (some renderers)

Term
: Definition of the term

Heading IDs and Links

Most renderers auto-generate IDs from headings. Link to them directly:

[Jump to section](#heading-ids-and-links)

Common Pitfalls

1. Inconsistent heading levels — skip levels (e.g., # to ###) and screen readers lose structure
2. Missing alt text — images without descriptions fail accessibility checks
3. No language hints — code blocks without a language lose syntax highlighting
4. Mixed list markers — mixing -, *, and + in the same list creates inconsistency
5. Trailing spaces for line breaks — two spaces at the end of a line create a <br>, but this is invisible in editors and easy to break accidentally

Quick Reference

Related Guides

• Markdown Best Practices
• Markdown Extensions Explained
• Placeholder Text Best Practices

Try It Yourself

Ready to put Markdown into practice? Use our free Markdown to HTML Converter to write Markdown and see the rendered HTML output instantly.