Markdown Syntax Guide: A Complete Reference

What Is Markdown?

Markdown is a lightweight markup language created by John Gruber in 2004. It lets you write formatted text using plain text syntax that's readable even without rendering. Markdown converts to HTML, making it perfect for documentation, README files, blog posts, and content management.

Markdown is used everywhere: GitHub, GitLab, Notion, Obsidian, Reddit, Stack Overflow, Discord, Slack, and most modern documentation tools.

Headings

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

Alternatively (only works for H1 and H2):

Heading 1
=========

Heading 2
---------

Emphasis

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

Output: italic, bold, bold italic, strikethrough

Inline Code

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

Renders as: Use the console.log() function to debug.

Code Blocks

Fenced code blocks with optional syntax highlighting:

```javascript
function greet(name) {
  console.log(`Hello, ${name}!`);
}
```

Supported language hints: javascript, python, bash, sql, json, yaml, html, css, typescript, rust, go, and many more.

Links

[Link text](https://example.com)
[Link text](https://example.com "Optional title")

Reference-style:
[Link text][ref-id]
[ref-id]: https://example.com "Optional title"

Images

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

Reference-style:
![Alt text][img-ref]
[img-ref]: image.png "Optional title"

Lists

Unordered list:

- Item 1
- Item 2
  - Nested item (indent 2 spaces)
  - Another nested item
- Item 3

* Also valid
+ Also valid

Ordered list:

1. First item
2. Second item
3. Third item

Task list (GitHub Flavored Markdown):

- [x] Completed task
- [ ] Incomplete task
- [ ] Another incomplete task

Blockquotes

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

> Nested:
> > Inner blockquote

Horizontal Rules

---
***
___

Tables (GitHub Flavored Markdown)

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

Alignment:
| Left     | Center   | Right    |
|:---------|:--------:|---------:|
| text     | text     | text     |

Escaping Special Characters

To display a literal *, _, #, [, ], (, ), or backtick, escape it with a backslash:

\*not italic\*
\# not a heading

GitHub Flavored Markdown (GFM) Extensions

GitHub uses GFM, an extended version of Markdown:

Autolinks — URLs and emails are automatically linked: https://github.com

Mention — @username notifies a GitHub user

Issue reference — #123 links to issue number 123

Strikethrough — text creates strikethrough (not standard Markdown)

Tables — As shown above

Task lists — Checkbox lists that are interactive on GitHub

Syntax highlighting in code fences — As shown above

Footnotes (supported in some renderers):

Here is text with a footnote.[^1]

[^1]: This is the footnote content.

Markdown vs HTML

Markdown converts to HTML. You can mix raw HTML inside Markdown (most parsers allow it):

Some *markdown* and then <span style="color:red">raw HTML</span>.

However, HTML elements won't be processed as Markdown inside them.

Common Mistakes

1. Spaces matter in lists — Nested items need consistent indentation (typically 2 or 4 spaces)
2. Blank lines — You often need a blank line before/after headings, code blocks, and lists
3. Trailing spaces — Two trailing spaces create a line break (not all renderers respect this)
4. Underscores in words — Some parsers interpret some_function_name as emphasis. Use asterisks for emphasis to avoid this.

Use our free Markdown to HTML converter to preview and convert Markdown, or the Markdown Table Generator to create tables without counting pipes.