Markdown Syntax Guide: From Basic to Advanced

A complete Markdown reference covering all standard and extended syntax, with practical examples for documentation, READMEs, and static sites.

By Belqassim Djafer · Published 2026-06-02 · Updated 2026-07-01

What Is Markdown?

Markdown is a lightweight markup language designed to be readable as plain text while converting cleanly to HTML. Created by John Gruber in 2004, it has become the de-facto format for developer documentation, README files, wikis, static site generators, and writing tools.

The key insight behind Markdown: formatting should be readable in its raw, unprocessed form. A **bold word** is visually clear even before rendering.

Basic Syntax

Headings

# H1 — Page title (use only once)
## H2 — Section heading
### H3 — Subsection
#### H4 — Sub-subsection

Emphasis

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

Lists

- Unordered item
- Another item
  - Nested item (two-space or four-space indent)

1. First ordered item
2. Second item
   1. Nested ordered item

Links and Images

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

![Alt text](image.png)
![Alt text](image.png "Caption")

[Reference link][ref-id]
[ref-id]: https://example.com

Blockquotes

> Single-level blockquote
>
> Multiple paragraphs in a blockquote.
>
>> Nested blockquote

Code

Inline `code` with backticks.

```javascript
// Fenced code block with language
const greet = name => `Hello, ${name}!`;

### Horizontal Rule

```markdown
---
***
___

Extended Syntax (GFM)

GitHub Flavored Markdown (GFM) extends CommonMark with additional features widely supported across platforms.

Tables

| Name    | Age | City       |
|---------|-----|------------|
| Alice   | 30  | Paris      |
| Bob     | 25  | London     |
| Charlie | 35  | New York   |

# Column alignment
| Left | Center | Right |
|:-----|:------:|------:|
| L    |   C    |     R |

Task Lists (Checkboxes)

- [x] Completed task
- [ ] Pending task
- [x] Another done task

Footnotes

Here is a sentence with a footnote.[^1]

[^1]: This is the footnote content.

Definition Lists

Term 1
:   Definition of term 1

Term 2
:   Definition of term 2

Callout Blocks (GitHub / Obsidian)

> [!NOTE]
> Useful information for the reader.

> [!WARNING]
> Critical information requiring attention.

> [!TIP]
> Helpful advice to do something better.

Writing Great Documentation with Markdown

README Structure

A well-structured README follows this pattern:

# Project Name

Short, compelling description.

## Features

- Feature 1
- Feature 2

## Quick Start

```bash
npm install my-package

Usage

import { doThing } from "my-package";
doThing("hello");

API Reference

doThing(input)

Returns: string

Contributing

License

### Changelogs

Follow [Keep a Changelog](https://keepachangelog.com/) format:

```markdown
# Changelog

## [2.1.0] - 2026-06-01

### Added
- New export function
- Support for CSV output

### Fixed
- Parsing error with empty arrays

### Changed
- Default timeout increased to 30s

## [2.0.0] - 2026-04-15
...

Markdown Processors and Flavors

Common Mistakes

Hard Line Breaks

A single newline in Markdown is not a paragraph break — you need a blank line:

This is line one.
This appears on the same line.

This is a new paragraph. (blank line above)

To force a line break within a paragraph, end the line with two spaces or use <br>.

Escaping Special Characters

Prefix with backslash to display Markdown characters literally:

*This is not italic*
`This is not code`
# This is not a heading

Mixing Tabs and Spaces

Markdown processors interpret tabs as 4 spaces. Mixing leads to inconsistent list rendering across editors.

Markdown to HTML

Markdown is always converted to HTML for rendering. Understanding this conversion helps debug output:

**bold** → <strong>bold</strong>
*italic* → <em>italic</em>
# H1 → <h1>H1</h1>
[text](url) → <a href="url">text</a>

Use our Markdown to HTML converter to see the HTML output for any Markdown, and our HTML to Markdown tool to convert HTML documents back to Markdown.

Conclusion

Markdown's simplicity makes it ideal for documentation that needs to be readable in raw form and rendered as HTML. Master the basics — headings, lists, links, code blocks — and add GFM extensions as needed. Keep your documents well-structured with clear headings and concise paragraphs for maximum readability.