Markdown Code Blocks: Syntax Highlighting and Inline Code

Code is the part of technical writing that has to look right. Markdown gives you two tools for it: short snippets inline with your sentences, and standalone blocks for longer examples. Adding a language hint turns a plain monospaced box into color-coded prose, which is what most readers expect. This guide covers markdown code block syntax highlighting end to end — backticks, language hints, nesting, escaping, and the small habits that keep your docs tidy.

Inline code vs fenced blocks

For a word or two of code inside a sentence, wrap the text in single backticks. The output renders in a monospaced font, set apart from body text:

Use the `git status` command to inspect your working tree.

For anything longer than a line — a full command, a function, a config snippet — use a fenced block with triple backticks. The block keeps its line breaks and indentation intact:

```
git add .
git commit -m "Initial commit"
```

The rule of thumb: one token, use inline backticks; a full example, use a fence.

Add a language hint for syntax highlighting

A bare fence is just monospaced text. To get markdown code block syntax highlighting, put a language identifier right after the opening backticks (no space). The renderer then colors keywords, strings, comments, and numbers according to that language.

function greet(name) {
  return `Hello, ${name}!`;
}

The source for that block is:

```js
function greet(name) {
  return `Hello, ${name}!`;
}
```

Common language hints

Language hint	Use case
js / javascript	Frontend and Node.js code
ts / typescript	Typed JavaScript, config types
py / python	Scripts, data science, ML
bash / sh	Shell commands, install steps
json	Config files, API responses
yaml / yml	CI pipelines, cloud config
html	Markup examples
css	Styling snippets
sql	Database queries
md	Markdown showing Markdown

When in doubt about a hint, check the full Markdown cheat sheet for a quick reminder of which identifiers most viewers support.

Why syntax highlighting helps readability

Color is not decoration — it carries information. A good highlighter separates structure (keywords, operators) from data (strings, numbers) from noise (comments), so readers can scan a snippet and grasp its shape in seconds.

• Keywords pop, so control flow and declarations are obvious.
• Strings stand out, which makes literals and messages easy to find.
• Comments recede, signaling "explanation, not executable code".
• Errors are easier to spot, because a missing quote breaks the color pattern visibly.

For tutorials and API docs this matters doubly: readers copy examples verbatim, and highlighting helps them see which parts to change versus keep.

Nested backticks: four when you need three

Code blocks are delimited by triple backticks, so what happens when your example contains triple backticks — for instance, when you are documenting Markdown itself? The rule: a fence can be any run of three or more backticks, and a closing fence must match the length of the opening fence. To wrap a block that contains triple backticks, open and close with four.

````md
```js
const example = "contains three backticks inside";
```

The four-backtick fence above renders as a single code block whose content
includes a three-backtick fence. The same length-matching rule applies to inline
code: to show a single backtick inline, wrap it in double backticks —
`` `` `code` `` `` renders as `` `code` ``.

## Escaping and special cases inside code

Inside a code block, everything is literal. Backslashes, asterisks, angle
brackets, and dollar signs all render exactly as typed — Markdown formatting is
disabled between the fences. That is usually what you want, but a few cases trip
people up:

- **Leading whitespace is preserved.** Indented code inside a fence stays
  indented, which is great for YAML but means accidental leading spaces show up.
- **No inline Markdown inside a block.** `**bold**` inside a fence displays as
  literal asterisks, not bold text.
- **Tabs vs spaces.** Mix them and alignment can shift when a reader's font
  differs. Pick one (spaces are safest) and stick with it.
- **Very long lines** may overflow horizontally. Most viewers add a scrollbar,
  but try to keep examples narrow enough to read.

> Quick check: if your block looks wrong, paste it into the
> [MD Viewer](/md-viewer) to see exactly how a standards-aware renderer
> interprets it.

## Tips for clean code blocks

A few small habits keep code examples readable across every viewer and theme:

- **Keep fences flush-left.** Indented fences can be mistaken for indented code
  blocks in some parsers, producing odd output.
- **Add a blank line before and after each block.** This guarantees the parser
  treats the fence as a standalone block rather than run-on text.
- **Always include a language hint** when the content is real code. Even `text`
  is better than nothing — it signals "this is preformatted, don't touch it".
- **Match the closing fence length** to the opening one, especially when nesting.
- **Strip trailing whitespace** on each line to avoid unexpected indentation in
  the rendered output.

### A copy-pasteable template

````md
```js
// Describe what this does in one line.
function add(a, b) {
  return a + b;
}
```

Drop this into the homepage editor or open the full file in the MD Viewer to confirm the highlighting renders as expected before you publish.

Key takeaways

• Use single backticks for inline code and triple backticks for fenced blocks; the fence length must match.
• Add a language hint (```js, ```py, ```bash) right after the opening fence to enable syntax highlighting.
• Highlighting improves readability by separating keywords, strings, comments, and data at a glance.
• To show triple backticks inside a block, wrap the whole thing in a four-backtick fence.
• Keep fences flush-left, surround blocks with blank lines, and always pick a language hint — even text.

Write your next doc in the MD Viewer and watch your code blocks highlight live as you type.