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

# Code block essentials

> A few small choices in how you write code blocks determine whether users can actually follow along.

export const Quiz = ({question, answers, correctFeedback, incorrectFeedback}) => {
  const [selected, setSelected] = React.useState(null);
  const [checked, setChecked] = React.useState(false);
  const quizId = React.useId();
  const isCorrect = checked && answers[selected]?.correct;
  const reset = () => {
    setSelected(null);
    setChecked(false);
  };
  return <div className={"quiz-container" + (checked ? " quiz-checked" : "")}>
      <Badge color="green">Quiz</Badge>
      <p className="quiz-question" id={quizId + "-question"}>{question}</p>
      <div className="quiz-options" role="radiogroup" aria-labelledby={quizId + "-question"} aria-disabled={checked}>
        {answers.map((answer, i) => <label key={i} className={["quiz-option", !checked && selected === i ? "quiz-option-selected" : "", checked && answer.correct ? "quiz-option-correct" : "", checked && selected === i && !answer.correct ? "quiz-option-incorrect" : ""].filter(Boolean).join(" ")}>
            <input type="radio" name={"quiz-" + quizId} checked={selected === i} onChange={() => !checked && setSelected(i)} disabled={checked} />
            <span className="quiz-radio" />
            <span className="quiz-option-label">{answer.text}</span>
          </label>)}
      </div>
      {checked && <div className={"quiz-feedback " + (isCorrect ? "quiz-feedback-correct" : "quiz-feedback-incorrect")} role="status" aria-live="polite" aria-atomic="true">
          <span className="quiz-feedback-icon">{isCorrect ? "✓" : "✗"}</span>
          {isCorrect ? correctFeedback : incorrectFeedback}
        </div>}
      <div className="quiz-actions">
        {!checked ? <button className="quiz-btn quiz-btn-check" type="button" onClick={() => selected !== null && setChecked(true)} disabled={selected === null}>
            Check answer
          </button> : <button className="quiz-btn quiz-btn-reset" type="button" onClick={reset}>
            Try again
          </button>}
      </div>
    </div>;
};

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.

````mdx Example with and without a language tag theme={null}
{/* No highlighting. Harder to scan */}
```
npm install @mintlify/sdk
```

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

<CodeGroup>
  ```a Not highlighted theme={null}
  npm install @mintlify/sdk
  ```

  ```bash Highlighted correctly theme={null}
  npm install @mintlify/sdk
  ```
</CodeGroup>

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.

````mdx Example code block with a filename theme={null}
```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.

````mdx Example code block with a descriptive title theme={null}
```bash Install dependencies
npm install
```
````

## Line highlighting

When a code block is long and you want to emphasize a few lines, use line highlighting.

````mdx Example line highlighting theme={null}
```python {3}
import os

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

client = Client(api_key=API_KEY)
```
````

```python {3} theme={null}
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.

````mdx Example of only part of a config file theme={null}
```json docs.json
{
  // Add this inside your existing "colors" object
  "primary": "#166E3F"
}
```
````

<Quiz
  question="A code block shows a Python function with 20 lines. Three lines configure an environment variable. The rest is standard SDK setup the user completed two steps ago. What should you do?"
  answers={[
{ text: "Show all 20 lines for completeness. Users need the full context.", correct: false },
{ text: "Show only the three relevant lines, with a comment indicating where they go.", correct: true },
{ text: "Show all 20 lines and use line highlighting on the three important ones.", correct: false },
{ text: "Move the three lines to a callout instead of a code block.", correct: false },
]}
  correctFeedback="Right. Showing the full 20 lines forces readers to parse what they've already seen. Show only the three lines that matter, with a comment like `# Add inside your configure() function`. Highlighting helps but doesn't solve the problem of making users scan past content they don't need."
  incorrectFeedback="Showing the full 20 lines requires users to find the relevant part themselves. Line highlighting helps draw the eye but still exposes 17 lines of noise. The cleaner approach is to show only what's new, with a comment explaining where it belongs."
/>

<Check>
  Next up: [Code in context](/courses/components/code-in-context) — How to place code blocks within explanations so readers understand what to do and why.
</Check>