Markdown Syntax Guide: From Basics to Advanced Features

March 9, 2026 9 min read By CodeTidy Team

Markdown is the de facto standard for writing formatted text on the web. GitHub READMEs, documentation sites, blogs, Slack messages, Notion pages, and Jupyter notebooks all use Markdown. This guide covers everything from basic syntax to advanced features you might not know about.

Headings

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

Use only one # (H1) per document. Start sections with ## (H2) and nest subsections with ### (H3). Don't skip levels — go from H2 to H3, not H2 to H4.

Text Formatting

**bold text**
*italic text*
***bold and italic***
~~strikethrough~~
`inline code`

Horizontal rule (any of these):
---
***
___

Links and Images

# Links
[Link text](https://example.com)
[Link with title](https://example.com "Hover text")

# Reference-style links (useful for reuse)
[Go to Example][example-link]

[example-link]: https://example.com

# Auto-linked URLs
https://example.com

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

# Image with link
[![Alt text](image.png)](https://example.com)

Lists

# Unordered lists (use -, *, or +)
- Item one
- Item two
  - Nested item
  - Another nested item
- Item three

# Ordered lists
1. First item
2. Second item
   1. Nested numbered item
   2. Another nested item
3. Third item

# The actual numbers don't matter — Markdown auto-numbers:
1. First
1. Second (renders as 2)
1. Third (renders as 3)

Code

Inline code

Use `backticks` for inline code.

To include a literal backtick: ``code with ` backtick``

Code blocks

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

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

```sql
SELECT name, email
FROM users
WHERE active = true
ORDER BY created_at DESC;
```

Supported language identifiers include: javascript, python, java, go, rust, sql, bash, html, css, json, yaml, toml, typescript, ruby, php, c, cpp, and many more. The exact highlighting depends on the renderer.

Blockquotes

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

> Blockquotes can be nested:
>> Like this inner quote.

> **Tip:** You can use other Markdown inside blockquotes.

Tables

| Name     | Role       | Location |
|----------|------------|----------|
| Alice    | Developer  | Portland |
| Bob      | Designer   | Seattle  |
| Charlie  | Manager    | Austin   |

# Column alignment:
| Left     | Center     | Right    |
|:---------|:----------:|---------:|
| aligned  | aligned    | aligned  |

Tables must have a header row and a separator row. Use : in the separator to control alignment. Columns don't need to be perfectly aligned in the source — the pipes just need to be present.

Task Lists

- [x] Write the introduction
- [x] Add code examples
- [ ] Review and edit
- [ ] Publish

Task lists are a GitHub Flavored Markdown (GFM) extension. They render as checkboxes on GitHub, GitLab, and most Markdown renderers.

Footnotes

Here's a statement that needs a citation[^1].

And another point worth noting[^note].

[^1]: This is the footnote content.
[^note]: Footnotes can have any label, not just numbers.

Footnotes are rendered at the bottom of the page. Not all Markdown processors support them — GitHub does, basic CommonMark doesn't.

HTML in Markdown

Most Markdown processors allow raw HTML:

# Collapsible section (GitHub)
<details>
<summary>Click to expand</summary>

This content is hidden by default.

- You can use Markdown inside HTML blocks
- Just leave a blank line after the HTML tag

</details>

# Custom styling
<div align="center">

![Logo](logo.png)

**My Project Name**

</div>

# Superscript/subscript
H<sub>2</sub>O
x<sup>2</sup>

For more on HTML entities you might need inside Markdown, see our HTML Entity Encoder.

GitHub Flavored Markdown (GFM) Extras

Alerts / Admonitions

> [!NOTE]
> Useful information that users should know.

> [!TIP]
> Helpful advice for doing things better.

> [!IMPORTANT]
> Key information users need to know.

> [!WARNING]
> Urgent info that needs immediate attention.

> [!CAUTION]
> Advises about risks or negative outcomes.

Auto-linking references

# GitHub auto-links these:
#123              → links to issue/PR #123
@username         → links to user profile
SHA: a1b2c3d     → links to commit

Mermaid diagrams

```mermaid
graph LR
    A[Start] --> B{Decision}
    B --> |Yes| C[Do thing]
    B --> |No| D[Do other thing]
    C --> E[End]
    D --> E
```

Writing Better Markdown

One sentence per line — makes diffs cleaner and makes it easier to rearrange content. The rendered output won't show line breaks within a paragraph.
Blank lines between blocks — always leave a blank line before and after headings, code blocks, lists, and blockquotes.
Consistent list markers — pick either - or * for unordered lists and stick with it throughout the document.
Alt text on images — always provide descriptive alt text for accessibility.
Reference links for repeated URLs — if you link to the same URL multiple times, define it once as a reference.

Markdown Flavors

Flavor	Used By	Notable Features
CommonMark	Spec standard	Strict, well-defined parsing rules
GFM	GitHub	Tables, task lists, autolinks, alerts
MDX	Next.js, Docusaurus	JSX components inside Markdown
MultiMarkdown	Academic writing	Footnotes, citations, math
Obsidian	Obsidian app	Wikilinks, embeds, callouts

The best way to learn Markdown is to write it and see the output. Try our Markdown to HTML Preview tool — type Markdown on the left and see the rendered HTML in real time. It's perfect for writing READMEs, documentation, and blog content. You can also use our HTML Beautifier to clean up the generated HTML output.