Markdown Syntax Guide: Complete Reference With Examples

Why Every Developer Needs to Know Markdown

In 2004, John Gruber published Markdown with a simple premise: "a text-to-HTML conversion tool for web writers." He could not have anticipated that twenty-two years later, Markdown would be the primary documentation format for GitHub's 420+ million repositories, the default in Notion, Obsidian, Linear, Jira, Confluence, Reddit, Discord, Slack, and virtually every modern developer tool.

The 2025 Stack Overflow Developer Survey, which collected over 49,000 responses from 177 countries, named Markdown the most admired documentation and synchronization tool for the third consecutive year — outranking every alternative including AsciiDoc and reStructuredText. It is not going away.

This guide covers the complete syntax: the core spec (CommonMark), the GitHub Flavored Markdown extensions (GFM), and the platform-specific quirks that catch developers off guard. Each section shows the raw Markdown source side-by-side with what it renders.

Convert between Markdown and HTML instantly with our HTML to Markdown converter.

The Markdown Specification Landscape

Original Markdown (2004) was intentionally underspecified — Gruber described the behavior for common cases but left edge cases to implementation discretion. This caused a fractured ecosystem where the same Markdown rendered differently across GitHub, Pandoc, and Jekyll.

Recommendation: Write to CommonMark for maximum portability. Use GFM extensions (tables, task lists) freely — they are supported in all major developer tools. Avoid Pandoc-specific extensions unless you are specifically targeting academic output.

Headings

