Markdown code blocks: fenced, inline and highlighted

Fenced code blocks

For anything longer than a phrase, open and close with three backticks on their own lines:

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

Everything between the fences is preserved exactly: indentation, blank lines, punctuation, and every character that would otherwise be Markdown. Fenced blocks came from GitHub Flavored Markdown and are now supported by essentially every renderer worth using.

Tilde fences

Three tildes do the same job:

~~~
console.log("same result");
~~~

Tildes matter in one situation: when the code you are showing contains a backtick fence of its own. A ~~~ wrapper around Markdown that itself contains ``` keeps the two from colliding. Otherwise backticks are the convention. You cannot mix them on one block, because a fence opened with backticks must close with backticks.

Fence length and blank lines

Two rules decide whether a block closes cleanly:

• The closing fence must be at least as long as the opening one, so a block opened with four backticks closes with four or more.
• Leave a blank line before the opening fence and after the closing fence.

Skip that blank line and some parsers glue the block into the surrounding paragraph. It is a five-second fix that costs people twenty minutes of confusion.

The four-space indented block, and why fences won

The original 2004 Markdown had no fences. A code block was any run of lines indented by four spaces or one tab:

Here is an example:

    $ git status
    On branch main

Back to normal prose.

It still works in every renderer, and you will meet it in old README files and in Stack Overflow answers written a decade ago. Use fences anyway, for four reasons:

• No language identifier. An indented block cannot be syntax highlighted, because there is nowhere to say what language it is.
• Indentation is data. Python, YAML and Makefiles care about leading whitespace. Adding four spaces to every line and mentally subtracting them again is an unforced error.
• Copy-paste breaks it. Pasted code arrives unindented, so you re-indent every line by hand after every edit.
• It collides with lists. Inside a list item, four spaces already means "continuation of this item", which makes the two rules fight.

Treat the four-space form as something to read, not something to write.

Tip: Converting an old file is mechanical. Select the block, strip four spaces from every line, wrap it in fences, then add a language name. Most editors do the de-indent with a single Shift+Tab.

Code blocks inside lists, and fences inside fences

Inside a list item

A fence inside a list must be indented to line up with the item's text, or the list breaks in half around it. For a bulleted list that is usually two or three spaces; for an ordered list, three or four:

1. Install the dependencies:

   ```bash
   npm install
   ```

2. Start the dev server:

   ```bash
   npm run dev
   ```

The rule is the same one that governs all continuation content in Markdown lists. Three points cover it:

• Indent to the first character of the item's text, never to the marker.
• Give the opening and closing fence the same indentation.
• Leave a blank line before the fence to keep strict parsers happy.

Watch out: Get the indent wrong and the numbering restarts at 1 after the block. That renumbering is the classic symptom, and it means the list ended at the fence rather than continuing through it.

Showing a fence inside a fence

To display Markdown that itself contains a code block, make the outer fence longer than the inner one. Four backticks outside, three inside:

````markdown
Here is how to write a code block:

```js
alert("hi");
```
````

This is the mechanism behind every tutorial that teaches Markdown, this page included. If the inner content already uses four backticks, use five outside. The alternative is a ~~~ outer fence, which never collides with backticks at all.

Where highlighting actually happens

Fences are near-universal. Colour is not, because highlighting is a separate library that the platform either bundles or does not.

The preview here follows the same rule as the rest of that table. It runs highlight.js on any fence that carries a language tag, and leaves an untagged fence plain rather than guessing the language.

The practical consequence: never let colour carry meaning. If the reader must notice one specific line, say so in the prose above the block, or mark it with a comment inside the code. A highlighted keyword that renders grey somewhere else has communicated nothing. The Discord guide and the Notion guide cover what each app does with a fence.

Line length and horizontal scroll

Code blocks do not wrap in most renderers. A 200-character line becomes a horizontal scrollbar, and on a phone the reader sees the first third and swipes for the rest. Keep example lines under roughly 80 characters. Four habits get you there:

• Break long shell commands with a trailing backslash.
• Split long function calls across several lines.
• Shorten placeholder variable names to something short and obvious.
• Trim example URLs down to the part that matters.

If a block genuinely cannot be shortened, say what matters in the prose, so nobody has to scroll to understand the point. This is where raw HTML tempts people into a wrapping <pre> tag. Pasting a screenshot is worse still, since an image of code cannot be copied, searched or read aloud.

Common mistakes and how to fix them

The unclosed fence

This is the big one, and it is spectacular when it happens:

Broken:
```js
const a = 1;

Everything after this point is now code.
Headings, lists, links: all swallowed.

An opening fence with no matching close consumes the entire rest of the document. The tell is unmistakable: the page turns into one enormous monospaced block from a certain point downward. Scroll up to where the formatting died and add the missing ```. A closing fence needs its own line with nothing else on it, so const a = 1;``` does not count.

Tip: A live preview catches an unclosed fence the second you type it. That is the strongest argument for drafting in the editor rather than straight into a pull request description.

Smart quotes

Broken:  const greeting = “hello”;
Fixed:   const greeting = "hello";

Curly quotes are not the same characters as straight ones, and no compiler accepts them. Your Markdown renderer will not convert them inside a code block. The text may have been converted before it arrived, though: by a word processor, a chat app, a CMS editor, or macOS system-wide substitution. The same applies to -- becoming a dash. If pasted code fails with a baffling syntax error, look at the quotes first.

Pasting from a word processor

Copying code out of Word, Google Docs or an email drags along invisible passengers:

• Non-breaking spaces that look identical to ordinary ones.
• Tabs converted into variable-width indents.
• Zero-width characters with no visible form at all.
• Smart punctuation, as above.

The result looks correct and does not run. Paste through a plain-text step first: a text editor, a terminal, or the left pane of this site's editor, where you can see the raw characters before you commit them.

The fence that is indented too far

Broken:
    ```js
    const a = 1;
    ```

Four spaces at the start of a line already means "indented code block", so the fence characters get displayed as literal text. Unless the block sits inside a list item, keep fences flush with the left margin.

Language name typos

Writing ```JavaScipt costs you the colour and nothing else, so nothing looks broken. If a block that should be coloured is not, check the info string against the table above before blaming the platform. For everything else, see the complete Markdown guide, the quick reference table, or the FAQ.