Quotes, captions, names, wishes & practical how-tos

Markdown Basics

Markdown Code Blocks and Inline Code Explained

Students in a computer programming class, an example setting for markdown code blocks
Photo: Wikideas1, CC0, via Wikimedia Commons

A markdown code block is created by wrapping text in triple backticks, or by indenting every line with four spaces. For a short snippet inside a sentence, use single backticks for inline code. This guide covers fenced and indented blocks, language labels for syntax highlighting, and how to show backticks themselves.

Key takeaways

  • Fenced blocks use three backticks (or three tildes) above and below the code.
  • Add a language name after the opening fence for syntax highlighting where supported.
  • Inline code uses single backticks and keeps formatting literal.
  • Use longer fences or double backticks to show backticks inside code.

Inline Code With Single Backticks

Surround a word or short command with one backtick on each side. The text is shown in a monospace font and Markdown symbols inside it are not interpreted.

Run `git status` to see changed files.
Use `*` for bullets, not `**`.

Inline code is ideal for file names, function names, keyboard keys and short commands. It protects characters such as asterisks and underscores from being turned into emphasis.

Fenced Markdown Code Block Syntax

For several lines, put three backticks on a line of their own, paste the code, then close with three more backticks. This is the “fenced” style, part of GitHub Flavored Markdown and supported by CommonMark.

```
line one
line two
```

Keep the closing fence at least as long as the opening one and on its own line. Three tildes (~~~) work as an alternative fence in tools that follow CommonMark. Leave a blank line before and after the block so surrounding paragraphs are not pulled in, and do not indent the fences unless the block sits inside a list item.

Programmer writing code that would sit inside a markdown code block in documentation
Photo: daudi_mukiibi, CC BY-SA 4.0, via Wikimedia Commons (source)

Add a Language for Syntax Highlighting

Write a language name directly after the opening fence. Many renderers use it to color the code.

```python
def greet(name):
    return "Hello, " + name
```

Common labels include python, javascript, bash, json, html and css. Whether highlighting happens depends on the platform. The label is still harmless when the tool ignores it, so it is a good habit. Check the documentation of your site or editor for the list of supported names.

Indented Code Blocks

The older style indents each line by four spaces or one tab, with a blank line before the block.

    total = price * quantity
    print(total)

This works in virtually every Markdown processor, including very old ones, but it has no way to name a language, and an accidental indent can turn normal text into a code block. Most writers prefer fences for that reason.

A few habits make any markdown code block easier to use. Keep examples short and runnable so readers can copy them without edits. Use spaces or tabs consistently, because mixed indentation looks broken once rendered. Put the explanation above the block rather than as comments buried inside it, and avoid pasting screenshots of code, which cannot be searched or copied. For terminal commands, leave out the prompt symbol so people can paste the line straight into a shell. If the output of a command matters, show it in a second block so readers can tell input from result.

How to Show Backticks Inside Code

  1. For inline code that contains one backtick, wrap it in double backticks and add a space inside each end.
  2. For a fenced block that contains triple backticks, open and close it with four backticks, or use tildes.
  3. Preview the result to confirm the inner backticks appear literally.
`` `code` ``

Code Blocks Inside Lists and Quotes

To place a block inside a list item, indent the fences to match the text of the item and keep a blank line before the block. Inside a block quote, begin every line, including the fences, with >. When the block fails to render, misaligned indentation is the usual cause. For more on list indentation, see our guide to Markdown lists.

Software developer reviewing code, the kind of content shown in a markdown code block
Photo: Tsinkala, CC BY-SA 4.0, via Wikimedia Commons (source)

Comparison: Inline, Fenced and Indented Code

Style Syntax Best for Language label
Inline Single backticks Names, short commands No
Fenced Triple backticks or tildes Multi-line examples Yes
Indented Four spaces Legacy documents No

The GitHub Flavored Markdown specification defines these forms precisely. If you convert a document that contains code, the target format matters; converting Markdown to HTML wraps blocks in <pre> and <code> tags, and you can style them with CSS.

Frequently Asked Questions

How do I type a backtick on my keyboard?

On many US keyboards it sits at the top left, below Esc and left of the 1 key. Layouts differ, so look up your own layout if you cannot find it.

Why is my code not highlighted?

The platform may not support highlighting, or the language label may be misspelled or unsupported. The code still displays correctly in monospace.

Can I use bold or links inside a code block?

No. Everything inside a code block or inline code span is literal, which is exactly why it is used for code.

What is the difference between ``` and ~~~?

Both open a fenced block. Backticks are far more common, and tildes help when your code itself contains backticks.

Can I add a file name to a code block?

Core Markdown has no field for it. Some tools support extra attributes after the language, but this is not standard, so write the file name in the text above the block.

Wrap-Up

Use single backticks for short snippets, triple backticks with a language for blocks, and four spaces only for legacy files. Preview your page, and remember that highlighting depends on the platform.

Written byEditorial Team

Part of the MarkdownToGoogleDocs editorial team, sharing copy-ready words and practical Markdown and Google Docs how-tos.