Markdown Code Blocks and Syntax Highlighting Explained

A Markdown code block is a chunk of text rendered in a monospace font with formatting preserved, and you create one either by wrapping short snippets in single backticks for inline code or by wrapping whole blocks in three backticks for a fenced code block. That is the whole idea. The rest is knowing which style fits where, and how to add language syntax highlighting so your code shows up with color.

This guide covers every case you will hit: inline code, fenced versus indented blocks, highlighting by language, GitHub Flavored Markdown support, escaping stray backticks, and nesting code inside lists, tables, and blockquotes.

Inline code with backticks

Wrap a word or short phrase in single backticks to render it as inline code. Use it for file names, function names, flags, and values inside a sentence.

Run `npm install`, then edit the `astro.config.mjs` file.

That renders as: Run npm install, then edit the astro.config.mjs file. The backticks disappear and the wrapped text switches to a monospace font. Inline code markdown does not add syntax highlighting, it only changes the font and (in most themes) the background.

Keep inline code to short fragments. If you are showing more than one line, or a full command with output, reach for a fenced code block instead.

Fenced code blocks vs indented code blocks

There are two ways to write a multi-line code block. Fenced is the one you should use.

A fenced code block wraps your code in a line of three backticks above and below:

```
function greet(name) {
  return "Hello, " + name;
}
```

An indented code block uses four spaces of indentation at the start of each line instead of fences:

    function greet(name) {
      return "Hello, " + name;
    }

Both render the same monospace block, but fenced blocks win in practice. They read clearly in the raw source, they do not break when your code already contains indentation, and only fenced blocks accept a language label for syntax highlighting. Indented blocks are older CommonMark syntax and have no way to declare a language. Use fences unless you have a specific reason not to.

One tip: if the code you are showing itself contains three backticks (for example, you are writing about Markdown), open and close the outer block with four backticks instead. The parser matches the longer fence, so the inner triple backticks stay literal.

Adding syntax highlighting by language

To turn on markdown syntax highlighting, write the language name right after the opening three backticks, with no space:

```js
const total = items.reduce((sum, x) => sum + x.price, 0);
```

The js label (an “info string”) tells the renderer to color keywords, strings, and numbers using a highlighter like Prism, highlight.js, or Shiki. Common labels include js, ts, python, bash, json, html, css, sql, and yaml. Most highlighters accept aliases too, so javascript and js both work.

If you leave the label off, you still get a plain monospace block with no color. If you use a label the highlighter does not recognize, most engines fall back to plain text rather than erroring, so a typo like pythonn just means no colors.

GitHub Flavored Markdown highlighting support

GitHub Flavored Markdown (GFM) is the dialect GitHub uses in READMEs, issues, pull requests, and comments. For github flavored markdown code, the fenced-block syntax is identical: three backticks, then the language name.

```python
def total(items):
    return sum(item.price for item in items)
```

GitHub highlights hundreds of languages using the Linguist library, which powers the same grammar it uses to detect languages across a repository. If you are unsure of the exact label, check the Linguist languages list. GFM also supports the tilde fence (~~~) as an alternative to backticks, which is handy when your code contains backtick sequences.

Escaping backticks and nesting code in lists

Two things trip people up: showing a literal backtick, and putting a code block inside a list item.

To show a literal backtick as inline code, wrap it in a longer run of backticks. Two backticks on the outside let a single backtick live inside:

Use `` ` `` to start inline code.

The rule is simple: the outer fence must be longer than any backtick run inside it. Add a space just inside each end if your content starts or ends with a backtick, and the renderer trims that padding space for you.

Nesting a fenced block inside a list needs consistent indentation. Indent the entire fenced block to line up with the text of the list item, which is usually three or four spaces for an ordered or bulleted list:

1. Install the dependency:

npm install qrcode

2. Import it in your script.

If the fence is not indented to match the list item, the parser closes the list early and your block ends up outside it. When a code block “escapes” a list, misaligned indentation is almost always the cause.

Code blocks inside tables and blockquotes

Blockquotes handle code well. Prefix each line, including the fences, with >:

> Here is the fix:
>
> ```js
> clearTimeout(timer);
> ```

Tables are the awkward case. Markdown table cells cannot contain a fenced code block, because a table row must stay on a single line and fences need their own lines. Inside a table cell you are limited to inline code with single backticks:

| Command      | What it does        |
| ------------ | ------------------- |
| `npm run dev`| Starts the dev server |

If you genuinely need a multi-line block in a table, that is a sign the content wants a real table plus a separate code block below it, or an HTML table if your platform allows raw HTML. Speaking of tables: if you are hand-building Markdown tables from spreadsheet data, our CSV to Markdown converter turns a pasted CSV into a clean table in one step, so you can focus on the prose around it.

Troubleshooting: highlighting not working

If your fenced code block renders as plain text with no color, work through these in order:

• No language label. The most common cause. Add the language right after the opening fence, like ```js, with no space between the backticks and the name.
• A space after the backticks. ``` js (with a space) is not a valid info string on some parsers. Remove the space.
• Unrecognized label. Check the highlighter supports that language. A typo or an obscure alias falls back to plain text.
• No highlighter loaded. Plain CommonMark does not highlight anything by itself. The color comes from a separate library (Prism, highlight.js, Shiki) plus a theme stylesheet. If neither is present, you get monospace with no color, which is expected.
• Unbalanced fences. A missing or mismatched closing fence swallows the rest of your document into one giant block. Count your backticks: the closing fence must match the opening one in length and character.

FAQ

What is the difference between inline code and a code block? Inline code uses single backticks and sits inside a sentence for short fragments like a file name. A code block uses three backticks (or four-space indentation) and stands on its own lines for multi-line snippets. Only fenced code blocks support a language label for highlighting.

How do I add syntax highlighting in Markdown? Write the language name directly after the opening three backticks, for example ```python. A highlighter such as Prism or highlight.js reads that label and colors the code. Without a label, or without a highlighter loaded on the page, the block renders as plain monospace.

How do I show a literal backtick in Markdown? Wrap it in a longer run of backticks than the content contains. To show one backtick, surround it with two: ` . If your content starts or ends with a backtick, add a single space just inside each fence and the renderer trims it.

Can I put a code block inside a Markdown table? Not a fenced one. Table cells stay on a single line, so you are limited to inline code with single backticks inside a cell. For a multi-line block, place it outside the table or use an HTML table if your platform renders raw HTML.

If you want to go deeper on the rest of the syntax, see our full Markdown syntax guide and the companion piece on adding links and images. And if you are deciding whether to write in Markdown or raw HTML for a given page, Markdown vs HTML walks through the tradeoffs.