How to write a code block in Markdown:fence it with three backticks.

Fenced code blocks

A fence is a line of at least three backticks, and the block ends with a line of at least the same length. Everything between is shown as typed: no bold, no links, no line joining.

```
plain text, no colors
  indentation is kept
```

You can use three tildes instead: ~~~ opens and ~~~ closes. The two kinds do not mix, so a block that opens with tildes must close with tildes. Indenting every line by four spaces also makes a code block, the older style, but it cannot carry a language name, so fences are the better choice.

Language tags and syntax highlighting

The word after the opening fence is the info string. Most apps use it to pick a highlighter:

```json
{ "name": "dotmd", "private": true }
```

Common names that work in GitHub, DotMD and most other apps:

• js or javascript, ts or typescript, python, swift, go, rust
• bash, sh or zsh for shell commands
• json, yaml, html, css, sql
• markdown or md to show Markdown itself, diff for changes, text for no colors

The exact list of names depends on the app and its highlighter. A name the app does not know is not an error: the block just shows without colors. A block with no language is also shown plain.

Showing backticks inside a code block

If the code contains a line of three backticks, fence it with more. The closing fence has to be at least as long as the opening one, so use four to show three:

````markdown
```swift
let x = 1
```
````

That is how this page shows Markdown examples that contain code blocks. Tilde fences work the same way: a block opened with ~~~~ can contain ~~~.

Inline code

For a command or a name inside a sentence, wrap it in single backticks: `npm install` gives npm install. To show a backtick, put the whole thing between double backticks and add a space inside if the code starts or ends with a backtick:

``a `tick` inside``

Inline code also keeps characters like * and _ from being read as formatting, which makes it the right tool for file names and variables.

Code inside lists and quotes

A fenced block can sit inside a list item. Indent the fence to match the item's text so it stays part of the item:

1. Install the tool:

   ```bash
   brew install example
   ```

2. Run it.

Put a blank line before the fence, and keep every line of the code indented by the same amount. In a block quote, start each line of the fence with >.

Diff blocks

Mark a block diff and lines that start with + or - get green and red colors in apps that highlight diffs, including GitHub:

```diff
- let timeout = 30
+ let timeout = 60
```

It is a convenient way to show a change in a doc, a README or a spec without screenshots.

Common mistakes

• A closing fence that is shorter than the opening one, so the block never ends and swallows the rest of the page.
• Spaces before the language tag in strict apps. Write ```js, not ``` js, if colors do not appear.
• Mixing backticks and tildes in one block.
• No blank line before the fence after a list item or paragraph in some apps. Add one.
• Curly quotes. Text pasted from a word processor can turn straight quotes in code into curly ones. Paste as plain text.

Some fences are not for showing code. A block marked mermaid is drawn as a diagram by GitHub and by DotMD, as long as the syntax is valid.

Checking the colors

The quickest test of a language tag is to open the file in a reader. DotMD colors fenced blocks with highlight.js in light and dark themes and shows a Copy button when you hover a block. Reading is free, and the Markdown cheat sheet has the rest of the syntax on one page.

Questions about code blocks in Markdown

More questions