Markdown Code Blocks
TL;DR
- Fenced code blocks use at least three backticks or three tildes.
- Indented code blocks use four or more spaces.
- Indented code blocks cannot interrupt a paragraph, but fenced code blocks can.
- The content of a code block is treated as literal text, not parsed as normal Markdown.
What it is
A code block is a multi-line region of literal text. Markdown keeps the contents together and prevents normal inline parsing inside the block.
Why it matters
Code blocks are essential in technical writing, but they also show up in non-code documentation for command lines, configuration snippets, logs, and examples. A solid mental model here pays off across the rest of Markdown.
Syntax
```
code here
```
indented code here
Minimal example
Source
```bash
npm install
npm run dev
```
What it does
This renders a fenced code block containing two shell commands.
More examples
Example 1: Fenced code block
```
function greet(name) {
console.log(`Hello, ${name}`);
}
```
What it does
Triple backticks open and close the block. Everything inside is treated literally.
Example 2: Indented code block
line one
line two
What it does
Four leading spaces create an indented code block.
Example 3: Showing triple backticks with quadruple backticks
````
```
visible backticks
```
````
What it does
The outer fence is longer than the inner one, so the inner triple backticks appear as literal content.
Example 4: Code inside a list item
1. Install dependencies
npm install
2. Start the app
What it does
Inside a list item, non-fenced code usually needs more indentation than it would outside the list.
Common pitfalls
- Opening with backticks and closing with tildes, or vice versa
- Why it happens: both fence styles are valid
- Fix: open and close with the same fence character
- Using fewer than three fence characters
- Why it happens: double backticks already exist for some inline-code edge cases
- Fix: use at least three backticks or three tildes for fenced blocks
- Forgetting to close a fence
- Why it happens: the closing line is easy to miss in long documents
- Fix: add the closing fence immediately, then fill in the content
- Expecting an indented code block to start in the middle of a paragraph
- Why it happens: four spaces look like "make this code"
- Fix: remember that indented code blocks cannot interrupt paragraphs, while fenced code blocks can
- Mis-indenting code inside list items
- Why it happens: list structure changes the indentation region
- Fix: prefer fenced blocks inside lists when teaching or writing for beginners
Portability and platform notes
- Fenced and indented code blocks are both part of CommonMark.
- In CommonMark, the first word of a fence's info string is typically used as a language hint, but the spec does not require any specific syntax-highlighting behavior.
- GitHub recommends blank lines before and after fenced code blocks to make raw Markdown easier to read.
- GitHub also notes that non-fenced code inside lists may need eight spaces of indentation, and that lower-case language identifiers are a good default for GitHub Pages syntax highlighting.
FAQ
Should I use fenced or indented code blocks?
For most modern documentation, fenced code blocks are easier to read, easier to nest, and easier to extend with language identifiers. Indented blocks are still worth learning because they are part of the core syntax.
Why did my code block not start?
If you used indentation, check whether the code was attached to a paragraph or list in a way that prevented an indented block from forming. If you used fences, check the fence length and closing line.
How do I show triple backticks inside a code block?
Wrap the whole example in a longer fence, such as four backticks.
Does Markdown parse links or emphasis inside a code block?
No. Code block contents are treated as literal text.
Practice
- Create one fenced code block and one indented code block containing the same content.
- Put a short code sample inside a numbered list item using both an indented block and a fenced block, then compare which source is easier to maintain.
Related topics
- Inline code spans
- Syntax highlighting and info strings
- Nested lists and indentation rules
- Escaping and literal characters