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 supported language identifier after the opening backticks. Whitespace before the information string is allowed. Highlighting is an application feature; the Markdown parser itself only identifies the code block.

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 use the same character and contain at least as many markers as 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 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.
• Use blank lines for readable source. They separate examples clearly, although CommonMark does not require them around every fenced block.
• 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

```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. A closing fence must use the same marker and be at least as long as the opening fence.
• 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.