Skip to main content

Documentation Index

Fetch the complete documentation index at: https://learn.mintlify.com/llms.txt

Use this file to discover all available pages before exploring further.

Most documentation includes code blocks that are harder to use than they need to be: no language specified, no filename, no indication of which part matters. These are small details, but they have an outsized effect on whether users can follow along without frustration.

​
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 @mintlify/sdk
```

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

npm install @mintlify/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
  • Languages: python, javascript, typescript, go, ruby, java, sql
  • Data and config: json, yaml
  • Docs and markup: mdx, css

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

​
Line highlighting

When a code block is long and you want to emphasize a few lines, use line highlighting.
Example line highlighting
```python {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.

​
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.

​
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. Add comments to orient the reader.
Example of only part of a config file
```json docs.json
{
  // Add this inside your existing "colors" object
  "primary": "#166E3F"
}
```
Next up: Code in context — How to place code blocks within explanations so readers understand what to do and why.