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 fences of three 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 closing fence must use the same character as the opening fence and contain at least as many characters.

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"
```

A language tag is a hint to a highlighter, not a guarantee of colors. This site displays monospaced code without syntax coloring. A destination such as GitHub or a documentation site may apply its own highlighter.

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
~~~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 code from this site

This converter preserves code content and basic monospaced formatting, but it does not add syntax colors. Check each output for its intended use.

• HTML — retains <pre><code> and a language class when supplied. Add a syntax-highlighting library and its stylesheet at the destination if you need colors. Use Markdown to HTML to inspect the generated markup.
• PDF — captures monospaced code as part of image-based pages. Long lines wrap, and there is no selectable text layer. Use a different PDF workflow if readers need to copy runnable code.
• 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.

Keep language tags in the source for tools that use them, but verify whether the destination actually includes a highlighter.

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 publishing through Markdown to HTML, inspect the generated code markup and configure any desired syntax colors on the destination site.