Markdown code blocks

Markdown has two ways to mark code: inline code inside a sentence, and code blocks that stand on their own. Inside both, Markdown syntax is switched off. Asterisks, underscores and backslashes appear exactly as you typed them.

Inline code

Wrap the text in backticks.

Run `npm install` and then open `package.json`.

Result:

Run npm install and then open package.json.

Nothing inside is treated as Markdown, and a backslash does not escape anything.

The pattern `*.md` and the path `C:\temp` stay as typed.

Result:

The pattern *.md and the path C:\temp stay as typed.

Backticks inside inline code

A code span ends at the next run of backticks with the same length as the opening run. So to include a backtick, open and close with two backticks.

Use ``a`b`` for a single backtick inside code.

Result:

Use a`b for a single backtick inside code.

If the content starts or ends with a backtick, add one space on each side. Markdown removes that one space.

Type `` `code` `` to get inline code.

Result:

Type `code` to get inline code.

Fenced code blocks

Put a line with three backticks before the code and another one after it. These lines are called fences.

```
function add(a, b) {
  return a + b;
}
```

Result:

function add(a, b) {
  return a + b;
}

The rules:

• A fence is three or more backticks, or three or more tildes (~).
• The closing fence must use the same character and be at least as long as the opening fence.
• Line breaks and indentation inside the block are kept as they are.
• If you forget the closing fence, the block runs to the end of the document.
• A fenced block can follow a paragraph directly. No blank line is needed, but one makes the source easier to read.

Tilde fences

Tildes work the same way as backticks.

~~~
plain text here
~~~

Result:

plain text here

Language tags

Write a language name right after the opening fence. The spec calls this the info string. Apps use its first word to pick the syntax highlighting.

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

Result:

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

The Markdown specs do not define a list of language names. The highlighter in each app decides. Short names such as js, python, bash, json, html, css and diff are widely supported. If a name is unknown, most apps show the block without colours.

Fences inside fences

To show a fenced block as text, for example in documentation about Markdown, make the outer fence longer than the inner one.

````markdown
```js
console.log("hi");
```
````

Result:

```js
console.log("hi");
```

A tilde fence around a backtick fence works too, because a closing fence must use the same character as the opening one.

Indented code blocks

The original way to write a code block is to indent every line by four spaces or one tab. Leave a blank line before the block.

Check the state of the repository:

    git status
    git log --oneline

Result:

Check the state of the repository:

git status
git log --oneline

Indented blocks have limits:

• They cannot carry a language tag.
• They cannot interrupt a paragraph. Without the blank line, the indented lines become part of the paragraph.
• Inside a list item, the four spaces count from the start of the item’s text, not from the left margin. This is easy to get wrong.

For new documents, fenced blocks are the better choice.

Where it works

Inline code, fenced blocks with backticks or tildes, info strings and indented blocks are all part of CommonMark. GitHub Flavored Markdown (GFM) uses the same rules and adds nothing here. So the syntax on this page works in GitHub, GitLab, Obsidian, VS Code and any other app that follows CommonMark.

Syntax highlighting is the part that differs. It is not in the spec. GitHub, GitLab, Obsidian and the VS Code preview all highlight fenced blocks with a language tag, but each supports its own set of languages and names. For an unusual language, check your app.

To read a Markdown file without the backticks, Markko shows .md files formatted on a Mac and in Quick Look.

FAQ

Related