Markdown supports two heading styles: ATX (using #) and Setext (using underlines). ATX is universal; Setext only supports H1 and H2. Use ATX.

# H1 — Page title (one per page)
## H2 — Major section
### H3 — Subsection
#### H4 — Sub-subsection
##### H5 — Rarely used
###### H6 — Rarely used

# ATX requires a space after #
## Alternative: Setext style (H1 and H2 only)
Heading 1
=========
Heading 2
---------

Text Formatting

Gotcha: Underscores inside words are not treated as emphasis markers in CommonMark: some_var_name renders literally. Use *asterisks* for emphasis to avoid this ambiguity.

Lists

<!-- Unordered list — use -, *, or + (be consistent) -->
- First item
- Second item
  - Nested item (indent 2 spaces)
  - Another nested item
- Third item

<!-- Ordered list — use numbers + period -->
1. First item
2. Second item
   1. Nested ordered item
   2. Another nested
3. Third item

<!-- Loose list (blank line between items = paragraph wrapper) -->
- This item gets wrapped in <p> tags

- This item too — blank line triggers loose mode

<!-- Task list (GFM extension) -->
- [x] Completed task
- [ ] Pending task
- [x] Another done task

CommonMark detail: In ordered lists, the actual numbers do not matter — CommonMark only uses the first number to determine the list start value. 1. 1. 1. renders as 1, 2, 3. The HTML start attribute is set to your first number if it isn't 1.

Loose vs tight lists: If any list item is separated by a blank line, the entire list becomes "loose" — every item gets wrapped in <p> tags. This affects spacing in rendered output. For compact lists, do not add blank lines between items.

Links and Images

<!-- Inline link -->
[Link text](https://bytepane.com)

<!-- Link with title (shown on hover) -->
[BytePane Tools](https://bytepane.com "Developer Tools")

<!-- Reference link (define URL separately) -->
[Link text][ref-id]
[ref-id]: https://bytepane.com "Optional title"

<!-- Auto-link (GFM) — URL becomes clickable automatically -->
https://bytepane.com

<!-- Bare email auto-link -->
<[email protected]>

<!-- Link to heading anchor (GitHub generates IDs from heading text) -->
[Jump to section](#heading-text-lowercased-with-hyphens)

<!-- Image syntax (like link but with ! prefix) -->
![Alt text](https://bytepane.com/og-image.png)
![Alt text](image.png "Optional title")

<!-- Image with link (nest inside link) -->
[![Alt text](image.png)](https://bytepane.com)

<!-- Image sizing requires inline HTML -->
<img src="image.png" width="300" alt="Description">

Accessibility: Alt text is not optional. Screen readers announce image alt text to visually impaired users. For decorative images, use an empty alt (![](image.png)). For informational images, describe the content — not the visual style.

Reference-style links are useful when the same URL appears multiple times, or when long URLs would break the reading flow of the source. The reference definitions can go anywhere in the document — most people put them at the bottom.

Code: Inline and Blocks

<!-- Inline code: single backticks -->
Use the `console.log()` function to debug.

<!-- If code contains backticks, use double backticks as delimiter -->
`` const x = `template` ``

<!-- Fenced code block with language identifier -->
```javascript
const greet = (name) => `Hello, ${name}!`
console.log(greet('World'))
```

<!-- Common language identifiers -->
```python   → Python
```bash     → Shell/bash scripts
```sql      → SQL queries
```json     → JSON
```yaml     → YAML
```tsx      → TypeScript + JSX
```go       → Go
```rust     → Rust
```diff     → Diff output (shows +/- coloring)

<!-- Indented code block (4 spaces — original Markdown, CommonMark) -->
    This is a code block
    via indentation (no language highlighting)

<!-- Line numbers: not in spec, depends on renderer -->
```javascript showLineNumbers
// Some renderers (MDX, Prism) support showLineNumbers
```

Performance tip: Syntax highlighting libraries like Prism.js and highlight.js add significant bundle weight. For static sites, use a build-time highlighter like shiki (which ships zero JavaScript to the client) rather than client-side highlighting. Shiki uses VS Code's TextMate grammars — the same quality as your editor.

Tables (GFM Extension)

<!-- Basic table (GFM) -->
| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Cell 1   | Cell 2   | Cell 3   |
| Cell 4   | Cell 5   | Cell 6   |

<!-- Alignment: colons in separator row -->
| Left     | Center   | Right    |
|:---------|:--------:|---------:|
| aligned  | centered | aligned  |
| left     | middle   | right    |

<!-- Pipe chars in cells: escape with \ -->
| Header    | Value       |
|-----------|-------------|
| Pipe char | \| escaped  |

<!-- Pipes at line edges are optional in CommonMark -->
Column A | Column B
---------|----------
Value A  | Value B

Gotcha: Tables require a header row and a separator row — you cannot have a headerless table in GFM. For complex tables needing colspan/rowspan, fall back to inline HTML <table>.

Blockquotes

<!-- Basic blockquote -->
> This is a blockquote.
> It can span multiple lines.

<!-- Nested blockquote -->
> Level 1 quote
>> Level 2 (nested)
>>> Level 3

<!-- Blockquote with other Markdown inside -->
> ## Heading inside blockquote
>
> - List item
> - Another item
>
> ```javascript
> console.log('code in quote')
> ```

<!-- GitHub callouts (GFM extension, supported since 2023) -->
> [!NOTE]
> Useful information for readers.

> [!WARNING]
> Critical information — important warnings.

> [!TIP]
> Helpful but optional suggestions.

> [!IMPORTANT]
> Key information readers must not miss.

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

GitHub's callout syntax (> [!NOTE]) was introduced in September 2023 and renders with colored icons in GitHub. Other platforms may render it as a plain blockquote — test in your target environment.

Horizontal Rules and Line Breaks

<!-- Horizontal rule — three or more of: ---, ***, or ___ -->
---
***
___

<!-- All produce: <hr /> -->

<!-- Line break within a paragraph — two methods: -->

Method 1: two trailing spaces (may be stripped by editors)
Next line

Method 2: backslash at end of line (CommonMark)\
Next line

<!-- Hard vs soft wraps:
     A single newline = soft wrap = same paragraph
     A blank line = new paragraph
     Trailing spaces or \ = <br> tag -->

Paragraph one text here.
Still the same paragraph (soft wrap).

New paragraph starts here (blank line above).

Editor warning: Many editors (VS Code, vim with set expandtab, prettier) automatically strip trailing whitespace, silently breaking the two-space line break. The backslash method is safer for this reason, though it was only standardized in CommonMark — not the original Markdown spec.

Footnotes and Definition Lists

<!-- Footnotes (Pandoc, GitHub, some renderers) -->
Here is a sentence with a footnote.[^1]

Another sentence with a longer note.[^longnote]

[^1]: Short footnote text.

[^longnote]: Longer footnote. Can contain
    multiple paragraphs if indented.

<!-- Definition lists (Pandoc extension) -->
Term 1
:   Definition 1

Term 2
:   Definition 2a
:   Definition 2b

<!-- Abbreviations (PHP Markdown Extra) -->
*[HTML]: HyperText Markup Language
*[CSS]: Cascading Style Sheets

The HTML and CSS are used together.
<!-- "HTML" and "CSS" get <abbr> titles in output -->

Platform support: Footnotes are supported on GitHub (as of 2022), Pandoc, and Obsidian. They are not part of CommonMark or GFM core — check your renderer's documentation. Definition lists and abbreviations are Pandoc/PHP Markdown Extra extensions — avoid for maximum portability.

Escaping Characters and Inline HTML

<!-- Escape formatting characters with backslash -->
\ ` * _ { } [ ] ( ) # + - . ! |

\*Not emphasized\*    → *Not emphasized*
\_Not italic\_        → _Not italic_
\[Not a link\]         → [Not a link]

<!-- Inline HTML (passed through by most processors) -->
<div align="center">

Centered content here.

</div>

<!-- Useful inline HTML for features Markdown lacks -->
<details>
<summary>Click to expand</summary>

Hidden content revealed on click. Supported by GitHub!

</details>

<!-- Subscript and superscript -->
H<sub>2</sub>O     → H₂O
x<sup>2</sup>      → x²

<!-- Keyboard shortcut rendering -->
Press <kbd>Ctrl</kbd> + <kbd>C</kbd> to copy.

<!-- Colored text (inline HTML — some renderers strip this) -->
<span style="color: red">Red text</span>

Security note: When rendering user-supplied Markdown, always sanitize HTML. Many renderers (marked.js, remark) have a sanitization option — enable it. Alternatively, use DOMPurify after rendering to strip dangerous tags (<script>, event attributes). GitHub sanitizes Markdown from untrusted sources at render time.

Front Matter and MDX

<!-- YAML front matter (Jekyll, Hugo, Astro, Next.js MDX) -->
---
title: "Markdown Syntax Guide"
date: 2026-04-26
author: BytePane Team
tags: [markdown, documentation, reference]
draft: false
---

# Article content starts here

<!-- MDX: Markdown + JSX components (Next.js, Docusaurus) -->
import { Button } from '@/components/Button'
import DataTable from './DataTable'

## Using React components in Markdown

<Button href="/regex-tester/" variant="primary">
  Open Regex Tester
</Button>

<DataTable data={stats} />

Normal Markdown content continues here.

MDX (Markdown + JSX) is the standard format for Next.js documentation sites and Docusaurus. It compiles to JavaScript, which means full React component support — interactive examples, data visualizations, and live code playgrounds inside Markdown. The trade-off is that MDX requires a build step and is not portable to non-React environments.

Complete Syntax Quick Reference

Platform-Specific Quirks

Markdown rendering varies across platforms even when they claim CommonMark compliance. Here are the most common real-world differences:

Frequently Asked Questions