Code block essentials

Many code blocks are harder to use than they need to be: no language, no filename, and no indication of which part matters. These details are small, but fixing them makes examples much easier to follow.

Why specify a language?

Mintlify uses the language identifier after the opening backticks to apply syntax highlighting. Without it, the code renders as plain monospace text.

Example with and without a language tag

{/* No highlighting. Harder to scan */}
```
npm install @acme/sdk
```

{/* Highlighted correctly */}
```bash
npm install @acme/sdk
```

npm install @acme/sdk

npm install @acme/sdk

Syntax highlighting reduces the cognitive load of reading code. Readers can see at a glance where strings end, where keywords are, and what’s a variable versus a value. Include a language on every fenced block. Common identifiers include:

Shell and commands: bash, sh, powershell
Languages: python, javascript, typescript, go, ruby, java, sql
Data and config: json, yaml, toml
Markup and styles: mdx, html, css
Plain output: text

Filenames and titles

A filename tells readers where this code lives in their project. A title tells them what it does if a filename doesn’t apply.

Example code block with a filename

```json docs.json
{
  "theme": "sequoia",
  "name": "My Docs"
}
```

The filename docs.json appears as a label on the code block. Readers know immediately that this is what goes in the docs.json file. Use a filename when the code belongs in a specific file. Use a descriptive title when the code is a command or snippet without a natural filename.

Example code block with a descriptive

```bash Install dependencies
npm install
```

Draw attention to the lines that matter

When a code block is long and you want to emphasize a few lines, use highlight with the line numbers or ranges.

Example line highlighting

```python highlight={3}
import os

API_KEY = os.environ.get("API_KEY")  # This line is highlighted

client = Client(api_key=API_KEY)
```

import os

API_KEY = os.environ.get("API_KEY")  # This line is highlighted

client = Client(api_key=API_KEY)

Use highlighting sparingly. If you highlight most of a code block, nothing stands out. Two related options help in specific cases:

focus dims every line except the ones you name. Use it when the surrounding lines are context the reader needs to see but not study.
Diff markers show lines as added or removed. Add [!code ++] or [!code --] in a comment at the end of a line. Use them when you’re showing a change to existing code, like an upgrade guide.

Example diff

const client = new Acme({ apiKey: "YOUR_API_KEY" }); 
const client = new Acme({ apiKey: process.env.ACME_API_KEY }); 

The copy button

Mintlify adds a copy button to code blocks automatically. Users running commands from documentation expect to paste them directly. If the code has a trailing space, a curly quote instead of a straight quote, or wraps in a way that introduces a line break, the command won’t run and users won’t know why. Write commands exactly as they should be typed without extra spaces or decorative characters. Test them before publishing. Some code blocks aren’t meant to be copied, like terminal output or an ASCII diagram. Add nocopy to hide the copy button so readers don’t paste output as if it were a command.

Keep examples short

Code blocks that contain more than the reader needs force them to figure out which parts apply and which are setup they already did. When showing a configuration change, show only the relevant section, and tell readers where it goes.

Example of only part of a config file

Add `primary` inside the `colors` object in your `docs.json`:

```json docs.json
"colors": {
  "primary": "#166E3F"
}
```

When a complete example really is long, like a full configuration file, add expandable so the block starts collapsed and readers can open it if they need the whole thing. Next up: When to explain code and when to just show it—how to place code blocks within explanations so readers understand what to do and why.

Overview

Call out important information

Guide users through a process

Share sample code

Present content that varies by environment or stack

Show a comparison of options

Document APIs

Add visual context

Direct users to related content

Use supporting components

Why specify a language?

Filenames and titles

Draw attention to the lines that matter

The copy button

Keep examples short

​Why specify a language?

​Filenames and titles

​Draw attention to the lines that matter

​The copy button

​Keep examples short

Why specify a language?

Filenames and titles

Draw attention to the lines that matter

The copy button

Keep examples short