Markdown Code Blocks & Syntax Highlighting Guide

Code is a first-class citizen in Markdown. Whether you're documenting an API, posting a bug report, or writing a tutorial, knowing exactly how to format code means your samples render cleanly everywhere — in a GitHub README, a static site, or an exported Word document. This guide covers everything from inline snippets to syntax highlighting and nested fences.

Inline code vs fenced blocks

Use inline code for short identifiers, function names, file paths, or anything you want to render in monospace. Wrap it in single backticks.

Run `npm install` and open `src/index.js`.

Use fenced code blocks for anything longer than a single line. A block preserves line breaks, indentation, and special characters exactly as you typed them.

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

Rule of thumb: if it fits on the line of prose, use inline code. If it stands alone as a sample, use a block.

Two styles of fence

Triple backticks

The most common fence, supported by virtually every GFM renderer.

```python
print("hello")
```

Tilde fences

GFM also accepts one or more tildes. This matters when your code sample itself contains triple backticks — you can wrap it in tildes (or four backticks) without escaping anything.

~~~bash
echo "no escaping needed for `backticks` inside"
~~~

The opening and closing fence must use the same character and have the same or greater length than the opening fence.

Language tags and syntax highlighting

The word immediately after the opening fence is the info string. The first token of that string is the language tag, which most renderers use to apply syntax highlighting.

```ruby
puts "highlighted as Ruby"
```

If you omit the tag, you get plain monospace with no coloring. When the tag is correct, you get readable, color-coded output like the examples throughout this article.

Common language tags

The diff trick

Tag a block as diff to color lines green for additions (+) and red for deletions (-). Many renderers, including GitHub, render this out of the box.

```diff
- const old = require('fs');
+ import fs from 'node:fs';
```

Plain text when you want no color

If a sample shouldn't be colored (a log file, terminal output, a literal Markdown snippet), use text or leave the info string empty.

Escaping and nesting

Four-space indented blocks (legacy)

Before fences existed, you indented code by four spaces or one tab. It still works, but fences are preferred because they support language tags and are easier to read in source. Avoid four-space blocks for new writing unless you're targeting a very old parser.

Nesting fences inside fences

When your sample is Markdown (or any code containing backticks), bump the outer fence to four backticks or use tildes.

````md
```js
console.log("a fence inside a fence");
```

The outer fence is four backticks, so the inner three-backtick fence is shown literally. This is the standard pattern for documenting Markdown itself.

### Tildes inside backtick fences

Mixing fence characters is the cleanest way to show a fence without escaping.

````md
```md
~~~js
// shown literally inside a backtick fence
~~~
```

Escaping inside inline code

You can't always escape inside inline code with backslashes — backticks are literal there. To show a backtick inside inline code, wrap the snippet in double backticks and pad with spaces.

A single `` ` `` character, inline.

Tips for long code

• Keep lines under ~80 characters so they don't overflow sidebars and printed pages.
• Tag every block; even text is better than nothing for predictability.
• Strip sensitive data (API keys, internal hosts) before pasting.
• Add a comment at the top of each block explaining what it does.
• Prefer complete, runnable snippets over fragments whenever space allows.

A short annotated block beats a long uncommented one:

```bash
# install dependencies and start the dev server
npm install
npm run dev
```

Exporting highlighted code

Highlighted code in Markdown is only useful if it survives the trip to your target format. Here's how each common export handles it.

• HTML — preserves spans and CSS classes for syntax colors, so highlighting renders exactly as in the live preview. Use the Markdown to HTML converter to ship highlighted samples to the web.
• PDF — colors and monospace font are baked into the layout, ideal for printable handouts and reports. Try the Markdown to PDF tool.
• Word (.docx) — code lands in styled paragraphs with a monospace font; reviewers can comment and track changes without breaking formatting. Paste your source into the Markdown to Word converter and download.

For all three, the rule is the same: tag your blocks correctly in source and the highlighter does the rest.

Wrapping up

Get these basics right and your code samples will look consistent everywhere: use inline code for short identifiers, fenced blocks for samples, a language tag for highlighting, and a longer outer fence when you need to nest. When you're ready to publish, the Markdown to HTML converter turns your highlighted blocks into clean, web-ready markup in seconds.