<!-- https://ewels.github.io/starlight-codeblocks/ -->

# starlight-codeblocks

> A Starlight plugin that adds focus, line states, annotations, API auto-linking and 22 more features to the code blocks of a site.

This plugin adds 26 features to the [Expressive Code](https://expressive-code.com) blocks of [Starlight](https://starlight.astro.build). Use them to enrich code blocks, they're perfect for docs and training. Using an agent? [Point it at the bundled skill](https://ewels.github.io/starlight-codeblocks/agent-skill/).

## Features

### Explain code

- [Annotations](https://ewels.github.io/starlight-codeblocks/features/annotations/): Add numbered markers to lines. Each marker opens a note in a popover, so the code stays clean until a reader asks.
- [Side annotations](https://ewels.github.io/starlight-codeblocks/features/side-annotations/): Show the notes of an annotated block in a column beside the code, so readers see every note next to its line.
- [Footnotes](https://ewels.github.io/starlight-codeblocks/features/footnotes/): Add numbered badges to lines, with the notes in a list under the block, where readers see them all at once.
- [Inline callouts](https://ewels.github.io/starlight-codeblocks/features/inline-callouts/): Put a short note in a bubble above a line, with an arrow that points at the word it explains.
- [Scrollycoding](https://ewels.github.io/starlight-codeblocks/features/scrollycoding/): Explain a code block in prose steps that scroll past it, while the block stays in view and focuses the lines of each step.
- [Code walkthrough](https://ewels.github.io/starlight-codeblocks/features/code-walkthrough/): Step through versions of one code block, and watch the code move from each version to the next, so readers see what changed.

### Draw attention

- [Focus](https://ewels.github.io/starlight-codeblocks/features/focus/): Blur the lines outside a range, so that readers look at the lines that you name first.
- [Line states](https://ewels.github.io/starlight-codeblocks/features/line-states/): Tint lines as errors, warnings, notes or successes, with an optional message after the code, like the diagnostics in a code editor.
- [Code mentions](https://ewels.github.io/starlight-codeblocks/features/code-mentions/): Link a phrase in the prose to lines of the code block below it, so that readers see which lines the text is about.

### Make code easier to read

- [Hidden lines](https://ewels.github.io/starlight-codeblocks/features/hidden-lines/): Hide the imports and set-up that readers need to run an example but not to understand it.
- [Expandable blocks](https://ewels.github.io/starlight-codeblocks/features/expandable-blocks/): Show the first lines of a long block, with a fade and a button to reveal the rest.
- [Visible whitespace](https://ewels.github.io/starlight-codeblocks/features/visible-whitespace/): Show spaces and tabs as faint glyphs, for the blocks where indentation changes the meaning of the code.
- [Colourised brackets](https://ewels.github.io/starlight-codeblocks/features/colourised-brackets/): Colour matching brackets by nesting depth, so a dense line of code stays readable.
- [Colour swatches](https://ewels.github.io/starlight-codeblocks/features/colour-swatches/): Show a small swatch of each CSS colour next to its value, so readers see the colour without a colour picker.
- [File icons](https://ewels.github.io/starlight-codeblocks/features/file-icons/): Show the icon of the file type before the title of a code block, with the icons of the Starlight file tree or a coloured icon set.
- [Inline code highlighting](https://ewels.github.io/starlight-codeblocks/features/inline-code-highlighting/): Give inline code in the prose the syntax colours of the code blocks, from a language suffix or a default language for the site.
- [Word-level diff](https://ewels.github.io/starlight-codeblocks/features/word-level-diff/): Highlight the words that changed inside each line of a diff, so readers find a small edit in a long line.

### Link code

- [Code links](https://ewels.github.io/starlight-codeblocks/features/code-links/): Turn text in code into a link with a card that describes it, from a directive in the comment above.
- [API auto-linking](https://ewels.github.io/starlight-codeblocks/features/api-auto-linking/): Link the names in code examples to their reference pages, with a card that shows the signature and a summary.
- [Line permalinks](https://ewels.github.io/starlight-codeblocks/features/line-permalinks/): Give a code block line numbers that link to each line, so readers can share a link to the exact lines they mean. Shift-click to select multiple lines.

### Adapt to the reader

- [Code tabs](https://ewels.github.io/starlight-codeblocks/features/code-tabs/): Show several code blocks as one, with editor tabs in the title bar, such as the files of a project or the commands for each package manager.
- [Fill-in placeholders](https://ewels.github.io/starlight-codeblocks/features/fill-in-placeholders/): Turn placeholders such as YOUR_TOKEN into fields, so readers type their own values into every block and the copied code.

### Copy and run

- [Smart shell copy](https://ewels.github.io/starlight-codeblocks/features/smart-shell-copy/): Add a Copy commands button to terminal blocks, which copies the commands without the prompts or the output.
- [Open in playground](https://ewels.github.io/starlight-codeblocks/features/open-in-playground/): Add a title bar button that opens the example in an online playground, with the code already filled in.
- [Run code](https://ewels.github.io/starlight-codeblocks/features/run-code/): Add a Run code button that runs the example in the browser and shows the output under the block.

## Install

Add the package to the site:

:::code-tabs{sync="pm"}
```sh label="npm"
npm install starlight-codeblocks
```
```sh label="pnpm"
pnpm add starlight-codeblocks
```
```sh label="Yarn"
yarn add starlight-codeblocks
```
:::

Then add `codeblocks()` to the Starlight plugins in `astro.config.mjs`:

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';
import codeblocks from 'starlight-codeblocks'; // [!code focus ++] Import the plugin

export default defineConfig({
  integrations: [
    starlight({
      title: 'My docs',
      plugins: [codeblocks()], // [!code focus ++] Load the plugin
    }),
  ],
});
```

The [getting started](https://ewels.github.io/starlight-codeblocks/getting-started/) page has the full steps.

## Extend and reference

- [Extend](https://ewels.github.io/starlight-codeblocks/extend/write-an-api-link-adapter/): your own API link adapters, playgrounds and runtimes.
- [Reference](https://ewels.github.io/starlight-codeblocks/reference/options/): every option, attribute, directive and style setting.

## Using with an agent

This website is agent-friendly: each page has a Markdown version at the same address with `.md` at the end, such as [getting-started.md](https://ewels.github.io/starlight-codeblocks/getting-started.md).
[llms.txt](https://ewels.github.io/starlight-codeblocks/llms.txt) lists every page, and [llms-full.txt](https://ewels.github.io/starlight-codeblocks/llms-full.txt) has every page in one file.

Using an agent? [Point it at the bundled skill](https://ewels.github.io/starlight-codeblocks/agent-skill/). The skill tells the agent which feature suits each use, and how to write it.

## Thanks

This plugin builds on the excellent [Expressive Code](https://expressive-code.com), which renders every code block in Starlight.

The `[!code …]` comment notation comes from the [Shiki transformers](https://shiki.style/packages/transformers) and [VitePress](https://vitepress.dev/). Thank you to both projects. Most code blocks from VitePress work here unchanged.

---

<!-- https://ewels.github.io/starlight-codeblocks/getting-started/ -->

# Getting started

> Install starlight-codeblocks and add it to a Starlight site.

Starlight renders every code block with Expressive Code. The plugin adds its features to those code blocks, so the code blocks you already have keep working. You turn on nothing per page: most features start when a code block uses their attribute or directive. A few, such as file icons and colour swatches, apply to every matching block.

## Requirements

- Astro 7 or later.
- Starlight 0.42 or later.
- Node.js 22.12 or later.

## Install the plugin

1. Add the package to the site.

   **npm**

   ```sh
   npm install starlight-codeblocks
   ```

   **pnpm**

   ```sh
   pnpm add starlight-codeblocks
   ```

   **Yarn**

   ```sh
   yarn add starlight-codeblocks
   ```

2. Open `astro.config.mjs`.

3. Add `codeblocks()` to the `plugins` list of Starlight.

   ```js title="astro.config.mjs" ins={3,9}
   import starlight from '@astrojs/starlight';
   import { defineConfig } from 'astro/config';
   import codeblocks from 'starlight-codeblocks';

   export default defineConfig({
     integrations: [
       starlight({
         title: 'My docs',
         plugins: [codeblocks()],
       }),
     ],
   });
   ```

Pick a feature from the sidebar and add its attribute or directive to a code block to turn it on.

## Sites with an `ec.config.mjs` file

Some sites keep their Expressive Code options in an `ec.config.mjs` file. If that file has no `plugins` list, the plugin works with no change.

If the file has a `plugins` list, Expressive Code uses that list only. Add `pluginCodeblocks()` to it:

```js title="ec.config.mjs" ins={2,5}
import { pluginCollapsibleSections } from '@expressive-code/plugin-collapsible-sections';
import { pluginCodeblocks } from 'starlight-codeblocks/expressive-code';

export default {
  plugins: [pluginCollapsibleSections(), pluginCodeblocks()],
};
```

Keep `codeblocks()` in `astro.config.mjs` as well, and give it the options there. `pluginCodeblocks()` with no argument uses the same options. If you forget this step, the build stops with a message that tells you what to add.

## Sites without Starlight

Astro sites that use Expressive Code without Starlight add the preset to the Expressive Code plugins. Give the options to `pluginCodeblocks()`:

```js title="ec.config.mjs"
import { pluginCodeblocks } from 'starlight-codeblocks/expressive-code';

export default {
  plugins: [pluginCodeblocks({ focus: { style: 'dim' } })],
};
```

Code tabs, inline code highlighting and the `<CodeWalkthrough>` and `<Scrollycoding>` components need Starlight. The features inside code blocks work on every site. Set `tabWidth: 0` in the Expressive Code options, so that tabs reach the code blocks unchanged. Blocks with a **Run code** button need a runtime URL for their language, as in [Without Starlight](https://ewels.github.io/starlight-codeblocks/reference/expressive-code-plugins/#without-starlight).

## Next steps

- [Configuration](https://ewels.github.io/starlight-codeblocks/configuration/): Learn how to set options for the whole site, or for a single code block.
- [Features](https://ewels.github.io/starlight-codeblocks/#features): Browse all the features, with an example of each.

---

<!-- https://ewels.github.io/starlight-codeblocks/configuration/ -->

# Configuration

> Turn features off, change their settings and change their colours with one options object.

With no options, `codeblocks()` turns on every feature. Most features change a code block only when the block uses their attribute or directive. A few, such as file icons, colour swatches and word-level diff, apply to every matching block. Pages that use no interactive feature load no JavaScript from the plugin.

## The options object

In the astro config file, the plugins `codeblocks()` function takes one object. Each feature has a key in it. Set a key to `false` to turn the feature off, or to an object to change its settings:

```js title="astro.config.mjs" {4-8}
starlight({
  title: 'My docs',
  plugins: [
    codeblocks({
      focus: { style: 'dim' },
      expandable: { lines: 20 },
      runnable: false,
    }),
  ],
});
```

- [Options reference](https://ewels.github.io/starlight-codeblocks/reference/options/): See every option, with its type and its default.

## Options for one block

To change a setting for one block only, put the option on the fence line, with the same name as in `codeblocks()`. The fence line is the first line of the code block, with the language. The rest of the site keeps its setting:

````md
```js focus={2} focus.style="dim" lineStates.prefix=false
const host = 'localhost'
const port = 8080 // [!code warning] Set in production
```
````

This works for every setting that applies to one block, such as `wordDiff.minSimilarity=0.6` or `runnable.label="Try it"`. A value of the wrong type gives a build warning, and the block uses the site setting. Options for the whole site, such as custom line states, playgrounds and runtimes, stay in `codeblocks()`.

## Errors in the options

The plugin checks the options when the site starts. An unknown key or a value of the wrong type stops the build with a message that names the option:

```txt error={1} lineStates.prefix=false
starlight-codeblocks: `focus.style` must be 'blur' | 'dim', got "fade".
```

A feature with no settings, such as `callouts`, takes only `false`. To keep the feature on, leave its key out.

## Colours and sizes

Every colour and size of the plugin is an Expressive Code style setting. The default colours come from the Expressive Code theme of the site, such as its terminal blue for the accent. So they follow any theme, dark or light. The plugin makes each colour lighter or darker where it needs to, so that the defaults meet the contrast targets on the [accessibility](https://ewels.github.io/starlight-codeblocks/reference/accessibility/) page.

To change a setting, add `styleOverrides` to the Expressive Code options of Starlight. The shared settings are in the `codeblocks` group. A string applies to both themes, and a pair gives the dark value and then the light value:

```js title="astro.config.mjs" {3-8}
starlight({
  expressiveCode: {
    styleOverrides: {
      codeblocks: {
        accent: ['#c792ea', '#7c3aed'],
        popoverRadius: '4px',
      },
    },
  },
  plugins: [codeblocks()],
});
```

- [Style settings reference](https://ewels.github.io/starlight-codeblocks/reference/style-settings/): See every style setting, with its defaults.
- [Themes](https://ewels.github.io/starlight-codeblocks/reference/themes/): See the colours in eight themes.

## Options with an ec.config.mjs file

Some sites keep their Expressive Code options in an `ec.config.mjs` file, next to `astro.config.mjs`. If that file has a `plugins` list, add `pluginCodeblocks()` to it, as in [Sites with an ec.config.mjs file](https://ewels.github.io/starlight-codeblocks/getting-started/#sites-with-an-ecconfigmjs-file).

Give `pluginCodeblocks()` no argument. It reads its options from `codeblocks()`, so all options stay in `astro.config.mjs`. `styleOverrides` can go in either file.

---

<!-- https://ewels.github.io/starlight-codeblocks/comment-notation/ -->

# Comment notation

> Mark lines with directives in code comments. The plugin applies each directive and removes it from the code that readers see and copy.

The standard way to activate Expressive Code features is with attributes on the fence line, such as `{3}` or `ins={5}`. The fence line is the first line of the code block, with the language.
This means you need to be careful when you edit the code in a code block.
If you add or remove any lines, the counts change and the attribute can point at the wrong code.

To avoid this, starlight-codeblocks also offers configuration via _directives_.
A directive sits in a comment on or above the line that it marks.
It moves with the code, so you don't need to count line numbers.

````md
```ts title="config.ts"
export const config = {
  // [!code highlight]
  host: 'localhost',
  protocol: 'https',
  port: 3000, // [!code --]
  port: Number(process.env.PORT ?? 3000), // [!code ++]
  timeout: 5000,
};
```
````

_Same example, built instead with attributes:_

````md
```ts title="config.ts" mark={2} del={4} ins={5}
export const config = {
  host: 'localhost',
  protocol: 'https',
  port: 3000,
  port: Number(process.env.PORT ?? 3000),
  timeout: 5000,
};
```
````

Each directive changes its line. Each comment holds only a directive, so the plugin removes the whole comment. The copy button copies the code without the directives.

## Syntax

A directive is text in square brackets that starts with `!`.
It is written in a comment, using the appropriate comment syntax of the language of that code block.

Directives turn on many different features. `<name>` is the name of a directive, such as `focus` or `++`. They all use one of these forms:

| Form | Meaning |
|---|---|
| `[!code <name>]` | Applies to the line it is on. |
| `[!code <name>:N]` | Applies to its line and the next N-1 lines. |
| `[!code <name> <name>]` | Applies each name to the line. |
| `[!<name>] <text>` | Shows `<text>` after the code, for example as a note or a message. The text stops at the next directive or at the end of the comment. |
| `[!code <name> <name>] <text>` | Applies each name to the line, and shows `<text>` for the first name that can show text. |
| `[!<name> /<text>/]` | Points at the first match of the literal text on its target line. |
| `[\!code <name>]` | Renders as the literal text `[!code <name>]`. |

For example, `// [!code ++:3]` marks its line and the next two lines as inserted. `// [!code focus ++] Loads the plugin` focuses its line and marks it as inserted, with "Loads the plugin" as the message of the inserted line.

Every directive can go at the end of the line it marks, or on its own line above it. The plugin removes each line that holds only directives, so it does not show on the page.

- [Directives reference](https://ewels.github.io/starlight-codeblocks/reference/directives/): See every directive and the feature it belongs to.

### Sharing with ordinary comments

A directive can share a comment with an ordinary comment. The plugin removes only the directive, and the rest of the comment stays in the code:

````md
```js
const host = 'localhost'
const port = 8080 // Default port [!code focus]
```
````

Text after a directive that takes text, such as `[!code error]` or `[!callout]`, is the text of that directive. Put your own comment before the directive.

## Combining directives

One code block often needs several features: a focus, a changed line with a message, and a note to explain it. The features work together in one block, and each one keeps its own effect.

### Several names in one directive

One `[!code …]` directive can hold several names. Each name applies to the line. The text after the directive goes to the first name that takes text, here `++`.

````md
```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';
import codeblocks from 'starlight-codeblocks'; // [!code focus ++] Import the plugin

export default defineConfig({
  integrations: [
    starlight({
      title: 'My docs',
      plugins: [codeblocks()], // [!code focus ++] Load the plugin
    }),
  ],
});
```
````

The two new lines are green, show their messages, and stay sharp. The other lines are blurred. To give two line states their own messages, use two lines.

### Several directives in one comment

One comment can hold several directives. Each directive takes the text up to the next directive.

````md
```py title="retry.py"
import time


def fetch_with_retry(fetch, retries=3):  # [!mention retries]
    for attempt in range(retries):
        try:
            return fetch()
        except TimeoutError:  # [!code warning] Other errors fail at once [!annotate] Only a timeout is worth a retry.
            time.sleep(2**attempt)  # [!code ++] Back off [!mention retries]
    raise TimeoutError("no response")
```
````

The `except` line has a warning and an annotation. The `sleep` line is new, and it is part of the [retry loop](#mention:retries) with the first line.

### Attributes and directives together

Attributes on the fence line and directives in comments add up. Here the fence line names a placeholder and hides the imports. The comments add a callout, a footnote and an error.

````md
```py title="client.py" placeholder="YOUR_TOKEN" hidden={1-2}
import os
import requests

session = requests.Session()
# [!callout /headers/] Sent with every request
session.headers["Authorization"] = "Bearer YOUR_TOKEN"
# [!ref] The service closes idle connections after 30 s.
session.timeout = 30
session.verify = False  # [!code error] Never turn off TLS checks
```
````

Readers can type their token into the field. The copy button copies their token, the hidden imports and none of the notes.

### The kitchen sink

This block turns on 15 features at once. It has focus, every line state and a word-level diff. It has annotations, mentions, a callout, a footnote and a code link. On the fence line, it adds a placeholder, hidden lines, visible whitespace, line permalinks, an expandable block and colourised brackets. Its title gets a file icon.

Do not publish a block like this. It shows that each feature keeps its own effect.

The [health route](#mention:health) and the [app](#mention:app) are mentions.

````md
```js title="server.js" id="kitchen-sink" placeholder="YOUR_API_KEY" hidden={1-2} whitespace="all" expandable={12} brackets
import 'dotenv/config';
import express from 'express';

const app = express(); // [!mention app]
const PORT = 3000; // [!code --]
const PORT = Number(process.env.PORT ?? 3000); // [!code ++] Read the port from the environment
app.use(express.json()); // [!code ++] Parse JSON bodies [!annotate] Before any route, or `req.body` is `undefined`.
// [!callout /x-api-key/] Checked on every request
app.use((req, res, next) => (req.get('x-api-key') === 'YOUR_API_KEY' ? next() : res.sendStatus(401)));
// [!ref] Load balancers call this route every 10 s.
app.get('/health', (req, res) => { // [!mention health] [!code focus:3]
  res.json({ ok: true, uptime: process.uptime() }); // [!code success] Always 200 [!mention health]
});
// [!link /express.Router/ https://expressjs.com/en/5x/api.html#router] Groups routes under one prefix.
const api = express.Router(); // [!mention app]
api.get('/users/:id', async (req, res) => { // [!code info] Needs a database
  const user = await db.users.find(req.params.id); // [!code error] `db` is not defined
  res.json(user ?? {}); // [!code todo] Return 404 when missing
}); // [!code warning] No error handler
app.use('/api', api); // [!code highlight] [!annotate] Every route in `api` starts with `/api`.
app.listen(PORT, () => console.log('Listening on', PORT)); // [!mention app]
```
````

## Behaviour

The plugin reads the directives when the site builds. It needs no JavaScript in the browser.

- Removing directives:
  - The plugin removes every directive from the rendered code and from the copied text.
  - If a comment holds only directives, the plugin removes the whole comment and the whitespace before it. Other text in the comment stays.
  - In JSX, TSX and MDX, the plugin also reads comments in braces, `{/* [!code focus] */}`, and removes the braces with the comment.
  - A backslash after the bracket, as in `[\!code focus]`, turns a directive into plain text. The plugin removes the backslash.
- Expressive Code markers:
  - `[!code highlight]`, `[!code ++]` and `[!code --]` give the same result as the `mark`, `ins` and `del` attributes of Expressive Code. Text after them shows as a message, as for [line states](https://ewels.github.io/starlight-codeblocks/features/line-states/).
- Text and copy:
  - Inline code, links and bold in the text of a directive render as HTML. Other Markdown stays as text.
  - The copy button leaves out messages, annotations, callouts and footnotes.

### Line numbers

Line numbers in attributes count the lines that readers see. The plugin removes lines that hold only directives before it counts, so they do not change the numbers. This applies to the attributes of Expressive Code as well, such as `{2}` and `ins={3}`.

### Warnings

The build logs a warning with the file, the code block and the line when:

- a directive has an unknown name, or the feature it belongs to is off;
- the `/<text>/` of a directive has no match on its target line;
- a directive on its own line has no line below it;
- a directive is not in a comment that the block reads, such as `<!-- -->` in an `mdx` block. A directive in a string does not give this warning.

The directive then has no effect. An unknown directive, or one outside a comment, stays in the code as written, so you can see it on the page.

## Options

### `notation`

Reads directives in code comments. Set it to `false` to turn the feature off. Every comment then renders as written.

- Type: `false | object`
- Default: On

### `notation.comments`

Comment syntax for each language, added to the built-in map. An empty list removes a language.

- Type: `Record<string, string[]>`
- Default: `{}`

Each entry in `notation.comments` is a language and a list of comment syntaxes. A syntax with a space in it is a block comment: the opener, then the closer.

```js title="astro.config.mjs"
codeblocks({
  notation: {
    comments: {
      cypher: ['//'],
      jinja: ['{# #}'],
    },
  },
});
```

An entry replaces the built-in syntax of that language. A language name or its alias works: an entry for `powershell` also applies to ` ```pwsh `. The built-in map:

| Comment syntax | Languages |
|---|---|
| `//`, `/* */` | `c`, `c#`, `c++`, `cc`, `cjs`, `cpp`, `cs`, `csharp`, `cts`, `dart`, `go`, `groovy`, `h`, `hpp`, `java`, `javascript`, `js`, `json5`, `jsonc`, `kotlin`, `kt`, `kts`, `mjs`, `mts`, `nextflow`, `nf`, `php`, `rs`, `rust`, `scala`, `swift`, `ts`, `typescript` |
| `//`, `/* */`, `{/* */}` | `jsx`, `tsx` |
| `#` | `bash`, `console`, `docker`, `dockerfile`, `make`, `makefile`, `nix`, `perl`, `pl`, `powershell`, `ps`, `ps1`, `py`, `pycon`, `python`, `r`, `rb`, `ruby`, `sh`, `shell`, `shellscript`, `toml`, `yaml`, `yml`, `zsh` |
| `--` | `haskell`, `hs`, `lua`, `sql` |
| `<!-- -->` | `html`, `markdown`, `md`, `svg`, `xml` |
| `{/* */}` | `mdx` |
| `<!-- -->`, `//`, `/* */` | `astro`, `svelte`, `vue` |
| `/* */` | `css` |
| `/* */`, `//` | `less`, `sass`, `scss` |
| `%` | `erl`, `erlang`, `latex`, `tex` |
| `;` | `clj`, `clojure`, `ini`, `lisp` |

- [Configuration](https://ewels.github.io/starlight-codeblocks/configuration/): Learn how to set options for the whole site, or for a single code block.

## Comment syntax examples

Python and shell blocks use `#` comments:

````md
```py title="parse.py"
import json

data = json.loads(text)  # [!code highlight]
print(data["name"])
```
````

HTML blocks use `<!-- -->` comments. `:2` marks two lines with one directive:

````md
```html title="nav.html"
<nav>
  <a href="/">Home</a> <!-- [!code ++:2] -->
  <a href="/docs/">Docs</a>
</nav>
```
````

To show a directive as text, for example in a page about this plugin, add a backslash:

````md
```js title="server.js"
const port = 8080; // [\!code highlight]
```
````

## Limitations

- JSON has no comments, so a `json` block cannot use directives. Use `jsonc`, or use attributes.
- The plugin skips a comment opener inside a string that opens and closes on the same line, such as `"// [!code ++]"`. A string that continues on the next line, such as a template literal, is not skipped. Escape a directive in it with a backslash.
- One comment on each line can hold directives. Text such as `[!NOTE]` outside a comment, as in a Markdown alert, stays in the code. The plugin still reads the comment after it.

## Related

- [Focus](https://ewels.github.io/starlight-codeblocks/features/focus/): use `[!code focus]` to blur the lines that do not matter.
- [Line states](https://ewels.github.io/starlight-codeblocks/features/line-states/): use `[!code error]` and the other states to tint a line and add a message.

---

<!-- https://ewels.github.io/starlight-codeblocks/agent-skill/ -->

# Use with an AI agent

> Install the starlight-codeblocks agent skill, so an AI coding agent knows each feature, its syntax and when to use it.

The plugin comes with an [agent skill](https://github.com/ewels/starlight-codeblocks/tree/main/skills/starlight-codeblocks) for Claude Code, Codex, Cursor, GitHub Copilot and other agents. With the skill, your agent uses the features as it writes new pages. For example, it focuses the lines of a new option, or adds a placeholder for an API token. It also knows when a feature does not help.

## Install the skill

Run this command in the folder of your Starlight site. Add `-g` to install it for every project:

```sh
npx skills add ewels/starlight-codeblocks
```

The [skills CLI](https://github.com/vercel-labs/skills) installs the skill for each coding agent that you use. Run `npx skills update` to get a new version.

An agent without a skills folder can read [`SKILL.md`](https://github.com/ewels/starlight-codeblocks/blob/main/skills/starlight-codeblocks/SKILL.md) on GitHub:

- [Agent skill source](https://github.com/ewels/starlight-codeblocks/tree/main/skills/starlight-codeblocks): SKILL.md and the reference files on GitHub.

## Add features to an existing site

The skill works well for agents building new sites, but can also retrofit existing content.

Ask the agent to add the features to one page, a sidebar group or the whole site. It works through the pages one at a time, and reads each code block in the context of its page. It adds a feature only when the page gives a reason for it. After each page, it tells you what it changed and why.

---

<!-- https://ewels.github.io/starlight-codeblocks/features/annotations/ -->

# Annotations

> Add numbered markers to lines. Each marker opens a note in a popover, so the code stays clean until a reader asks.

A comment in a code block explains a line. But it takes space in the code, and readers copy it with the code. An annotation moves the explanation out of the code. The line gets a small numbered marker, and the note opens in a popover when a reader clicks the marker.

:::tip[Good for:]
Additional helper info that most readers can skip.
Takes up almost no additional space until a reader opens a marker.
If readers need every note, use [footnotes](https://ewels.github.io/starlight-codeblocks/features/footnotes/) or [side annotations](https://ewels.github.io/starlight-codeblocks/features/side-annotations/).
:::

````md
```yaml title=".github/workflows/test.yml"
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest # [!annotate] Uses the Ubuntu GitHub Actions runner.
    steps:
      - uses: actions/checkout@v7
      - uses: astral-sh/setup-uv@v7 # [!annotate] Installs `uv` and caches its downloads between runs.
      - run: uv run pytest
```
````

Each `[!annotate]` comment is gone from the output. A numbered marker is in its place, after the code on the line. Hover over a marker to see its note, or click the marker to keep the note open. Press Escape or click anywhere else to close the notes.

## Syntax

| Syntax | Where |
|---|---|
| `[!annotate] note` | Comment at the end of a line |
| `startNoteNumber={N}` | Code block fence line |
| `annotations.style="filled"`, `annotations.style="outline"` | Code block fence line |

The directive goes at the end of the line it explains. The note is the rest of the comment. It can hold inline code, links and bold text. The markers count from 1, in line order. To continue the numbers of an earlier block, add `startNoteNumber={N}` to the fence line, and the first marker is `N`. `annotations.style` sets the style of the markers for one block.

- [Side annotations](https://ewels.github.io/starlight-codeblocks/features/side-annotations/): Use the same syntax to show every note in a column beside the code.

## Examples

### A link in a note

A note can hold a link, for a line that needs more explanation than a sentence:

````md
```ts title="retry.ts"
export async function retry<T>(task: () => Promise<T>, attempts = 3): Promise<T> {
  for (let i = 1; ; i++) {
    try {
      return await task();
    } catch (error) {
      if (i >= attempts) throw error; // [!annotate] Gives up and passes on the last error. See [Error handling](https://example.com/errors).
      await new Promise((done) => setTimeout(done, 2 ** i * 100)); // [!annotate] Waits 200 ms, then 400 ms: an exponential backoff.
    }
  }
}
```
````

### The outline style

The `outline` style, for one block:

````md
```js annotations.style="outline"
const port = 8080 // [!annotate] The default port. Set `PORT` to change it.
```
````

## Behaviour

- Opening a note:
  - Hover over a marker to show its note. The mouse cursor can move into the note, for example to click a link.
  - Click the marker to keep the note open. Click it again to close the note.
  - Several notes can be open at once. Escape, or a click outside the notes, closes them all.
- Where the note opens:
  - To the right of the marker, over the empty space after the line. A long note wraps at the popover width, 340 px by default.
  - Under the marker, if the note would cover code or go past the edge of the block or the window. On a phone, most notes open here.
  - Above the marker, if there is no room under it.
- Screen readers:
  - Each marker is a button with the label "Annotation N". Screen readers read the note directly after it.
- Copy and print:
  - The copy button leaves the markers and the notes out. A manual selection leaves the markers out.
  - In print, each marker shows its number, and the notes are a numbered list under the block.
- Without JavaScript:
  - The browser's `popover` attribute opens and closes the notes. Each note opens under its marker.
- Motion:
  - The note fades in and out in 160 ms. On hover, the marker changes colour on the same timing, after 80 ms.
  - With reduced motion, both change at once.

## Options

### `annotations`

Adds numbered markers that open a note. Set it to `false` to turn the feature off.

- Type: `false | object`
- Default: On

### `annotations.style`

Filled markers in the accent colour, or outlined markers in the magenta of the theme. Side annotations use it too. A code block can set its own on its fence line.

- Type: `'filled' | 'outline'`
- Default: `'filled'`

The `filled` style draws each marker as a circle filled with the accent colour. The `outline` style draws an outlined circle in the magenta of the theme, and fills it when the note is open. [Footnotes](https://ewels.github.io/starlight-codeblocks/features/footnotes/) have the same two styles. To use outlined markers on the whole site:

```js title="astro.config.mjs"
codeblocks({
  annotations: { style: 'outline' },
});
```

With `annotations: false`, the plugin does not know the `[!annotate]` directive. It leaves the comment in the code as written, and logs a build warning. Side annotations are off too.

- [Configuration](https://ewels.github.io/starlight-codeblocks/configuration/): Learn how to set options for the whole site, or for a single code block.

## Limitations

- The note is part of the source line. Long notes make long lines in the Markdown file.
- An annotation applies to one line. For a note about a range of lines, put it on the first line of the range.
- Readers see a note only when they open it. If readers need every note to follow the code, use [footnotes](https://ewels.github.io/starlight-codeblocks/features/footnotes/) or [side annotations](https://ewels.github.io/starlight-codeblocks/features/side-annotations/).

## Related

- [Inline callouts](https://ewels.github.io/starlight-codeblocks/features/inline-callouts/): a short, always visible note above the line, with an arrow at one name.
- [Footnotes](https://ewels.github.io/starlight-codeblocks/features/footnotes/): numbered notes listed under the block, all visible at once.
- [Side annotations](https://ewels.github.io/starlight-codeblocks/features/side-annotations/): the same notes in a column beside the code.

---

<!-- https://ewels.github.io/starlight-codeblocks/features/side-annotations/ -->

# Side annotations

> Show the notes of an annotated block in a column beside the code, so readers see every note next to its line.

[Annotations](https://ewels.github.io/starlight-codeblocks/features/annotations/) hide each note in a popover until a reader opens it. For a walkthrough, where readers need every note, that is one click too many. Side annotations use the same `[!annotate]` directive, but show the notes in a column beside the code.

:::tip[Good for:]
A long block with a short note on many of its lines. Readers see every note at once, each beside its line, and the notes work in Markdown and MDX. To explain the code in paragraphs, one step at a time, use [scrollycoding](https://ewels.github.io/starlight-codeblocks/features/scrollycoding/).
:::

````md
```py title="report.py" annotations="side"
import csv
import sys
from collections import Counter
from pathlib import Path


def read_rows(path):
    with path.open() as fh:  # [!annotate] Opens the file and closes it when the block ends.
        return list(csv.DictReader(fh))  # [!annotate] Each row becomes a dict keyed by the header line.


def summarise(rows, key):  # [!annotate] Counts the rows for each value in the column `key`.
    return Counter(r[key] for r in rows)


def main():
    rows = read_rows(Path(sys.argv[1]))
    counts = summarise(rows, "status")
    for status, n in counts.items():
        print(f"{status:<10} {n:>5}")  # [!annotate] Pads the status and count into columns of fixed width.


if __name__ == "__main__":
    main()
```
````

Each annotated line has a small number, and the note with the same number is in the column on the right. Hover over a note, or move keyboard focus to it, to highlight its line. Hover over a line to highlight its note.

## Syntax

| Syntax | Where |
|---|---|
| `annotations="side"` | Code block fence line |
| `[!annotate] note` | Comment at the end of a line |
| `codeSide="right"` | Code block fence line |
| `startNoteNumber={N}` | Code block fence line |
| `annotations.style="filled"`, `annotations.style="outline"` | Code block fence line |

Add `annotations="side"` to the fence line (the first line of the code block, with the language) of a block that uses `[!annotate]`. The directive works as on the [annotations](https://ewels.github.io/starlight-codeblocks/features/annotations/) page. The code is in the left column. To put it in the right column, add `codeSide="right"`. `startNoteNumber={N}` numbers the notes from `N`. `annotations.style` sets the style of the numbers for one block, as for [annotations](https://ewels.github.io/starlight-codeblocks/features/annotations/#options).

## Examples

### Code on the right

`codeSide="right"` puts the code in the right column and the notes in the left column:

````md
```yaml title="config.yml" annotations="side" codeSide="right"
server:
  port: 8080 # [!annotate] The port that the server listens on.
  host: 0.0.0.0 # [!annotate] Listens on every network interface.
log:
  level: info # [!annotate] One of `debug`, `info`, `warn` or `error`.
```
````

### The outline style

`annotations.style="outline"` draws the numbers on the lines as outlined circles in the magenta of the theme:

````md
```py title="greet.py" annotations="side" annotations.style="outline"
import sys # [!annotate] Gives access to the command-line arguments.

name = sys.argv[1] # [!annotate] The first argument after the file name.
print(f"Hello, {name}!") # [!annotate] An f-string puts the value of `name` in the text.
```
````

## Behaviour

- Layout:
  - The code and the notes are two columns when the block's container has space for the longest line beside the notes. The plugin measures the lines at build time and gives each block one of three widths: 600, 800 or 1000 px. In a container narrower than that width, such as on a phone, the notes are a numbered list under the block.
  - At 600 px, the code column shows about 42 characters on a line. At 800 px it shows about 66, and at 1000 px about 90. A line with a number needs 3 characters more, and the first line needs 4 more for the copy button.
  - The notes column is at least 12rem wide.
- Scrolling:
  - The notes column starts level with the top of the block. It sticks below the site header while the block scrolls past.
  - If the notes column is taller than the space below the header, it scrolls with the page instead.
- Highlighting:
  - Hovering over a note, or focusing it with the Tab key, highlights its line. Hovering over a line highlights its note.
  - A number on a line changes colour when the mouse cursor is on it, the same as an annotation marker.
  - Clicking a note or its number keeps the highlight, as for [footnotes](https://ewels.github.io/starlight-codeblocks/features/footnotes/). A second click clears it. Several can stay highlighted. A click anywhere else clears them all.
  - With keyboard focus on a note, Enter or Space keeps or clears its highlight.
- Screen readers:
  - The numbers on the lines are hidden from screen readers. Screen readers read the notes as a list after the code.
- Copy:
  - The copy button leaves the numbers and the notes out.
- Without JavaScript:
  - The layout works, but notes and lines do not highlight each other.
- Motion:
  - Under reduced motion, the highlight changes at once.

## Options

Side annotations have no options of their own. They use the `style` option of [annotations](https://ewels.github.io/starlight-codeblocks/features/annotations/#options), and a block can set its own with `annotations.style="outline"`. `annotations: false` turns them off together with annotations:

```js title="astro.config.mjs"
codeblocks({
  annotations: false,
});
```

- [Configuration](https://ewels.github.io/starlight-codeblocks/configuration/): Learn how to set options for the whole site, or for a single code block.

## Make space for long lines

Starlight's content column is 45rem (720 px) wide on each page that has a sidebar. So on a default page, a block with lines of more than about 42 characters shows the notes as a list under the code.

On a page without a table of contents, the column has free space on each side. A block that needs 800 or 1000 px spreads over that space, so it gets the columns in a wide window. The text stays in the content column.

[See the demo on a page without a table of contents](https://ewels.github.io/starlight-codeblocks/features/side-annotations/wide/)

To use this, turn off the table of contents of the page:

```md title="src/content/docs/guides/walkthrough.md"
---
title: Walkthrough
tableOfContents: false
---
```

- The block spreads only when it is directly on the page. A block in tabs, an aside, a list or a component stays in its column.
- The block spreads by the same amount on each side, and not more than it needs for the columns.
- If the window is too narrow for the columns, the block stays in the content column and shows the list.
- A block that fits the content column does not spread.

## Limitations

- The columns need a container of 600 px or more. Blocks with long lines need a wider container, or a page without a table of contents. Smaller windows and phones get the list under the block.
- The widths are estimates for Starlight's default code font. A larger code font can make a line scroll in the code column.
- Lines of more than about 90 characters scroll inside the code column at every width.
- Each note is next to its number, not next to its line. Notes in the column follow each other from the top of the block.

## Related

- [Annotations](https://ewels.github.io/starlight-codeblocks/features/annotations/): the same notes in popovers, for blocks where most readers do not need every note.
- [Footnotes](https://ewels.github.io/starlight-codeblocks/features/footnotes/): the notes in a list under the block at every width, with badges that link the two.
- [Scrollycoding](https://ewels.github.io/starlight-codeblocks/features/scrollycoding/): prose steps that scroll past the block, which focuses the lines of each step.

---

<!-- https://ewels.github.io/starlight-codeblocks/features/footnotes/ -->

# Footnotes

> Add numbered badges to lines, with the notes in a list under the block, where readers see them all at once.

A code block often comes with a list of notes in the prose after it, where each note names the line it is about. Footnotes put that list inside the block. Each line with a note gets a numbered badge, and the notes are a numbered list under the code.

:::tip[Good for:]
A short block where readers need every note. The list stays close to the lines and works the same on a phone and a desktop. For a long block, use [side annotations](https://ewels.github.io/starlight-codeblocks/features/side-annotations/).
:::

````md
```py title="app.py"
from flask import Flask

# [!ref] Creates the application object.
app = Flask(__name__)

# [!ref] Runs this function for `GET /health`.
@app.get("/health")
def health():
    return {"ok": True}
```
````

The two `[!ref]` comment lines are gone from the output. Their lines have the badges 1 and 2, and the notes are in the list under the code. Click a badge to highlight its line and its note together. Click a note to do the same from the list.

## Syntax

| Syntax | Where |
|---|---|
| `[!ref] note` | Comment on or above the line |
| `footnotes="sticky"` | Code block fence line |
| `footnotes="static"` | Code block fence line |
| `footnotes.sticky=true`, `footnotes.sticky=false` | Code block fence line |
| `startNoteNumber={N}` | Code block fence line |
| `footnotes.style="filled"`, `footnotes.style="outline"` | Code block fence line |

The directive goes at the end of the line it explains, or on its own line above it. The note can hold inline code, links and bold text. `footnotes="sticky"` keeps the list in view while the block scrolls past. `footnotes="static"` turns the sticky list off for one block, if the site turns it on for every block. `footnotes.sticky=true` and `footnotes.sticky=false` do the same, with the name of the option. `startNoteNumber={N}` numbers the footnotes from `N`, to continue the numbers of an earlier block.

`footnotes.style` sets the style of the badges for one block.

## Examples

### A sticky list

A sticky list suits a long block, where the notes would otherwise be far from the lines they are about. Scroll past this block to see the list stay at the bottom of the window:

````md
```py title="count.py" footnotes="sticky"
import argparse
import logging
from pathlib import Path

# [!ref] A logger named after the module, so output shows where it came from.
log = logging.getLogger(__name__)


def parse_args() -> argparse.Namespace:
    parser = argparse.ArgumentParser(description="Count lines in files.")
    parser.add_argument("paths", nargs="+", type=Path)
    # [!ref] `-v` can be repeated: `-vv` turns on debug output.
    parser.add_argument("-v", "--verbose", action="count", default=0)
    return parser.parse_args()


def count_lines(path: Path) -> int:
    with path.open() as fh:
        return sum(1 for _ in fh)


def main() -> None:
    args = parse_args()
    logging.basicConfig(level=logging.WARNING - 10 * args.verbose)
    for path in args.paths:
        log.debug("Reading %s", path)
        print(f"{count_lines(path):>8}  {path}")


# [!ref] Runs only when the file runs as a script, not when another module imports it.
if __name__ == "__main__":
    main()
```
````

### The filled style

The `filled` style, for one block:

````md
```py footnotes.style="filled"
# [!ref] Creates the application object.
app = Flask(__name__)
```
````

## Behaviour

- Numbers and placement:
  - Badges are numbered from 1 in each block, or from the `startNoteNumber` value, in line order.
  - With `footnotes="sticky"`, the list sticks to the bottom of the window while any part of the block is on screen.
- Highlighting:
  - Hovering over a badge or a note with a mouse highlights the line and the note until the mouse cursor leaves. The highlight fades in after 80 ms, so it does not flash while the mouse cursor passes over. The page does not scroll.
  - Clicking a badge highlights its whole line and its note, and the highlight stays. Clicking the badge or the note again clears it. Several footnotes can be highlighted at once. If the note is not on screen, the page scrolls to it.
  - Clicking a note highlights it and its line. If the line is not on screen, the page scrolls to it.
  - The note gets the same tint and bar as its line.
  - Clicking anywhere else clears every highlight.
- Keyboard and screen readers:
  - Each badge is a link with the label "Footnote N", and its note is its accessible description. The number in front of each note is a link back to its line, with the label "Footnote N, for line L".
  - From the keyboard, a badge always moves focus to its note, and the number moves focus back to the badge.
- Copy:
  - The copy button leaves the badges and the notes out. A manual selection of the code leaves the badges out.
- Without JavaScript:
  - The badges and the numbers are plain links to each other, so they still work, without the highlight.
- Motion:
  - With reduced motion, the highlights change at once, and the page jumps to the line or the note instead of scrolling smoothly.

## Options

### `footnotes`

Adds numbered badges to lines, with the notes in a list under the block. Set it to `false` to turn the feature off.

- Type: `false | object`
- Default: On

### `footnotes.sticky`

Keep the list of footnotes in view while the block is on screen. A code block can set its own on its fence line.

- Type: `boolean`
- Default: `false`

### `footnotes.style`

Filled badges in the accent colour, or outlined badges in the magenta of the theme. A code block can set its own on its fence line.

- Type: `'filled' | 'outline'`
- Default: `'outline'`

The `outline` style draws an outlined badge in the magenta of the theme, and fills it when its line is highlighted. The `filled` style draws each badge filled with the accent colour, the same as an [annotation](https://ewels.github.io/starlight-codeblocks/features/annotations/) marker.

```js title="astro.config.mjs"
codeblocks({
  footnotes: { sticky: true, style: 'filled' },
});
```

With `footnotes: false`, the plugin does not know the `[!ref]` directive. It leaves the comment in the code as written, and logs a build warning.

- [Configuration](https://ewels.github.io/starlight-codeblocks/configuration/): Learn how to set options for the whole site, or for a single code block.

## Limitations

- A footnote applies to one line. For a note about a range of lines, put it above the first line of the range.
- A sticky list covers the bottom of the block while it is on screen. Keep the notes short, so the list stays small.

## Related

- [Annotations](https://ewels.github.io/starlight-codeblocks/features/annotations/): numbered markers that open a note only when the reader asks for it.
- [Side annotations](https://ewels.github.io/starlight-codeblocks/features/side-annotations/): the notes in a column beside the code, on wide screens.
- [Inline callouts](https://ewels.github.io/starlight-codeblocks/features/inline-callouts/): a short note above the line, with an arrow at one name.

---

<!-- https://ewels.github.io/starlight-codeblocks/features/inline-callouts/ -->

# Inline callouts

> Put a short note in a bubble above a line, with an arrow that points at the word it explains.

A code block shows the code, and the prose around it explains it. When the explanation is about one name on one line, a reader must find that name themselves. An inline callout puts the note in a bubble directly above the line, with an arrow that points down at the name.

:::tip[Good for:]
A note of one short sentence about one name on a line. The bubble is always visible, so keep to one or two callouts in a block. For a longer note, use [annotations](https://ewels.github.io/starlight-codeblocks/features/annotations/) or [footnotes](https://ewels.github.io/starlight-codeblocks/features/footnotes/).
:::

````md
```js
const controller = new AbortController();
// [!callout /signal/] Lets `controller.abort()` cancel the request.
const res = await fetch(url, { signal: controller.signal });
const data = await res.json();
```
````

The comment line with `[!callout /signal/]` is gone from the output. The bubble takes its place, and its arrow points at the middle of the first `signal` on the line below.

## Syntax

| Syntax | Where |
|---|---|
| `[!callout /text/] note` | Comment on or above the line |
| `[!callout] note` | Comment on or above the line |

The directive goes at the end of the line it explains, or on its own line directly above it. `/text/` is literal text, not a regular expression. The arrow points at the first match on that line. Without `/text/`, the arrow points at the first character that is not a space. The note can hold inline code, links and bold text.

## Examples

### A callout for the whole line

A callout without `/text/` points at the start of the line. This suits a note about the whole statement:

````md
```py
import sqlite3

# [!callout] Creates the file if it does not exist yet.
db = sqlite3.connect("notes.db")
db.execute("CREATE TABLE IF NOT EXISTS notes (body TEXT)")
```
````

### Two callouts on one line

Two callouts above one line explain two parts of it. The bubbles stack in source order:

````md
```ts
// [!callout /retries/] How many times to try again after the first attempt.
// [!callout /backoffMs/] The wait before each retry, in milliseconds.
const client = createClient({ retries: 3, backoffMs: 250 });
```
````

## Behaviour

- Where the bubble shows:
  - The plugin removes the directive, and its line if the line holds nothing else. The bubble is above the target line.
  - The bubble starts 40 px to the left of the arrow, but never closer than 8 px to the edge of the block.
  - The bubble is at most 60 characters wide, or 90% of the block. Longer notes wrap inside the bubble, so the block does not get wider.
  - On a narrow screen, the target text can be past the right edge of the block. The bubble and its arrow then stay at the right edge, where the reader can see them.
  - Two callout lines above one line give two bubbles, in the order you wrote them.
- Highlights:
  - If the lines above and below the callout have the same highlight, the callout has it too, so the highlight does not break. This works for marked, inserted and deleted lines and for [line states](https://ewels.github.io/starlight-codeblocks/features/line-states/).
- Screen readers:
  - Screen readers read the bubble before its line. The bubble has the `note` role.
- Copy:
  - The copy button leaves callouts out. A manual selection of the code leaves them out too.
  - To select the text of a bubble, start the selection in the bubble.
- Without JavaScript:
  - Callouts are plain HTML and CSS. They work without JavaScript, and they have no animation. Without JavaScript, the text of a bubble cannot be selected.

## Options

Inline callouts have no options. Turn the feature off for the whole site with `callouts: false`:

```js title="astro.config.mjs"
codeblocks({
  callouts: false,
});
```

With `callouts: false`, the plugin does not know the `[!callout]` directive. It leaves the directive line in the code as written, and logs a build warning.

- [Configuration](https://ewels.github.io/starlight-codeblocks/configuration/): Learn how to set options for the whole site, or for a single code block.

## Limitations

- The plugin counts columns in characters. A tab counts to the next multiple of 2 columns, which is the `tab-size` the plugin sets on code blocks. If your site sets another `tab-size`, arrows on lines with tabs after other characters point at the wrong place.
- With Expressive Code's `wrap` attribute, a long line can wrap below its callout. The arrow then points at the first row of the line.
- A callout explains one line. For a note about several lines, use [annotations](https://ewels.github.io/starlight-codeblocks/features/annotations/) or [footnotes](https://ewels.github.io/starlight-codeblocks/features/footnotes/).

## Related

- [Annotations](https://ewels.github.io/starlight-codeblocks/features/annotations/): numbered markers that open a note only when the reader asks for it.
- [Footnotes](https://ewels.github.io/starlight-codeblocks/features/footnotes/): numbered notes listed under the block, all visible at once.

---

<!-- https://ewels.github.io/starlight-codeblocks/features/scrollycoding/ -->

# Scrollycoding

> Explain a code block in prose steps that scroll past it, while the block stays in view and focuses the lines of each step.

A walkthrough of a file often puts the whole block first, then explains it in paragraphs below. Readers scroll back up to find each line that a paragraph names. Scrollycoding keeps the block next to the prose. As each step scrolls past the middle of the block, the block focuses the lines of that step.

:::tip[Good for:]
A tutorial that explains a block in paragraphs, one step at a time. To show versions of a file with only a short label for each step, use a [code walkthrough](https://ewels.github.io/starlight-codeblocks/features/code-walkthrough/). For a short note on each of many lines, all visible at once, use [side annotations](https://ewels.github.io/starlight-codeblocks/features/side-annotations/).
:::

````md
<Scrollycoding>

```js title="server.js"
import express from 'express';

const app = express();
app.use(express.json());

app.get('/health', (req, res) => {
  res.json({ ok: true });
});

app.listen(3000);
```

<Step focus="1">Import Express. Nothing else is needed for a small server.</Step>
<Step focus="3">Create the app object that holds routes and middleware.</Step>
<Step focus="4">Parse JSON request bodies before any route sees them.</Step>
<Step focus="6-8">Answer health checks with a small JSON payload.</Step>
<Step focus="10">Start listening on port 3000.</Step>

</Scrollycoding>
````

Scroll down the page. The block stays below the site header, and each step that reaches the middle of the block changes the focus. On a narrow screen, each step has its own copy of the block, focused for that step.

## Syntax

| Syntax | Where |
|---|---|
| `<Scrollycoding>` ... `</Scrollycoding>` | Around the code blocks and the steps, in an MDX file |
| `<Step>` ... `</Step>` | After the code block, one for each step |
| `focus="<range>"` | On `<Step>` |
| `mark="<range>"` | On `<Step>` |
| A code block between two steps | After a `<Step>` |
| `codeSide="left"` | On `<Scrollycoding>` |

Import both components at the top of the MDX file:

```mdx
import { Scrollycoding, Step } from 'starlight-codeblocks/components';
```

Put one code block first, then the steps. Leave an empty line after `<Scrollycoding>` and before `</Scrollycoding>`. `focus` and `mark` take a [range](https://ewels.github.io/starlight-codeblocks/comment-notation/#line-numbers) without braces, such as `4` or `1, 6-8`. A step can contain any Markdown, such as links, inline code or several paragraphs. Text outside the steps fails the build: put it in a step, or before or after `<Scrollycoding>`.

To change the code during the walkthrough, put a new version of the code block between two steps. The steps after it show the new version, and their `focus` and `mark` ranges count its lines. See [Change the code between steps](#change-the-code-between-steps).

## Examples

### Mark a line in a step

A step can mark a line as well as focus a range. Here, the second step keeps the whole function in focus and marks the line that changes the total:

````md
<Scrollycoding>

```py title="cart.py"
def total(items, discount=0):
    price = sum(i.price for i in items)
    return price * (1 - discount)
```

<Step focus="1">The function takes the items and an optional discount, from 0 to 1.</Step>
<Step focus="1-3" mark="3">The last line applies the discount to the sum.</Step>

</Scrollycoding>
````

### Change the code between steps

A code block between two steps is a new version of the code. Here, the third step adds a line, and the block animates to the new version when that step becomes active:

````md
<Scrollycoding>

```js title="server.js"
const app = express();

app.listen(3000);
```

<Step focus="1">Create the app object that holds routes and middleware.</Step>
<Step focus="3">Start listening on port 3000.</Step>

```js title="server.js"
const app = express();
app.use(express.json());

app.listen(3000);
```

<Step focus="2">Parse JSON request bodies before any route sees them.</Step>
<Step focus="4">The server still listens on port 3000.</Step>

</Scrollycoding>
````

### Code on the left

`codeSide="left"` puts the block in the left column and the steps in the right column:

````md
<Scrollycoding codeSide="left">

```py title="cart.py"
def total(items, discount=0):
    price = sum(i.price for i in items)
    return price * (1 - discount)
```

<Step focus="1">The function takes the items and an optional discount, from 0 to 1.</Step>
<Step focus="2">Add up the price of each item.</Step>
<Step focus="3">Apply the discount to the sum.</Step>

</Scrollycoding>
````

## Behaviour

- Layout:
  - On a wide screen, the steps are a column on the left, and the block is on the right. With `codeSide="left"`, the block is on the left and the steps are on the right. The block stays below the site header while the steps scroll with the page.
  - The two columns need space for the longest line of the block beside a text column of 12rem. The plugin measures the lines at build time and gives the block one of three widths: 600, 800 or 1000 px. In a narrower container, the page shows the narrow layout. The widths are the same as for [side annotations](https://ewels.github.io/starlight-codeblocks/features/side-annotations/#make-space-for-long-lines).
  - On a narrow screen, each step shows its own copy of the block below its text, in the version of that step.
- Scrolling through the steps:
  - The step that crosses the middle of the block is the active step. It shows at full opacity, and the other steps fade.
  - When the active step changes, the block changes its focused and marked lines, with the 250 ms transition of [focus](https://ewels.github.io/starlight-codeblocks/features/focus/).
  - When the active step has a new version of the code, the code moves to the new version as in a [code walkthrough](https://ewels.github.io/starlight-codeblocks/features/code-walkthrough/). Code that is in both versions moves, and new lines fade in with a green tint.
  - The block stays blurred when the mouse cursor is over it, because the mouse cursor often rests there while the reader scrolls. Move keyboard focus into the block to make every line sharp.
- Copy:
  - The copy button copies the whole block, in every step.
- Without JavaScript:
  - The page shows the narrow layout at every width.
- Motion:
  - When the reader's system asks for reduced motion, the focus, the fade and the code change without a transition.

## Options

Scrollycoding has no options. To turn the feature off for the whole site, set `scrollycoding` to `false`:

```js title="astro.config.mjs"
codeblocks({
  scrollycoding: false,
});
```

With `scrollycoding: false`, `<Scrollycoding>` shows the narrow layout at every width, with no script. With `walkthrough: false`, a new version of the code shows without the animation.

- [Configuration](https://ewels.github.io/starlight-codeblocks/configuration/): Learn how to set options for the whole site, or for a single code block.

## Make space for long lines

A block with lines of more than about 41 characters needs more than 600 px for the two columns. On a page without a table of contents, the content column has free space on each side. A `<Scrollycoding>` that needs 800 or 1000 px spreads over that space, as [side annotations](https://ewels.github.io/starlight-codeblocks/features/side-annotations/#make-space-for-long-lines) do.

[See the demo on a page without a table of contents](https://ewels.github.io/starlight-codeblocks/features/scrollycoding/wide/)

To use this, turn off the table of contents of the page with `tableOfContents: false` in its front matter. The component spreads only when it is directly on the page, not in tabs, an aside or another component.

## Limitations

- `<Scrollycoding>` works in MDX files only, because Markdown files cannot contain components.
- During the animation to a new version, the block shows the syntax colours only. The focus shows again when the animation ends.
- The widths are estimates for Starlight's default code font. A larger code font can make a line scroll in the code column.
- The narrow layout repeats the block for each step, so a long block with many steps makes a long page.
- The component replaces the focus of the block. A `focus` attribute on the fence line (the first line of the code block, with the language) has no effect. A mark on the fence line, such as `{2}`, shows in every step. The steps focus their lines with `focus: false` too.

## Related

- [Focus](https://ewels.github.io/starlight-codeblocks/features/focus/): one block with one focus range, with no prose steps.
- [Code walkthrough](https://ewels.github.io/starlight-codeblocks/features/code-walkthrough/): versions of a block, with buttons to step through them and no prose between the steps.
- [Side annotations](https://ewels.github.io/starlight-codeblocks/features/side-annotations/): notes for many lines in a column next to the block, all visible at once.

---

<!-- https://ewels.github.io/starlight-codeblocks/features/code-walkthrough/ -->

# Code walkthrough

> Step through versions of one code block, and watch the code move from each version to the next, so readers see what changed.

A tutorial often shows the same file several times, with a few lines more each time. Readers must compare the blocks line by line to find the change. A code walkthrough puts the versions in one block with numbered steps in the title bar. When the reader changes step, unchanged code moves to its new place, and new code fades in.

:::tip[Good for:]
A file that grows over a few steps, where each step needs only a short label. The versions take the space of one block, and readers step through them with buttons. To explain each step in paragraphs next to the code, use [scrollycoding](https://ewels.github.io/starlight-codeblocks/features/scrollycoding/).
:::

````md
<CodeWalkthrough>

```js title="server.js" step="Create the app"
const app = express();

app.listen(3000);
```

```js title="server.js" step="Parse JSON bodies"
const app = express();
app.use(express.json());

app.listen(3000);
```

```js title="server.js" step="Add a health route"
const app = express();
app.use(express.json());

app.get('/health', (req, res) => {
  res.json({ ok: true });
});

app.listen(3000);
```

</CodeWalkthrough>
````

Click **Next**, and `app.listen(3000);` moves down while the new line fades in. Each numbered step shows one version of the file. The label of the current step shows next to the numbers.

## Syntax

| Syntax | Where |
|---|---|
| `<CodeWalkthrough>` ... `</CodeWalkthrough>` | Around the code blocks, in an MDX file |
| `step="<label>"` | Code block fence line of each step |

Import the component at the top of the MDX file:

```mdx
import { CodeWalkthrough } from 'starlight-codeblocks/components';
```

Put two or more code blocks between the tags, with an empty line after `<CodeWalkthrough>` and before `</CodeWalkthrough>`. Each code block is one step, in order. The `step` attribute is optional. Each step keeps its other attributes, such as `title`.

## Examples

### Steps without a title

A configuration file grows one section at a time. The steps have no titles, so the title bar shows the steps only:

````md
<CodeWalkthrough>

```yaml step="Name the site"
site:
  name: Example Docs
```

```yaml step="Add a search index"
site:
  name: Example Docs
search:
  index: true
```

</CodeWalkthrough>
````

### A refactor

A refactor changes the code inside a function. Code that stays moves to its new place, so readers see the loop become one call to `sum()`:

````md
<CodeWalkthrough>

```py title="prices.py" step="Before"
def total(items):
    result = 0
    for item in items:
        result += item.price
    return result
```

```py title="prices.py" step="With sum()"
def total(items):
    return sum(item.price for item in items)
```

</CodeWalkthrough>
````

## Behaviour

- The controls:
  - The title bar shows the title, the numbered steps and the label of the current step.
  - Earlier steps have an outline in the accent colour. The current step is filled.
  - When the mouse cursor is on a step, its border changes colour. This is true for earlier steps and the current step too.
  - A row under the block shows the **Previous** and **Next** buttons, with the step count between them, such as "Step 2 of 3".
  - When the steps are narrower than 480 px, the label is hidden. If the label is too long for the title bar, it ends with an ellipsis.
- Moving between steps:
  - Click a number to go to that step. You cannot click **Previous** on the first step, or **Next** on the last step.
  - When a numbered step has keyboard focus, the left and right arrow keys go to the previous and the next step.
- Screen readers:
  - Screen readers announce the number and the label of the new step.
  - The name of each numbered step gives the label to screen readers, also when the label is hidden.
- Copy and print:
  - The copy button copies the code of the current step.
  - The numbered steps and the row of **Previous** and **Next** buttons do not print. Each step prints in order, with its label.
- Without JavaScript:
  - Each step shows as a separate code block, in order, with its label after the title.
- Motion:
  - The animation takes 480 ms. Code that is in both versions moves. Removed code fades out, and new code fades in.
  - A line that is new in the step gets a green tint, which fades out in 1 second. The green is the terminal green of the theme.
  - When the reader's system asks for reduced motion, the steps change without the animation.

## Options

Code walkthrough has no options. To turn the feature off for the whole site, set `walkthrough` to `false`:

```js title="astro.config.mjs"
codeblocks({
  walkthrough: false,
});
```

With `walkthrough: false`, `<CodeWalkthrough>` shows each step as a separate code block with its label after the title, as it does without JavaScript. The page loads no script for the steps.

The style settings in the `codeblocksWalkthrough` group change the colours of the steps and the length of the animation. For example, `codeblocksWalkthrough.duration` sets the length of the animation, and `codeblocksWalkthrough.newLineBackground` sets the tint of new lines.

- [Configuration](https://ewels.github.io/starlight-codeblocks/configuration/): Learn how to set options for the whole site, or for a single code block.

## Limitations

- `<CodeWalkthrough>` works in MDX files only, because Markdown files cannot contain components.
- During the animation, the block shows the syntax colours only. Line numbers, line states and other decorations show again when the animation ends.
- A jump over several steps animates from the first version to the last. Code that exists in both only through a middle step fades out and in again.
- The page loads the animation library, about 3 kB, only on pages with `<CodeWalkthrough>`.

## Related

- [Scrollycoding](https://ewels.github.io/starlight-codeblocks/features/scrollycoding/): prose steps that change the focus of a block, and can change its code, as the reader scrolls.
- [Word-level diff](https://ewels.github.io/starlight-codeblocks/features/word-level-diff/): one block that marks the changed words between two versions.
- [Code tabs](https://ewels.github.io/starlight-codeblocks/features/code-tabs/): versions that are alternatives, such as package managers, and not steps in an order.

---

<!-- https://ewels.github.io/starlight-codeblocks/features/focus/ -->

# Focus

> Blur the lines outside a range, so that readers look at the lines that you name first.

A code block often shows a whole file, but the text around it is about a few lines. Focus blurs and fades every other line, so readers find those lines at once. The other lines stay in the block, because readers need them for context.

````md
```js title="src/config.js" focus={4-7}
import { defineConfig } from './lib.js';

export default defineConfig({
  cache: {
    dir: '.cache',
    maxAge: 3600,
  },
  retries: 2,
  verbose: false,
});
```
````

Lines 4 to 7 are sharp, and the other lines are blurred. Hover over the block, or move keyboard focus into it, to make every line sharp. The copy button copies the whole file.

## Syntax

| Syntax | Where |
|---|---|
| `focus={range}` | Code block fence line |
| `[!code focus]` | Comment |
| `[!code focus:N]` | Comment |
| `focus.style="blur"`, `focus.style="dim"` | Code block fence line |

`focus={range}` takes a [range](https://ewels.github.io/starlight-codeblocks/comment-notation/#line-numbers), such as `{2}` or `{1, 4-6}`. `[!code focus:N]` focuses its own line and the next N-1 lines. You can use the attribute and directives in the same block.

## Examples

### Focus with a directive

A directive moves with its line when you edit the code. Use one when the block can change:

````md
```py title="app.py"
import os

token = os.environ["API_TOKEN"]  # [!code focus]
url = "https://api.example.com/v1/items"
```
````

### Focus with a diff

Focus combines with the other line markers. Here the focused lines also show a change:

````md
```ts title="server.ts" focus={3-4}
import { createServer } from 'node:http';

const port = 3000; // [!code --]
const port = Number(process.env.PORT ?? 3000); // [!code ++]

createServer(handler).listen(port);
```
````

## Behaviour

- The blur:
  - Lines outside the focus are blurred and faded. Focused lines look the same as in a block without focus.
  - If no line is in focus, the block is the same as a block without the plugin.
- Hover and keyboard:
  - When the reader hovers over the block, or moves keyboard focus into it, every line becomes clear. The change takes 250 ms.
  - The code area takes keyboard focus, so keyboard readers can see every line. Tab moves focus into it.
- Screen readers:
  - Screen readers read every line, because the blurred lines stay in the page.
- Copy:
  - The copy button copies every line, focused or not.
- Without JavaScript:
  - Focus needs no JavaScript in the browser.
- Motion:
  - When the reader's system asks for reduced motion, the lines change without the transition.

## Options

### `focus`

Blurs the lines outside a focus range. Set it to `false` to turn the feature off. `[!code focus]` then stays in the code as written.

- Type: `false | object`
- Default: On

### `focus.style`

Blur and fade the other lines, or only fade them. A code block can set its own on its fence line.

- Type: `'blur' | 'dim'`
- Default: `'blur'`

Blur makes the other lines hard to read for some readers. If your site does not need the blur, use the `dim` style:

```js title="astro.config.mjs"
codeblocks({
  focus: { style: 'dim' },
});
```

To change the amount of blur, the opacity or the duration of the transition, use the `codeblocksFocus` style settings in `styleOverrides`:

```js title="ec.config.mjs"
export default {
  styleOverrides: {
    codeblocksFocus: { blur: '2px', opacity: '0.6', transitionDuration: '150ms' },
  },
};
```

- [Configuration](https://ewels.github.io/starlight-codeblocks/configuration/): Learn how to set options for the whole site, or for a single code block.

## Limitations

- Focus applies to whole lines. To point at a word on a line, use an [inline callout](https://ewels.github.io/starlight-codeblocks/features/inline-callouts/).
- Every line becomes clear while the mouse cursor is over the block. Readers who use a touch screen see every line after they touch the block.

## Related

- [Line states](https://ewels.github.io/starlight-codeblocks/features/line-states/): tint a line as an error, a warning or a note, with a message.
- [Hidden lines](https://ewels.github.io/starlight-codeblocks/features/hidden-lines/): remove lines from view but keep them in the copied text.
- [Scrollycoding](https://ewels.github.io/starlight-codeblocks/features/scrollycoding/): move the focus of one block as the reader scrolls through steps.

---

<!-- https://ewels.github.io/starlight-codeblocks/features/line-states/ -->

# Line states

> Tint lines as errors, warnings, notes or successes, with an optional message after the code, like the diagnostics in a code editor.

Expressive Code can mark a line, but a mark does not say what is wrong with the line. A line state tints the line as an error, a warning, a note or a success. It can also show a message after the code, as a code editor does.

````md
```py title="loop.py" info={1}
import sys

for name in sys.argv[1:]  # [!code error] SyntaxError: expected ':'
    print(name)

count = len(sys.argv)  # [!code warning] Includes the script name
```
````

Each state has its own colour and a bar on the left edge. The text after the directive becomes the message. The copy button copies the code without the messages.

## Syntax

| Syntax | Where |
|---|---|
| `error={range}`, `warning={range}`, `info={range}`, `success={range}` | Code block fence line |
| `[!code error] <message>` | Comment |
| `[!code warning] <message>` | Comment |
| `[!code info] <message>` | Comment |
| `[!code success] <message>` | Comment |
| `note`, `warn` | Both |
| `[!code ++] <message>`, `[!code --] <message>`, `[!code highlight] <message>` | Comment |
| `[!code <state>:N] <message>` | Comment |
| `<state>={range}`, `[!code <state>]` | Both |
| `lineStates.prefix=false`, `lineStates.prefix=true` | Code block fence line |

`note` is another name for `info`, and `warn` for `warning`.

The message is optional. An attribute tints the lines and shows no message. `[!code <state>:N]` tints its own line and the next N-1 lines, and shows the message on the first line.

Inline code, links and bold in a message render as HTML. Other Markdown stays as text.

## Examples

### A custom state

This site defines a `todo` state, as in the [custom state example](#add-a-custom-state). Use it to show readers the parts of a file that they must complete:

````md
```ts title="handler.ts"
export async function handler(request: Request) {
  const body = await request.json(); // [!code todo] Check the body against a schema
  return Response.json({ ok: true });
}
```
````

### A message on an inserted line

A message after `[!code ++]` tells readers why a line is new, for example in a step of a tutorial:

````md
```js title="astro.config.mjs"
import starlight from '@astrojs/starlight';
import codeblocks from 'starlight-codeblocks'; // [!code ++] Import the plugin

export default defineConfig({
  integrations: [starlight({ plugins: [codeblocks()] })], // [!code ++] Load the plugin
});
```
````

### Labels without the name of the state

With `prefix: false`, a label shows only the message, and a line without a message shows only the tint. Screen readers still hear the name of the state:

```js title="astro.config.mjs"
codeblocks({
  lineStates: { prefix: false },
});
```

To leave the names out of one block only, add `lineStates.prefix=false` to its fence line. `lineStates.prefix=true` shows them in one block when the option is off:

````md
```py title="config.py" lineStates.prefix=false
retries = -1  # [!code error] Must be 0 or more
timeout = 0.5  # [!code warning] Less than a second
```
````

### States without a message

An attribute marks lines without a message. Use it when the text around the block explains the problem:

````md
```js title="retry.js" warning={2-4}
export async function fetchWithRetry(url) {
  while (true) {
    try { return await fetch(url); } catch {}
  }
}
```
````

## Behaviour

- Tints and bars:
  - Each state has a background tint and a 3 px bar on the left edge.
  - If every line of a block has the same state, the tint covers the whole block, with one bar down its side.
  - A line can have more than one state. The line then shows the colour of the last state in the configuration.
- Labels:
  - A message shows after the code, as a small label. The label starts with the name of the state in bold: **Error**, **Warning**, **Note** or **Success**. With `prefix: false`, or `lineStates.prefix=false` on the fence line (the first line of the code block, with the language), the label shows only the message.
  - A line with no message shows a label with only the name of the state. In a group of lines with the same state, only the first line shows it. The colour then does not carry the meaning alone. With the names off, a line with no message shows only the tint.
  - A message after `[!code ++]`, `[!code --]` or `[!code highlight]` shows in the same label, in the colour of the marker. The label has no name before the message, because Expressive Code already marks the line. With `lineStates: false`, the message stays in the code as a comment.
- Screen readers:
  - Screen readers hear the name of the state before the line, for example "Error:". A screen reader reads the message after the code.
- Copy:
  - The copy button leaves out the messages. The names of the states and the messages are also not part of a manual text selection.
- Without JavaScript:
  - Line states need no JavaScript in the browser.

## Options

### `lineStates`

Tints lines as errors, warnings, notes or successes, with an optional message. Set it to `false` to turn the feature off. The directives then stay in the code as written.

- Type: `false | object`
- Default: On

### `lineStates.states`

Custom states by name, in addition to `error`, `warning`, `info` and `success`. A name uses lower-case letters, digits and hyphens.

- Type: `Record<string, { label: string; colour: { dark: string; light: string } }>`
- Default: `{}`

### `lineStates.prefix`

Show the name of the state, such as **Error**, before each message, and on the first line of a run with no message. Off, the tint alone marks the state on screen. A code block can set its own on its fence line.

- Type: `boolean`
- Default: `true`

### Add a custom state

A custom state works in the same way as a built-in state. Its name is the attribute and the directive.

1. Add the state to `lineStates.states`. Give it a label, and a colour for the dark and the light theme.

   ```js title="astro.config.mjs"
   codeblocks({
     lineStates: {
       states: {
         todo: { label: 'To do', colour: { dark: '#c792ea', light: '#7c3aed' } },
       },
     },
   });
   ```

2. Use the name as an attribute, such as `todo={9}`, or as a directive, such as `[!code todo]`.

A name uses lower-case letters, digits and hyphens. It cannot be the name of another attribute, such as `title` or `focus`. To change the label or the colour of a built-in state, add a state with its name, for example `info`.

The plugin makes the tint and the label colours from the colour that you give. Each colour must have a contrast of 3:1 or more against the background of the code, so that readers can see the bar.

- [Configuration](https://ewels.github.io/starlight-codeblocks/configuration/): Learn how to set options for the whole site, or for a single code block.

## Limitations

- A message is one line of text. A long message makes the line wider, and the block scrolls sideways.

## Related

- [Focus](https://ewels.github.io/starlight-codeblocks/features/focus/): blur the other lines, so readers look at a few lines first.
- [Inline callouts](https://ewels.github.io/starlight-codeblocks/features/inline-callouts/): show a longer note in a bubble above a line.
- [Annotations](https://ewels.github.io/starlight-codeblocks/features/annotations/): add a numbered marker that opens a note.

---

<!-- https://ewels.github.io/starlight-codeblocks/features/code-mentions/ -->

# Code mentions

> Link a phrase in the prose to lines of the code block below it, so that readers see which lines the text is about.

Prose often explains a code block line by line: "the base case stops the recursion". A reader must then find the base case in the block on their own. Code mentions tag the lines in the block with a name, and a link in the prose with that name highlights them.

````md
The [base case](#mention:base) stops the recursion. The [recursive step](#mention:step) calls the function again with a smaller number.

```py
def factorial(n):
    if n == 0:  # [!mention base]
        return 1  # [!mention base]
    return n * factorial(n - 1)  # [!mention step]
```
````

Hover over "base case", or move keyboard focus to it, to highlight lines 2 and 3. The other lines of the block fade. The page stays plain Markdown: the tags are comments, and the links are normal links.

## Syntax

| Syntax | Where |
|---|---|
| `[!mention <name>]` | Comment, at the end of a line |
| `[text](#mention:<name>)` | Prose |

Tag each line that belongs to a name. A name is one word, such as `base` or `parse-args`. One line can have more than one tag. The plugin removes the tags from the code and from the copied text.

## Examples

### Two names on one line

Two names can share a line. Here, the call to `fetch` is part of the request and of the error handling:

````md
The [request](#mention:request) sends the form data. The [error handling](#mention:errors) turns a failed response into an exception.

```js title="submit.js"
const response = await fetch('/api/signup', { method: 'POST', body: form }); // [!mention request] [!mention errors]
if (!response.ok) { // [!mention errors]
  throw new Error(`Sign-up failed: ${response.status}`); // [!mention errors]
}
```
````

## Behaviour

- Which block a link pairs with:
  - A link pairs with the next code block in the same section that has lines with its name. A section ends at the next heading. If no block follows in the section, the link pairs with the nearest block before it.
  - In a [code tabs](https://ewels.github.io/starlight-codeblocks/features/code-tabs/), only the variant that shows counts. Tag the same name in each variant, and the link follows the reader's choice.
- Hover, focus and click:
  - Hovering over the link, or moving keyboard focus to it, highlights the tagged lines with a tint and a bar. The other lines of the block fade to 42% opacity.
  - Clicking the link keeps the highlight, and scrolls the block into view if it is not fully visible. The address of the page does not change.
  - The links have a dotted underline, which becomes solid on hover and focus. On hover, a link keeps its colour.
- Screen readers:
  - Screen readers read the tagged lines as the description of the link.
- Warnings:
  - A link with no matching block shows as plain text, and the build logs a warning with the file name.
- Without JavaScript:
  - The links do nothing, and they look like other links.
- Motion:
  - The fade and the scroll happen without animation when the reader's system asks for reduced motion.

## Options

Code mentions have no options. Turn the feature off for the whole site with `mentions: false`:

```js title="astro.config.mjs"
codeblocks({
  mentions: false,
});
```

With `mentions: false`, `[!mention]` tags stay in the code, and `#mention:` links go nowhere.

### Links validator

The `starlight-links-validator` plugin reports `#mention:` links as broken, because no heading has that id. Give it the `linksValidatorExclude` function from this plugin in `astro.config.mjs`:

```js title="astro.config.mjs"
import codeblocks, { linksValidatorExclude } from 'starlight-codeblocks';

starlightLinksValidator({
  exclude: linksValidatorExclude,
}),
```

The function also skips links to [line permalinks](https://ewels.github.io/starlight-codeblocks/features/line-permalinks/). [Plugin compatibility](https://ewels.github.io/starlight-codeblocks/reference/plugin-compatibility/#starlight-links-validator) has the full set-up.

- [Configuration](https://ewels.github.io/starlight-codeblocks/configuration/): Learn how to set options for the whole site, or for a single code block.

## Limitations

- The build check reads links and tags in Markdown only. It does not see tags in a block from the `<Code>` component, so a link to that block shows as plain text.
- The tint and the fade show which lines a link names. A reader on a touch screen sees them after they tap the link.

## Related

- [Focus](https://ewels.github.io/starlight-codeblocks/features/focus/): blur every line outside a range for every reader, without a link.
- [Line permalinks](https://ewels.github.io/starlight-codeblocks/features/line-permalinks/): let readers link to lines, instead of the author.
- [Side annotations](https://ewels.github.io/starlight-codeblocks/features/side-annotations/): notes next to the block that highlight their line on hover.

---

<!-- https://ewels.github.io/starlight-codeblocks/features/hidden-lines/ -->

# Hidden lines

> Hide the imports and set-up that readers need to run an example but not to understand it.

A working example often needs lines that the reader can skip, such as imports, settings or the boilerplate around the part you explain. The `hidden` attribute and `[!code hide]` remove these lines from view, behind a marker the reader can open.

````md
```py title="summary.py" hidden={1-3,6-7}
import json
from pathlib import Path

config = json.loads(Path("config.json").read_text())
for key, value in config.items():
    if key.startswith("_"):
        continue
    print(f"{key} = {value}")
```
````

The imports and the `if` block are behind their own markers. Click a marker to show that run, or the title bar button to show every hidden line at once. Copying the block gives the whole file, imports included.

## Syntax

| Syntax | Where |
|---|---|
| `hidden={range}` | Code block fence line |
| `[!code hide]` | Comment |
| `[!code hide:N]` | Comment |

`hidden={range}` takes a [range](https://ewels.github.io/starlight-codeblocks/comment-notation/#line-numbers), such as `{2}` or `{1, 4-6}`. `[!code hide:N]` hides its own line and the next N-1 lines. You can use the attribute and the directive in the same block.

## Examples

### Hide lines with a directive

A directive keeps the hidden line next to the code it belongs to, so it moves if you reorder the block:

````md
```ts title="server.ts"
import { createServer } from 'node:http'; // [!code hide]
import { readFileSync } from 'node:fs'; // [!code hide]

const port = Number(process.env.PORT ?? 3000);
createServer((req, res) => res.end(readFileSync('index.html'))).listen(port);
```
````

### A block without a title

A block with no title still gets a title bar, which holds only the toggle button:

````md
```js hidden={1-2}
import { readFile } from 'node:fs/promises';

const notes = await readFile('notes.txt', 'utf8');
console.log(notes.length);
```
````

## Behaviour

- Markers:
  - Each run of hidden lines is replaced by a dashed marker, with the text "N hidden lines".
  - Clicking a marker shows that run only. Its text changes to "Hide N lines". The lines get a faint background, and their code is dimmed to 75% opacity, so the reader can tell they asked for them.
  - The dashed rule of a marker gets brighter when the mouse cursor is on it, and fainter while its lines show.
- The title bar button:
  - The title bar has a button, "Show N hidden lines", where N is the total across every run. It shows every run at once. Once every run is open, it reads "Hide N lines".
- Screen readers:
  - Each marker has `aria-expanded`. The label of the title bar button changes from **Show** to **Hide**. Both have `aria-controls`, so assistive technology reports what they open.
- Copy and print:
  - The copy button always includes hidden lines, so the code still runs after a paste. A manual selection includes only the hidden lines that are open, and never the text of a marker.
  - Hidden lines stay hidden when the page prints. The markers and the title bar button do not print.
- Other features:
  - An [inline callout](https://ewels.github.io/starlight-codeblocks/features/inline-callouts/) on a hidden line shows only while the line is open.
- Without JavaScript:
  - Hidden lines stay hidden, and the markers and the title bar button do nothing.

## Options

Hidden lines have no options. Turn the feature off for the whole site with `hiddenLines: false`:

```js title="astro.config.mjs"
codeblocks({
  hiddenLines: false,
});
```

With `hiddenLines: false`, the plugin ignores `hidden={range}`, and `[!code hide]` stays in the code as written.

- [Configuration](https://ewels.github.io/starlight-codeblocks/configuration/): Learn how to set options for the whole site, or for a single code block.

## Hidden lines or collapsible sections

Expressive Code has its own plugin for a similar job, [`@expressive-code/plugin-collapsible-sections`](https://expressive-code.com/plugins/collapsible-sections/). Its `collapse={range}` attribute folds lines into a section with a summary line, such as "3 collapsed lines". The plugin is not part of Starlight, so a site must install it and add it to the `plugins` list of its `ec.config.mjs` file. That list replaces the plugins of Starlight, so add `pluginCodeblocks()` to it too, as in [Sites with an ec.config.mjs file](https://ewels.github.io/starlight-codeblocks/getting-started/#sites-with-an-ecconfigmjs-file):

```js title="ec.config.mjs"
import { pluginCollapsibleSections } from '@expressive-code/plugin-collapsible-sections';
import { pluginCodeblocks } from 'starlight-codeblocks/expressive-code';

export default {
  plugins: [pluginCollapsibleSections(), pluginCodeblocks()],
};
```

This site uses the plugin, so the examples below are live. Here is the first example of this page again, with `collapse` in place of `hidden`:

````md
```py title="summary.py" collapse={1-3,6-7}
import json
from pathlib import Path

config = json.loads(Path("config.json").read_text())
for key, value in config.items():
    if key.startswith("_"):
        continue
    print(f"{key} = {value}")
```
````

Each section keeps a summary line in the block, where hidden lines leave only a thin marker. Click a summary line to open its section.

With `collapseStyle`, an open section keeps a line to close it again. `collapsible-auto` puts that line at the start of the section, or at the end if the section ends the block:

````md
```py title="summary.py" collapse={6-7} collapseStyle="collapsible-auto"
import json
from pathlib import Path

config = json.loads(Path("config.json").read_text())
for key, value in config.items():
    if key.startswith("_"):
        continue
    print(f"{key} = {value}")
```
````

The two features compare as follows:

| Aspect | Hidden lines | Collapsible sections |
|---|---|---|
| Space before a reader opens it | A thin dashed marker | A full summary line for each section |
| Syntax | `hidden={range}`, `[!code hide]` and `[!code hide:N]` | `collapse={range}` |
| Show every section at once | A title bar button | No |
| Open lines look different | Yes: a faint background, and code at 75% opacity | Only with a `collapsible-*` style |
| Close a section again | The marker, or the title bar button | The summary line, with a `collapsible-*` style |
| Copy button | Copies every line | Copies every line |
| Without JavaScript | The lines stay hidden | Works: the sections are HTML `<details>` elements |
| Needs | This plugin | A separate Expressive Code plugin |

Use hidden lines for lines that most readers never need, such as imports, and when the block must stay compact. The directive keeps the hidden state next to its line, so it moves when you edit the block. Use collapsible sections when readers often open the lines, or when the page must work without JavaScript. Both plugins work on one site, and each block can use either one.

## Limitations

- A hidden line still runs in the copied code. If a line depends on something the reader must change, such as an API key, keep it visible or use a [fill-in placeholder](https://ewels.github.io/starlight-codeblocks/features/fill-in-placeholders/) instead.

## Related

- [Focus](https://ewels.github.io/starlight-codeblocks/features/focus/): blur the lines around the ones you explain, and keep them in view.
- [Expandable blocks](https://ewels.github.io/starlight-codeblocks/features/expandable-blocks/): cap a long block at a line count, instead of a list of lines to hide.
- [Collapsible sections](https://expressive-code.com/plugins/collapsible-sections/): the Expressive Code plugin that folds lines behind a summary line.
- [Comment notation](https://ewels.github.io/starlight-codeblocks/comment-notation/): the directive syntax that `[!code hide]` uses.

---

<!-- https://ewels.github.io/starlight-codeblocks/features/expandable-blocks/ -->

# Expandable blocks

> Show the first lines of a long block, with a fade and a button to reveal the rest.

A full file is sometimes the clearest example, but a reader who scans the page does not need every line in view at once. The `expandable` attribute caps the block at a line count, with a fade at the cut and a button that reveals the rest.

````md
```py title="report.py" expandable={8}
import csv
import sys
from collections import Counter
from pathlib import Path


def read_rows(path: Path) -> list[dict]:
    with path.open() as fh:
        return list(csv.DictReader(fh))


def summarise(rows: list[dict]) -> Counter:
    return Counter(row["status"] for row in rows)


def main() -> None:
    rows = read_rows(Path(sys.argv[1]))
    counts = summarise(rows)
    for status, n in counts.most_common():
        print(f"{status:<10} {n:>5}")


if __name__ == "__main__":
    main()
```
````

The block shows its first eight lines, faded at the bottom, with "Show all 24 lines" underneath. Clicking the button reveals the rest, and the button then reads "Show fewer lines".

## Syntax

| Syntax | Where | Effect |
|---|---|---|
| `expandable` | Code block fence line | Caps the block at the site default, 12 lines |
| `expandable={N}` | Code block fence line | Caps the block at `N` lines |
| `expandable=false` | Code block fence line | Turns off the `auto` option for the block |
| `expandable.lines=<N>` | Code block fence line | The line count for the block when it expands through `expandable` or `auto` |

## Examples

### The site default

`expandable` with no number uses the site default:

````md
```yaml title=".github/workflows/ci.yml" expandable
name: CI

on:
  push:
    branches: [main]
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7

      - uses: actions/setup-node@v4
        with:
          node-version: 22

      - run: npm ci

      - run: npm test
```
````

## Behaviour

- The collapsed block:
  - The block shows the first `N` lines, with a fade over the last one.
  - A bar under the code has a button, "Show all X lines", where X is the total. When the block is open, it reads "Show fewer lines".
- Other ways to open the block:
  - The collapsed lines use `hidden="until-found"` in browsers that support it. A reader who searches the page with Find still finds text inside them, and the block expands to show the match.
  - A [line permalink](https://ewels.github.io/starlight-codeblocks/features/line-permalinks/) to a collapsed line opens the block.
- Which blocks collapse:
  - A block collapses only if the collapse hides three lines or more. A block with eight lines and `expandable={7}` renders in full.
  - Lines that [hidden lines](https://ewels.github.io/starlight-codeblocks/features/hidden-lines/) remove do not count. In a block of 20 lines with `hidden={1-8} expandable={5}`, readers see 5 lines, and the button reads "Show all 12 lines".
  - A block with Expressive Code's `collapse` attribute does not collapse, even with `expandable`, because its collapsed sections already shorten it.
- Without JavaScript:
  - The block renders in full, with no fade and no button.
- Motion:
  - The block eases open and closed in 200 ms. The button stays under the mouse cursor while the block closes.
  - With reduced motion, the block opens and closes at once.

## Options

### `expandable`

Shows the first lines of long blocks, with a button to show the rest. Set it to `false` to turn the feature off. `expandable` and `expandable={N}` then have no effect.

- Type: `false | object`
- Default: On

### `expandable.lines`

Lines to show before the block expands. A code block can set its own on its fence line.

- Type: `number`
- Default: `12`

### `expandable.auto`

Makes every block with more lines than this expandable, without the attribute. `expandable=false` turns it off for one block.

- Type: `number | false`
- Default: `false`

To show more lines in blocks with the bare `expandable` attribute, raise `lines`:

```js title="astro.config.mjs"
codeblocks({
  expandable: { lines: 20 },
});
```

### Make every long block expandable

The `auto` option makes every block with more lines than its value expandable, with no attribute. The block shows `lines` lines:

```js title="astro.config.mjs"
codeblocks({
  expandable: { lines: 12, auto: 30 },
});
```

With this configuration, a block of 31 lines or more shows its first 12 lines. Add `expandable=false` to the fence line (the first line of the code block, with the language) of a block that must show in full. An `expandable={N}` attribute wins over the option.

`auto` skips blocks that have their own layout or their own controls:

- The variants of a [code tabs](https://ewels.github.io/starlight-codeblocks/features/code-tabs/).
- Blocks with a [**Run code** button](https://ewels.github.io/starlight-codeblocks/features/run-code/).
- Blocks with Expressive Code's `collapse` attribute, from its collapsible sections plugin.
- Blocks in [`<CodeWalkthrough>`](https://ewels.github.io/starlight-codeblocks/features/code-walkthrough/) and [`<Scrollycoding>`](https://ewels.github.io/starlight-codeblocks/features/scrollycoding/), where each step must show every line.

- [Configuration](https://ewels.github.io/starlight-codeblocks/configuration/): Learn how to set options for the whole site, or for a single code block.

## Limitations

- Expandable blocks print in full: the fade and the button do not appear on paper.

## Related

- [Hidden lines](https://ewels.github.io/starlight-codeblocks/features/hidden-lines/): remove specific lines from view, instead of capping the block at a line count.
- [Focus](https://ewels.github.io/starlight-codeblocks/features/focus/): keep every line in view, and blur the ones that do not matter.

---

<!-- https://ewels.github.io/starlight-codeblocks/features/visible-whitespace/ -->

# Visible whitespace

> Show spaces and tabs as faint glyphs, for the blocks where indentation changes the meaning of the code.

A code block usually renders whitespace as empty space. That is fine for most languages, but some depend on the exact character. Make needs a tab at the start of a recipe, and Python needs consistent indentation. The `whitespace` attribute shows spaces and tabs as glyphs, so readers see which character is there.

````md
```make title="Makefile" whitespace
build:
	cargo build --release

test:
    cargo test  # Recipes must start with a tab
```
````

The first recipe starts with an arrow, for the tab that Make needs. The second starts with four dots, for the four spaces that Make rejects. Copying the block gives the real characters, not the glyphs.

## Syntax

| Syntax | Where | Effect |
|---|---|---|
| `whitespace` | Code block fence line | Shows the leading whitespace of every line |
| `whitespace="all"` | Code block fence line | Shows every space and tab in the block |

## Examples

### Every space and tab

`whitespace="all"` shows every space, which is useful when trailing whitespace is part of what you are explaining:

````md
```text title="diff.patch" whitespace="all"
-  const width = 10; 
+  const width = 12;
```
````

## Behaviour

- The glyphs:
  - A space renders as a middle dot. A tab renders as an arrow at the start of the tab. The tab keeps its width up to the next tab stop. The plugin sets the CSS `tab-size` property of code blocks to 2 columns.
  - By default, the plugin shows only the leading whitespace of each line, where indentation usually matters. `whitespace="all"` shows every space and tab, including the ones between words and at the end of a line.
  - The glyphs are faint, so that they do not compete with the code. They use the text colour of the theme at about a third of its strength.
- Screen readers:
  - Screen readers do not hear the glyphs. They read the same code as a block without the attribute.
- Copy:
  - The glyphs are drawn with CSS on top of the real character. A manual copy or the copy button gives the actual spaces and tabs.
- Without JavaScript:
  - Visible whitespace needs no JavaScript in the browser.

## Options

Visible whitespace has no options. Turn it off for the whole site with `whitespace: false`:

```js title="astro.config.mjs"
codeblocks({
  whitespace: false,
});
```

The style setting `codeblocksWhitespace.foreground` changes the colour of the glyphs.

- [Configuration](https://ewels.github.io/starlight-codeblocks/configuration/): Learn how to set options for the whole site, or for a single code block.

## Limitations

- The glyphs add visual noise on a block with a lot of whitespace. Use `whitespace="all"` only where the extra detail matters, and leave the default, leading-only view for everything else.
- Expressive Code removes the whitespace at the end of each line before any plugin sees the code. The plugin puts it back for fenced code blocks in Markdown and MDX. A block that the `<Code>` component renders does not show trailing whitespace.
- Expressive Code turns every tab into spaces before this feature can see it. `codeblocks()` sets `tabWidth: 0` for you unless you already chose your own value. A site without Starlight sets `tabWidth: 0` in `ec.config.mjs` itself. A tab then reaches the plugin unchanged, and a Makefile block copies its real tab rather than spaces. Set `expressiveCode.tabWidth` in the Starlight config, or `tabWidth` in `ec.config.mjs`, for Expressive Code's normal tab-to-space expansion instead.

## Related

- [Line states](https://ewels.github.io/starlight-codeblocks/features/line-states/): mark the line that has the indentation problem, with a message that explains it.

---

<!-- https://ewels.github.io/starlight-codeblocks/features/colourised-brackets/ -->

# Colourised brackets

> Colour matching brackets by nesting depth, so a dense line of code stays readable.

A line with several levels of nested brackets is hard to scan: every `(`, `[` and `{` looks the same. The `brackets` attribute colours each bracket by how deep it is nested, cycling through three colours. A reader can then follow a pair by its colour.

````md
```js brackets
const title = document.title;
const slug = encodeURIComponent(
  kebab(trim(title.toLowerCase()))
);
```
````

The colour cycles every three levels, so the outermost call and the innermost call share a colour. Hover over a bracket to outline it and its partner, so you can tell the two pairs apart even when their colour repeats.

## Syntax

| Syntax | Where |
|---|---|
| `brackets` | Code block fence line |
| `brackets=false` | Code block fence line |

## Examples

### Brackets inside a string

Brackets inside a string stay the normal string colour:

````md
```js brackets
const pattern = "(group)";
```
````

## Behaviour

- Colours:
  - `()`, `[]` and `{}` cycle through three colours by nesting depth.
  - Brackets inside a string or a comment keep the normal syntax colour, so they do not compete with the real structure of the code.
  - A bracket with no partner, such as one from an incomplete example, keeps its normal colour.
- Matching pairs:
  - Hovering over a bracket outlines it and its matching partner with a solid line. The pair then stands out by shape, not only by colour.
  - Readers who use caret browsing (F7 in most browsers) get the same outline when the caret is on a bracket.
- Without JavaScript:
  - The colours work without JavaScript. The outline needs JavaScript, and does nothing without it.

## Options

### `brackets`

Colours matching brackets by nesting depth. Set it to `false` to turn the feature off.

- Type: `false | object`
- Default: On

### `brackets.languages`

Languages that get colourised brackets in every block.

- Type: `string[]`
- Default: `[]`

A site that writes a lot of deeply nested JavaScript or JSON can turn colourised brackets on for those languages by default:

```js title="astro.config.mjs"
codeblocks({
  brackets: { languages: ['js', 'json'] },
});
```

Each name also covers the other names of its language, so `js` also turns on the colours in `javascript` and `mjs` blocks.

To turn the colours off for one block of those languages, add `brackets=false` to its fence line. The fence line is the first line of the code block, with the language.

- [Configuration](https://ewels.github.io/starlight-codeblocks/configuration/): Learn how to set options for the whole site, or for a single code block.

## Limitations

- On a short line with only one level of nesting, the colours add little. Use the attribute for lines that are hard to scan, or turn it on for a whole language with `brackets.languages` when it is usually dense.
- The plugin finds strings and comments with the comment syntax of the block's language, not a full parser. A language with unusual string syntax can colour a bracket that is inside a string.

## Related

- [Focus](https://ewels.github.io/starlight-codeblocks/features/focus/): blur everything except the lines with the brackets you are explaining.
- [Comment notation](https://ewels.github.io/starlight-codeblocks/comment-notation/): the comment syntax map that colourised brackets reads to skip comments.

---

<!-- https://ewels.github.io/starlight-codeblocks/features/colour-swatches/ -->

# Colour swatches

> Show a small swatch of each CSS colour next to its value, so readers see the colour without a colour picker.

A hex value such as `#ff5f1f` tells most readers little about the colour. The plugin puts a small swatch before each CSS colour in a code block, in the colour itself. Swatches are on for every code block, so you do not add an attribute.

````md
```css
.button {
  color: #ffffff;
  background: rebeccapurple;
  border: 1px solid rgb(102 51 153 / 50%);
}
```
````

Each value keeps its text, and the swatch comes before it. Hover over a colour to show it on a chip in its own colour. Click a colour to copy it.

## Syntax

Each attribute goes on the code block fence line.

| Syntax | What it does |
|---|---|
| `swatches=false` | Turns off the swatches for the block. |
| `swatches` | Turns on the swatches for a block of a language outside `swatches.languages`. |
| `swatches.shape="square"` | Draws square swatches in the block. |
| `swatches.shape="rounded"` | Draws swatches with rounded corners in the block. |
| `swatches.shape="circle"` | Draws round swatches in the block. |
| `swatches.match="all"` | Shows a swatch for every hex colour and colour function in the block. |
| `swatches.match="value"` | Shows a swatch only for colours that look like values in the block. |

## Examples

### Every kind of colour

Hex colours, the CSS colour functions and the colour names all get a swatch:

````md
```css
:root {
  --brand: #ff5f1f;
  --link: rgb(37 99 235);
  --success: hsl(142deg 71% 45%);
  --muted: hwb(220 60% 30%);
  --warm: lab(62% 45 60);
  --cool: lch(55% 60 260);
  --mint: oklab(0.8 -0.12 0.04);
  --violet: oklch(60% 0.2 300);
  --wide: color(display-p3 0.2 0.7 0.4);
  --shadow: black;
}
```
````

### Swatch shapes

`swatches.shape` sets the shape for one block. The `swatches.shape` option sets it for the site:

````md
```css swatches.shape="square"
.tag { background: #22c55e; }
```

```css swatches.shape="rounded"
.tag { background: #22c55e; }
```

```css swatches.shape="circle"
.tag { background: #22c55e; }
```
````

### Colours with transparency

A colour with an alpha value shows a checkerboard through its swatch:

````md
```css
.overlay {
  background: rgb(15 23 42 / 40%);
  border-color: #ff5f1f80;
  box-shadow: 0 4px 12px hsl(0 0% 0% / 0.25);
}
```
````

### Colours in other languages

Outside stylesheets, the plugin finds colours only where they look like values: in quotes, or after a `:`, `=` or `,`. A comment such as `// TODO #add` keeps its text:

````md
```js
// TODO #add a dark theme
const theme = {
  text: '#1e1e2e',
  accent: 'tomato',
};
```
````

### Every colour in a block

Some languages put colours where they do not look like values, such as after a `|`. Add `swatches.match="all"` to show a swatch for every hex colour and colour function:

````md
```text swatches.match="all"
%%metro line: main | Main | #4caf50
%%metro line: qc | Quality Control | #2196f3 | dashed
```
````

### Turn off swatches for one block

Add `swatches=false` to the fence line. The fence line is the first line of the code block, with the language:

````md
```css swatches=false
:root { --accent: #ff5f1f; }
```
````

### Colours in the prose

With the `swatches.prose` option, colours in the text of a page also get a swatch. This site turns it on:

```md
The brand colour is #ff5f1f. Use `rebeccapurple` for links.
```

## Behaviour

- Colours:
  - Hex colours with three, four, six or eight digits, and the CSS colour names, such as `rebeccapurple`.
  - The colour functions `rgb()`, `rgba()`, `hsl()`, `hsla()`, `hwb()`, `lab()`, `lch()`, `oklab()`, `oklch()` and `color()`.
  - A colour function gets a swatch only when it has numbers in it. `rgb(var(--r), 0, 0)` has no swatch, because the plugin cannot know its colour.
  - A colour with transparency shows a checkerboard through the swatch.
- What is not a colour:
  - In CSS, Sass, Less and Stylus blocks, ID selectors such as `#bad { }` and classes such as `.red`.
  - Variables such as `$green` and `--blue`, and SVG references such as `url(#fade)`.
  - In other languages, colour names that are not in quotes, such as `paint(red)`.
  - In other languages, hex that does not look like a value, such as `// TODO #add`. The `swatches.delimiters` option adds text, such as `|`, that can come before or after a value.
  - With `swatches.match="all"`, issue numbers such as #123 and words such as #add that are not in quotes.
  - In the prose, issue numbers such as #123, tags such as #cafe, and colour names such as red that are not inline code.
- Hover and copy:
  - Hovering over a colour shows it on a chip in its own colour, with a darker border. The text turns black or white, whichever reads on the colour.
  - After a short pause, **Click to copy** shows next to the colour.
  - Clicking a colour copies its value, and **Copied** shows next to it. A colour is a button, so you can also move to it with Tab and press Enter or Space.
  - The swatches copy no text. The copy button and a selection copy the code as written.
- Without JavaScript:
  - The swatches and the hover tint work without JavaScript. Copy needs JavaScript, and without it a colour is plain text.

## Options

### `swatches`

Shows a swatch of the colour before each CSS colour in code. Set it to `false` to turn the feature off.

- Type: `false | object`
- Default: On

### `swatches.languages`

Languages that get swatches. `swatches` on the fence line turns them on for one block of another language.

- Type: `'all' | string[]`
- Default: `'all'`

### `swatches.formats`

The kinds of colour that get swatches. `rgb` also covers `rgba()`, and `hsl` covers `hsla()`. `named` is the CSS colour names, such as `rebeccapurple`.

- Type: `Array<'hex' | 'rgb' | 'hsl' | 'hwb' | 'lab' | 'lch' | 'oklab' | 'oklch' | 'color' | 'named'>`
- Default: `['hex','rgb','hsl','hwb','lab','lch','oklab','oklch','color','named']`

### `swatches.shape`

The shape of each swatch. A code block can set its own on its fence line.

- Type: `'square' | 'rounded' | 'circle'`
- Default: `'rounded'`

### `swatches.size`

The width and height of each swatch, as a CSS length such as `10px` or `0.8em`.

- Type: `string`
- Default: `'0.8em'`

### `swatches.hover`

Tint the colour text in its own colour, and enlarge the swatch, when the mouse cursor is on it.

- Type: `boolean`
- Default: `true`

### `swatches.copy`

Copy the colour when the reader clicks it.

- Type: `boolean`
- Default: `true`

### `swatches.prose`

Also show swatches in the text of Markdown pages, and in inline code that is one colour. Named colours get a swatch only in inline code.

- Type: `boolean`
- Default: `false`

### `swatches.match`

Outside stylesheets, `value` shows a swatch only for a colour that looks like a value. `all` shows a swatch for every hex colour and colour function. A code block can set its own on its fence line.

- Type: `'value' | 'all'`
- Default: `'value'`

### `swatches.delimiters`

More text that can come before or after a colour that looks like a value, such as `|`. They add to the built-in delimiters.

- Type: `{ before?: string[]; after?: string[] }`
- Default: `{}`

### `swatches.byLanguage`

A `match` and `delimiters` for the blocks of each language. They replace the site settings for that language.

- Type: `Record<string, { match?: 'value' | 'all'; delimiters?: { before?: string[]; after?: string[] } }>`
- Default: `{}`

To show swatches for hex colours only, as circles, in CSS blocks only:

```js title="astro.config.mjs"
codeblocks({
  swatches: { formats: ['hex'], shape: 'circle', languages: ['css'] },
});
```

With `swatches.languages` set, add `swatches` to the fence line of a block of another language to turn on its swatches.

To find colours after and before a `|` in Mermaid blocks only, and every colour in `metro` blocks:

```js title="astro.config.mjs"
codeblocks({
  swatches: {
    byLanguage: {
      mermaid: { delimiters: { before: ['|'], after: ['|'] } },
      metro: { match: 'all' },
    },
  },
});
```

The `swatches.match` and `swatches.delimiters` options set the same for every language. A language in `swatches.byLanguage` uses its own settings in place of them.

- [Configuration](https://ewels.github.io/starlight-codeblocks/configuration/): Learn how to set options for the whole site, or for a single code block.

## Limitations

- The plugin finds colours with patterns, not a CSS parser. A rare value can get a swatch that it does not need. Add `swatches=false` to that block.
- A colour that comes from a variable, such as `var(--accent)`, has no swatch.
- A swatch adds width to its line, so a column of values after it moves to the right.

## Related

- [Colourised brackets](https://ewels.github.io/starlight-codeblocks/features/colourised-brackets/): colour bracket pairs by depth, for dense lines with nested calls.
- [Inline code highlighting](https://ewels.github.io/starlight-codeblocks/features/inline-code-highlighting/): give inline code in the prose the syntax colours of the code blocks.

---

<!-- https://ewels.github.io/starlight-codeblocks/features/file-icons/ -->

# File icons

> Show the icon of the file type before the title of a code block, with the icons of the Starlight file tree or a coloured icon set.

A code block with a title shows the file name in the title bar. The plugin puts the icon of the file type before that name. By default, it uses the coloured icons of vscode-icons, the icon theme of VS Code. Two other coloured sets are available. The one-colour Seti set makes a file look the same as in the Starlight `<FileTree>` component.

````md
The default vscode-icons:

```js title="src/index.js"
export const greet = (name) => console.log('Hello', name);
```

Material Icon Theme, with `fileIcons.set="material"`:

```py title="app.py" fileIcons.set="material"
print("Hello from Python")
```

The Seti icons of the Starlight file tree, with `fileIcons.set="seti"`:

```json title="package.json" fileIcons.set="seti"
{ "name": "my-site", "type": "module" }
```

Catppuccin, with `fileIcons.set="catppuccin"`:

```dockerfile title="Dockerfile" fileIcons.set="catppuccin"
FROM node:22-alpine
CMD ["node", "src/index.js"]
```
````

File icons are on for every code block with a title, so you do not add an attribute. The plugin finds the icon from the file name in the title. When the title is not a file name, the icon comes from the language of the code block. The `fileIcons.set` attribute changes the icon set for one block, and the `fileIcons.set` option changes it for the site.

## Syntax

Each attribute goes on the code block fence line. The fence line is the first line of the code block, with the language.

| Syntax | Where |
|---|---|
| `icon="<name>"` | Code block fence line. Sets the icon by name, such as `react`. |
| `icon=false` or `no-icon` | Code block fence line. Removes the icon. |
| `fileIcons.set="vscode-icons"` | Code block fence line. Takes the icon from the coloured vscode-icons icons. |
| `fileIcons.set="material"` | Code block fence line. Takes the icon from the coloured Material Icon Theme icons. |
| `fileIcons.set="seti"` | Code block fence line. Takes the icon from the one-colour Seti icons. |
| `fileIcons.set="catppuccin"` | Code block fence line. Takes the icon from the coloured Catppuccin icons. |
| `fileIcons.style="plain"` | Code block fence line. Shows the icon alone. |
| `fileIcons.style="tile"` | Code block fence line. Shows the icon on a square with rounded corners. |
| `fileIcons.colour="<colour>"` | Code block fence line. Sets a CSS colour for the icon, or for the square of a tile. |

## Examples

### Coloured icons

The `vscode-icons`, `material` and `catppuccin` sets have coloured icons, each with its own rules for file names. [Icon sets](#icon-sets) lists the package that each set needs:

````md
```json title="package.json" fileIcons.set="material"
{ "name": "my-site", "type": "module" }
```

```json title="package.json" fileIcons.set="vscode-icons"
{ "name": "my-site", "type": "module" }
```

```json title="package.json" fileIcons.set="catppuccin"
{ "name": "my-site", "type": "module" }
```

```py title="app.py" fileIcons.set="catppuccin" fileIcons.style="tile"
print("Hello")
```
````

Some icons have a variant for light themes, and the block shows the variant for its theme. In a tile, a coloured icon sits on a neutral square.

### GitHub files

Files in a `.github` folder and `.gitattributes` get the GitHub icon, from the whole path in the title:

````md
```yaml title=".github/workflows/test.yml"
on: [push, pull_request]
```
````

### Icons in a tile

The `tile` style puts a one-colour icon, such as a Seti icon, on a square in the accent colour of the theme. With a custom colour, the icon is black or white, whichever reads on the square:

````md
```py title="app.py" fileIcons.set="seti" fileIcons.style="tile"
print("Hello")
```

```py title="app.py" fileIcons.set="seti" fileIcons.style="tile" fileIcons.colour="#3776ab"
print("Hello")
```

```js title="app.js" fileIcons.set="seti" fileIcons.style="tile" fileIcons.colour="#f7df1e"
console.log('Hello');
```
````

### Set the icon

`icon` sets the icon by name. In the Seti set, the names are the names of the Starlight icons, with or without the `seti:` prefix. Each coloured set has its own names, which [All file icons](https://ewels.github.io/starlight-codeblocks/features/file-icons/all/) shows when you hover over an icon. A Seti name works in every set:

````md
```js title="App" icon="react"
export const App = () => <h1>Hello</h1>;
```
````

### Colour an icon

`fileIcons.colour` takes a CSS colour. Use `light-dark()` to give a different colour in the dark and the light theme:

````md
```toml title="Cargo.toml" fileIcons.colour="light-dark(#f74c00, #b33600)"
[package]
name = "hello"
```
````

### Custom icons

The `fileIcons.icons` option adds icons by name. This site adds the Nextflow icon from Simple Icons, links it to the `.nf` extension and the `nextflow` language, and gives it the Nextflow green:

````md
```nextflow title="main.nf"
workflow {
    Channel.of('Hello').view()
}
```
````

```js title="astro.config.mjs"
import { siNextflow } from 'simple-icons';

codeblocks({
  fileIcons: {
    icons: { nextflow: siNextflow.svg },
    files: { '.nf': 'nextflow', 'nextflow.config': 'nextflow' },
    languages: { nextflow: { icon: 'nextflow', colour: '#31C9AC' } },
  },
});
```

## Behaviour

- How the plugin finds the icon:
  - First, the `icon` attribute.
  - Then the rules of the `fileIcons.files` option, on the whole path in the title.
  - Then the GitHub rules: `.github/**` and `.gitattributes`.
  - Then the rules of the icon set. The Seti set reads the file name at the end of the title, as `<FileTree>` does.
  - In the Seti set, the full name comes first, such as `Dockerfile`. Then the extension, such as `.test.ts` and then `.ts`.
  - Then the language of the code block, such as `py` or `python`.
  - Then the default file icon.
  - A `false` in `fileIcons.files` or `fileIcons.languages` stops the search, and the block gets no icon. The `icon` attribute still sets one.
  - When two keys of `fileIcons.files` match a title, the later key wins.
- Where icons show:
  - In the title of an editor frame. Terminal frames and code blocks with no title get no icon.
  - [Code tabs](https://ewels.github.io/starlight-codeblocks/features/code-tabs/) show the icon of each file on its tab. The code tabs menu shows the icon of each language, custom icons too.
- Colours:
  - A `plain` icon has the colour of the title text.
  - A `tile` has the accent colour of the theme, with the icon in the text colour for that accent.
  - A colour from the site or the code block replaces both.
  - A coloured icon keeps its colours. A colour from the site or the code block draws it in that one colour.
- Screen readers:
  - The icon is decorative. Screen readers read the title only.

With the Seti set, a file in a `<FileTree>` has the same icon as a code block with that file name as its title:

- package.json
- app.py
- Cargo.toml
- Dockerfile
- src/
  - index.js

## Icon sets

The `fileIcons.set` option sets the icons for the whole site. vscode-icons and Seti come with the plugin. Material and Catppuccin each need one package, which you add to the site:

| Set | Icons | Package |
|---|---|---|
| `vscode-icons` | [vscode-icons](https://github.com/vscode-icons/vscode-icons). The default. | None |
| `material` | [Material Icon Theme](https://github.com/material-extensions/vscode-material-icon-theme) | `@iconify-json/material-icon-theme` |
| `catppuccin` | [Catppuccin Icons](https://github.com/catppuccin/vscode-icons), in Macchiato colours, and Latte colours in light themes | `@iconify-json/catppuccin` |
| `seti` | The one-colour icons of the Starlight `<FileTree>` | None |

```sh
npm install @iconify-json/catppuccin
```

The plugin has the file name rules of each set, so a site downloads only the icons of the set that it uses. These files show the icon of each set:

| File | Seti | Material | vscode-icons | Catppuccin |
|---|---|---|---|---|
| JavaScript `index.js` | `javascript` | `javascript` | `file-type-js` | `javascript` |
| TypeScript `index.ts` | `typescript` | `typescript` | `file-type-typescript` | `typescript` |
| React `App.tsx` | `react` | `react-ts` | `file-type-reactts` | `typescript-react` |
| Python `main.py` | `python` | `python` | `file-type-python` | `python` |
| Rust `main.rs` | `rust` | `rust` | `file-type-rust` | `rust` |
| Go `main.go` | `go` | `go` | `file-type-go` | `go` |
| Java `Main.java` | `java` | `java` | `file-type-java` | `java` |
| Kotlin `Main.kt` | `kotlin` | `kotlin` | `file-type-kotlin` | `kotlin` |
| C `main.c` | `c` | `c` | `file-type-c` | `c` |
| C++ `main.cpp` | `cpp` | `cpp` | `file-type-cpp` | `cpp` |
| C# `Program.cs` | `c-sharp` | `csharp` | `file-type-csharp` | `csharp` |
| Ruby `app.rb` | `ruby` | `ruby` | `file-type-ruby` | `ruby` |
| PHP `index.php` | `php` | `php` | `file-type-php` | `php` |
| Swift `main.swift` | `swift` | `swift` | `file-type-swift` | `swift` |
| Shell `install.sh` | `shell` | `console` | `file-type-shell` | `bash` |
| PowerShell `install.ps1` | `powershell` | `powershell` | `file-type-powershell` | `powershell` |
| HTML `index.html` | `html` | `html` | `file-type-html` | `html` |
| CSS `styles.css` | `css` | `css` | `file-type-css` | `css` |
| Sass `styles.scss` | `sass` | `sass` | `file-type-scss` | `sass` |
| JSON `data.json` | `json` | `json` | `file-type-json` | `json` |
| YAML `config.yaml` | `yml` | `yaml` | `file-type-yaml` | `yaml` |
| TOML `config.toml` | `config` | `toml` | `file-type-toml` | `toml` |
| Markdown `notes.md` | `markdown` | `markdown` | `file-type-markdown` | `markdown` |
| MDX `page.mdx` | `mdx` | `mdx` | `file-type-mdx` | `markdown-mdx` |
| Astro `Page.astro` | `astro` | `astro` | `file-type-astro` | `astro` |
| Vue `App.vue` | `vue` | `vue` | `file-type-vue` | `vue` |
| Svelte `App.svelte` | `svelte` | `svelte` | `file-type-svelte` | `svelte` |
| SQL `schema.sql` | `db` | `database` | `file-type-sql` | `database` |
| GraphQL `schema.graphql` | `graphql` | `graphql` | `file-type-graphql` | `graphql` |
| Lua `init.lua` | `lua` | `lua` | `file-type-lua` | `lua` |
| package.json | `json` | `nodejs` | `file-type-npm` | `package-json` |
| tsconfig.json | `tsconfig` | `tsconfig` | `file-type-tsconfig` | `typescript-config` |
| Dockerfile | `docker` | `docker` | `file-type-docker` | `docker` |
| README.md | `info` | `readme` | `file-type-markdown` | `readme` |
| .gitignore | `git` | `git` | `file-type-git` | `git` |
| GitHub workflow `.github/workflows/ci.yml` | `github` | `github` | `github` | `github` |

- [All file icons](https://ewels.github.io/starlight-codeblocks/features/file-icons/all/): See the icon of every language and file name in each set.

## Options

### `fileIcons`

Shows the icon of the file type before the title of a code block. Set it to `false` to turn the feature off. `icon` attributes then have no effect.

- Type: `false | object`
- Default: On

### `fileIcons.set`

The icons: the coloured icons of vscode-icons, Material Icon Theme or Catppuccin, or the one-colour Seti icons of the Starlight file tree. Material and Catppuccin need their `@iconify-json` package, such as `@iconify-json/catppuccin`.

- Type: `'seti' | 'material' | 'vscode-icons' | 'catppuccin'`
- Default: `'vscode-icons'`

### `fileIcons.style`

The icon alone, or the icon on a square with rounded corners. A language or a code block can set its own.

- Type: `'plain' | 'tile'`
- Default: `'plain'`

### `fileIcons.languages`

Settings for the blocks of each language: the icon when the title gives none, as an icon name or SVG markup, or `false` for none, a CSS colour for the icon or the tile, and the style.

- Type: `Record<string, { icon?: string | false; colour?: string; style?: 'plain' | 'tile' }>`
- Default: `{}`

### `fileIcons.files`

Icon names, or `false` for no icon, by file name, such as `nextflow.config`, by extension, such as `.nf`, or by path pattern, such as `.github/**`. A `*` matches within one folder, and `**` across folders. They come before the built-in rules.

- Type: `Record<string, string | false>`
- Default: `{}`

### `fileIcons.icons`

Custom icons by name: SVG markup, or the path data of a 24 by 24 icon. A custom name replaces a built-in icon of the same name.

- Type: `Record<string, string>`
- Default: `{}`

To use tiles on the whole site, with the brand colour of Python and an icon for a custom language:

```js title="astro.config.mjs"
import { siNextflow } from 'simple-icons';

codeblocks({
  fileIcons: {
    style: 'tile',
    icons: { nextflow: siNextflow.svg },
    files: { '.nf': 'nextflow', 'nextflow.config': 'nextflow', 'docs/**/*.md': 'info' },
    languages: {
      python: { colour: '#3776ab' },
      nextflow: { icon: 'nextflow', colour: '#31C9AC' },
    },
  },
});
```

A key in `fileIcons.files` with a `/` or a `*` is a path pattern. `*` matches inside one folder, and `**` matches across folders.

For one language, the icon in `fileIcons.languages` can be SVG markup, with no name in `fileIcons.icons`:

```js title="astro.config.mjs"
codeblocks({
  fileIcons: { languages: { nextflow: { icon: siNextflow.svg } } },
});
```

To show no icon for a file type or a language, use `false`. Here, `.mmd` files and `metro` blocks get no icon, but `overview.mmd` gets the Markdown icon. It comes after `.mmd`, so it wins:

```js title="astro.config.mjs"
codeblocks({
  fileIcons: {
    files: { '.mmd': false, 'overview.mmd': 'markdown' },
    languages: { metro: { icon: false } },
  },
});
```

An icon in `fileIcons.icons` is SVG markup, or the path data of a 24 by 24 icon. An icon with no `fill` takes the colour of the icon. An icon with its own colours keeps them.

The size and the default colours are style settings in the `codeblocksFileIcons` group.

- [Style settings](https://ewels.github.io/starlight-codeblocks/reference/style-settings/): See the size and colour settings of file icons.

## Limitations

- Each set has icons only for the file types that it knows. Other files get the default file icon of the set. Add an icon with `fileIcons.icons`.
- A custom icon with its own colours keeps them in the `tile` style.
- `<FileTree>` sees only the file name, so it shows the YAML icon for a file in `.github/workflows`, where a code block shows the GitHub icon.
- The coloured sets have no GitHub icon, so GitHub files get the Seti icon in every set.
- The plugin carries the rules of each coloured set at one version. An icon that a newer version adds has no rule until the plugin updates its rules.

## Related

- [Code tabs](https://ewels.github.io/starlight-codeblocks/features/code-tabs/): show several files as one block, with the icon of each file on its tab.

---

<!-- https://ewels.github.io/starlight-codeblocks/features/inline-code-highlighting/ -->

# Inline code highlighting

> Give inline code in the prose the syntax colours of the code blocks, from a language suffix or a default language for the site.

Starlight shows inline code in the prose in one colour, with no syntax highlighting. A short expression such as a function call is then harder to read than the same code in a block. A `{:lang}` suffix at the end of the inline code gives it the syntax colours of that language. A site can also set a [default language](#a-default-language) for all inline code.

**Tip:**
If most of the code on your site is in one language, [set it as the default](#a-default-language) in `astro.config.mjs`.
All inline code then gets syntax highlighting, with no extra Markdown syntax.

```md
> - In JavaScript, `[] + {}{:js}` is `"[object Object]"{:js}`.
> - In Python, `from __future__ import braces{:py}` raises `SyntaxError: not a chance{:py}`.
> - In CSS, `.modal { z-index: 99999 !important }{:css}` is a cry for help.
> - In a shell, `rm -rf node_modules{:sh}` fixes most things.
```

Each piece of inline code with a suffix gets the colours and the background of the site's code blocks. The plugin removes the suffix, so readers see only the code. Inline code without a suffix, such as `astro.config.mjs`, keeps the plain style of Starlight.

## Syntax

| Syntax | Where |
|---|---|
| `` `<code>{:<lang>}` `` | Inside the backticks, at the end of the code |
| `` `<code>`{:<lang>} `` | Directly after the closing backtick |

`<lang>` is a language name or alias that Expressive Code knows, as in a code block: `js`, `py`, `sh`, `css` and others. Languages that the site adds in the `shiki.langs` option of Expressive Code work too. The suffix must follow the code or the backtick with no space between them.

**Tip:**
If possible, use the first syntax, with the suffix inside the backticks. It is the same syntax as `rehype-pretty-code`, and it is valid in `.md` and `.mdx` files with no change.

**Caution:**
MDX reads a `{:js}` after the closing backtick as a JavaScript expression, and the build fails.
If you need to use this syntax with MDX, write a backslash before it: `` `res.ok`\{:js} ``. Some plugins read `.md` files as MDX too, such as `starlight-versions` and `starlight-md-txt`, so the backslash is needed in `.md` files on those sites. The backslash works in `.md` files on every site.

## Behaviour

- Colours:
  - The inline code uses the site's Expressive Code themes: the background and the token colours of the dark theme and the light theme.
  - The colours change with Starlight's theme menu, the same as the code blocks.
  - The colours have the same contrast correction as the code blocks.
- The suffix:
  - The plugin removes the suffix from the page, in both forms.
  - Inline code without a suffix does not change, unless the site sets a [default language](#a-default-language).
- Warnings:
  - If Expressive Code does not know the language, the code shows as normal inline code and the build logs a warning with the file name. The plugin removes the suffix.
- Screen readers and copy:
  - The highlighted code is a normal `code` element. Screen readers and the copied text get the same characters as before.
- Without JavaScript:
  - The highlighting happens at build time, so it works without JavaScript. Pages with no code blocks get the colours too.

## Options

### `inlineHighlighting`

Adds syntax colours to inline code with a `{:lang}` suffix. Set it to `false` to turn the feature off.

- Type: `false | object`
- Default: On

### `inlineHighlighting.defaultLanguage`

The language of inline code with no suffix. `{:txt}` keeps one piece of inline code plain.

- Type: `string | false`
- Default: `false`

### A default language

Some sites have one main language, such as the API docs of a Python package. The `defaultLanguage` option highlights inline code with no suffix in that language:

```js title="astro.config.mjs"
codeblocks({
  inlineHighlighting: { defaultLanguage: 'py' },
});
```

With this configuration, `` `len(items)` `` gets the Python colours. A suffix wins over the default, so `` `fetch(url){:js}` `` is still JavaScript. To keep one piece of inline code plain, such as a file name, add `{:txt}`: `` `pyproject.toml{:txt}` ``. The suffixes `{:text}`, `{:plain}` and `{:plaintext}` do the same.

If Expressive Code does not know the default language, inline code without a suffix stays plain, and the build logs one warning. On this site, the option adds about 900 highlighted pieces of inline code and no measurable build time.

### Turn the feature off

Turn the feature off for the whole site with `inlineHighlighting: false`:

```js title="astro.config.mjs"
codeblocks({
  inlineHighlighting: false,
});
```

With `inlineHighlighting: false`, the suffix stays in the prose as text.

- [Configuration](https://ewels.github.io/starlight-codeblocks/configuration/): Learn how to set options for the whole site, or for a single code block.

## Limitations

- Inline code cannot use the attributes or directives of code blocks, such as focus or line states.
- The plugin does not support the token form of rehype-pretty-code, such as `{:.entity.name.function}`.
- The code must be on one line. Expressive Code highlights it as a code block of one line. An unclosed string colours the rest of the code as a string.

## Related

- [Code links](https://ewels.github.io/starlight-codeblocks/features/code-links/): make text inside a code block a link.
- [Code mentions](https://ewels.github.io/starlight-codeblocks/features/code-mentions/): link a phrase in the prose to lines of a code block.

---

<!-- https://ewels.github.io/starlight-codeblocks/features/word-level-diff/ -->

# Word-level diff

> Highlight the words that changed inside each line of a diff, so readers find a small edit in a long line.

Expressive Code tints the added and removed lines of a `diff` block. Word-level diff also highlights the words that changed inside each pair of lines, so readers can find a one-word edit in a long line.

````md
```diff lang="js"
-const timeout = 5000;
+const timeout = options.timeout ?? 5000;
const client = createClient({
-  retries: 3,
+  retries: options.retries,
});
```
````

The new `timeout` line adds `options.timeout ??`, and `3` becomes `options.retries`. The plugin pairs each removed line with the added line below it, and compares them word by word. The changed words get a stronger tint and a bar under them. The rest of the line keeps the plain diff tint.

## Syntax

| Syntax | Where |
|---|---|
| A `diff` block | Code block fence line |
| `ins={range}`, `del={range}` | Code block fence line |
| `[!code ++]`, `[!code --]` | Comment |
| `wordDiff=false` | Code block fence line |
| `wordDiff.minSimilarity=<0-1>` | Code block fence line |

Word-level diff applies to every removed line that has an added line below it, from any of these sources. You do not turn it on. `wordDiff=false` turns it off for one block.

## Examples

### With `ins` and `del`

The `ins` and `del` attributes give the same result as a `diff` block, without changing the language of the block:

````md
```js title="server.js" ins={2} del={1}
const port = 3000;
const port = Number(process.env.PORT ?? 3000);
```
````

### With directives

`[!code --]` and `[!code ++]` move with their line when you edit the code:

````md
```py title="config.py"
TIMEOUT = 30  # [!code --]
TIMEOUT = 60  # [!code ++]
```
````

### Lines too different to compare

A rewritten line is too different to compare, so it keeps a plain diff tint:

````md
```diff lang="js"
-const total = a + b;
+export function computeGrandTotal(items) {
+  return items.reduce((sum, item) => sum + item.price, 0);
+}
```
````

## Behaviour

- Pairing lines:
  - The plugin pairs a run of removed lines with the run of added lines below it, one by one.
  - Each pair is compared token by token: words, runs of whitespace and single punctuation characters.
  - If a pair is less than 40% similar, it is too different to compare. The plugin leaves the whole-line tints in place and adds no word highlight.
- Highlights:
  - The changed tokens get a stronger tint and a bar in the diff colour. Whitespace between two changed tokens is part of the highlight, so a run of changed words tints as one block.
  - Changed words have a bar under them, and removed words also have a line through them, so the change does not rely on colour.
  - The plugin corrects the colour of each changed word to 4.5:1 contrast on the tint. In dark themes, this can turn the syntax colours of the words close to plain text.
- Without JavaScript:
  - Word-level diff needs no JavaScript in the browser.

## Options

### `wordDiff`

Highlights the words that changed between a removed line and an added line. Set it to `false` to turn the feature off.

- Type: `false | object`
- Default: On

### `wordDiff.minSimilarity`

Pairs of lines less similar than this keep whole-line tints only. From 0 to 1. A code block can set its own on its fence line.

- Type: `number`
- Default: `0.4`

Some codebases rewrite lines often enough that the word-level highlight adds noise more often than it helps. Raise the threshold to show it only for close edits:

```js title="astro.config.mjs"
codeblocks({
  wordDiff: { minSimilarity: 0.7 },
});
```

- [Configuration](https://ewels.github.io/starlight-codeblocks/configuration/): Learn how to set options for the whole site, or for a single code block.

## Limitations

- Pairing is by position. The first removed line pairs with the first added line, the second with the second, and each later pair the same way. A block that adds or removes a different number of lines can pair the wrong lines.
- The comparison works on the visible text of the line. It does not parse the language, so it cannot tell that `total` and `sum` are the same value with a new name.
- The plugin does not compare a long pair of lines, such as two lines of minified code. If the number of tokens in the removed line multiplied by the number in the added line is more than 1,000,000, the whole-line tints stay.

## Related

- [Line states](https://ewels.github.io/starlight-codeblocks/features/line-states/): tint a line as an error, a warning or a note, instead of a change.
- [Comment notation](https://ewels.github.io/starlight-codeblocks/comment-notation/): the `[!code ++]` and `[!code --]` directives that word-level diff reads.

---

<!-- https://ewels.github.io/starlight-codeblocks/features/code-links/ -->

# Code links

> Turn text in code into a link with a card that describes it, from a directive in the comment above.

Readers who meet an unfamiliar function in an example often want to know what it does, and where its reference page is. A code block in Starlight has no links, so the reader must search for it. The `[!link]` directive turns text on a line into a link to the page you choose, with a short description in a card.

````md
```py
import numpy as np

# [!link /linspace/ https://numpy.org/doc/stable/reference/generated/numpy.linspace.html] Returns evenly spaced numbers over an interval.
x = np.linspace(0, 1, 50)
y = np.sin(2 * np.pi * x)
```
````

The directive is on its own line, above the line it applies to. It can also go at the end of that line. The plugin removes the directive, and `linspace` becomes a link with an underline in the accent colour. Hover over the link, or press Tab to focus it, to see the description in a card. The rest of the line keeps its syntax colours.

## Syntax

| Syntax | Where |
|---|---|
| `[!link /<text>/ <url>] <description>` | Comment on or above the line |
| `[!link /<text>/ <url>]` | Comment on or above the line |

`<text>` is literal text, not a regular expression. The plugin links its first match on the line it applies to. `<url>` is a relative, `http` or `https` URL without spaces. A URL that starts with `/` is a link inside the site.

`<description>` is optional. It shows in a card, as for [API auto-linking](https://ewels.github.io/starlight-codeblocks/features/api-auto-linking/). The text runs to the next directive or to the end of the comment. Without a description, the link has no card.

Several `[!link]` lines can stack above one line of code, one for each text to link.

## Examples

### Two links on one line

Two `[!link]` lines above one line link two names on it, each with its own card:

````md
```py title="notes.py"
from pathlib import Path

# [!link /Path/ https://docs.python.org/3/library/pathlib.html#pathlib.Path] A path on the file system.
# [!link /read_text/ https://docs.python.org/3/library/pathlib.html#pathlib.Path.read_text] Returns the text of the file.
notes = Path("notes.txt").read_text()
```
````

### A link inside the site

A link inside the site starts with `/`. The plugin adds the site's base:

````md
```js title="astro.config.mjs"
export default defineConfig({
  // [!link /codeblocks/ /reference/options/] Every option of the plugin.
  integrations: [starlight({ plugins: [codeblocks()] })],
});
```
````

### Links without a description

Leave out the description for a plain link with no card. It needs no JavaScript:

````md
```py
import numpy as np

# [!link /linspace/ https://numpy.org/doc/stable/reference/generated/numpy.linspace.html]
x = np.linspace(0, 1, 50)
```
````

## Behaviour

- The link:
  - The linked text keeps its syntax colours, with an underline in the accent colour. Hover over the link to see a faint background.
  - The link is a normal link. Readers can focus it with the keyboard, and it opens in the same tab.
  - A URL that starts with `/` gets Astro's `base` in front of it, unless it already starts with the base. On this site, `/reference/directives/` becomes `/starlight-codeblocks/reference/directives/`. A site without `codeblocks()` gives the base to `pluginCodeblocks()`, as the [Expressive Code plugins page](https://ewels.github.io/starlight-codeblocks/reference/expressive-code-plugins/#the-preset) shows.
- The card:
  - The card shows on hover and on focus. It shows the linked text, the description and the domain of the URL. A link inside the site shows no domain. Press Escape to close the card.
  - The card shows plain text. Inline code, bold and links in the description become plain text.
- Screen readers:
  - Screen readers read the description and the domain as the link's description.
- Copy:
  - The copied text leaves out the directive line.
- Warnings:
  - If the text has no match on the line it applies to, the build logs a warning and the line renders without the link. A directive without a URL, or with another scheme such as `mailto:`, gets a warning too.
- Without JavaScript:
  - The card needs JavaScript, and the page loads it only for a block with a description. Without JavaScript, the link still works.

## Options

Code links have no options. Turn the feature off for the whole site with `codeLinks: false`:

```js title="astro.config.mjs"
codeblocks({
  codeLinks: false,
});
```

With `codeLinks: false`, a `[!link]` directive is an unknown directive. The build logs a warning and leaves the comment in the code.

- [Configuration](https://ewels.github.io/starlight-codeblocks/configuration/): Learn how to set options for the whole site, or for a single code block.

## Limitations

- A directive links the first match only. To link a later match, make the text longer, so that it matches only there.
- Languages with no comment syntax, such as JSON, cannot use `[!link]`. Use `jsonc` instead.
- A link cannot span two lines.

## Related

- [API auto-linking](https://ewels.github.io/starlight-codeblocks/features/api-auto-linking/): link every name that an adapter knows, with no directive in the code. Code links are for one-off links.
- [Comment notation](https://ewels.github.io/starlight-codeblocks/comment-notation/): the directive syntax that `[!link]` uses.

---

<!-- https://ewels.github.io/starlight-codeblocks/features/api-auto-linking/ -->

# API auto-linking

> Link the names in code examples to their reference pages, with a card that shows the signature and a summary.

A code example uses names from libraries: modules, functions, classes and their methods. In a normal code block, a reader who wants the reference page of a name must search for it. API auto-linking finds these names and links them to their reference pages. You write nothing in the code block.

````md
```py title="report.py"
import json
from pathlib import Path

run = json.loads(Path("run.json").read_text())
print(run["status"])
```
````

The Python adapter reads the two imports. It links `json`, `pathlib`, `json.loads`, `Path` and `read_text` to the Python documentation. It knows that `read_text` belongs to `Path`, because the code calls `Path` first. Hover over a link, or move keyboard focus to it, to see a card with the kind, the name, a short summary and the source.

## Syntax

API auto-linking has no syntax. It runs on every code block in a language that has an adapter.

| Syntax | Where | Effect |
|---|---|---|
| `apiLinks=false` | Code block fence line | Turns the feature off for one code block |

## Examples

### Nextflow

A Nextflow workflow gets links for the channel factory and for the process from nf-core:

````md
```nextflow title="main.nf"
include { FASTQC } from './modules/nf-core/fastqc/main'

workflow {
    reads = channel.fromFilePairs(params.reads)
    FASTQC(reads)
}
```
````

### An adapter for your own names

A site can link its own names with an adapter of its own. This site links the names that a block imports from starlight-codeblocks:

````md
```js title="adapters.mjs"
import { nextflow } from 'starlight-codeblocks/adapters/nextflow';
import { python } from 'starlight-codeblocks/adapters/python';

export const adapters = [python(), nextflow()];
```
````

### Turn links off for one block

With `apiLinks=false`, the same Python block has no links:

````md
```py title="report.py" apiLinks=false
import json

run = json.loads(text)
```
````

## Behaviour

An adapter finds the names in a code block and resolves each one against its indexes. It links a name only when it is certain about the name. All other names stay plain text.

- Links:
  - A link has a dotted underline. On hover and on focus, the underline is solid and the link gets a faint background.
  - Names inside strings and comments never link.
- The card:
  - After 150 ms of hover, or at once on keyboard focus, a card opens under the link. It shows the signature, or the kind and the qualified name. Under that, it shows a summary, if the index has one, and the source of the link.
  - The source has the icon of its project, if [Simple Icons](https://simpleicons.org/) has one, such as Python, NumPy or Flask.
  - The card stays open while the mouse cursor is on the link or on the card. Press <kbd>Escape</kbd> to close it. The card closes when the link loses focus.
- Screen readers:
  - Screen readers get the text of the card as the description of the link.
- Copy:
  - The copied text is the same as the code. Links and cards are not part of it.
- Without JavaScript:
  - The links work, but there is no card.

Adapters load their indexes once for each build. An index that the build fetches from another site stays on disk in `node_modules/.cache/starlight-codeblocks/`, so later builds do not fetch it again. If a fetch fails and there is no copy on disk, the build logs a warning, and the names from that index stay plain text. The build does not fail.

## Options

### `apiLinks`

Links names in code to their reference pages. Set it to `false` to turn the feature off.

- Type: `false | object`
- Default: On

### `apiLinks.adapters`

Adapters that find and resolve names.

- Type: `ApiLinkAdapter[]`
- Default: `[python(), nextflow()]`

A list in `adapters` replaces the default list. To change one adapter, put all the adapters that you want in the list:

```js title="astro.config.mjs"
import codeblocks from 'starlight-codeblocks';
import { nextflow } from 'starlight-codeblocks/adapters/nextflow';
import { python } from 'starlight-codeblocks/adapters/python';

codeblocks({
  apiLinks: {
    adapters: [python({ inventories: ['https://numpy.org/doc/stable/objects.inv'] }), nextflow()],
  },
});
```

To add an adapter for another language or library, see [Write an API link adapter](https://ewels.github.io/starlight-codeblocks/extend/write-an-api-link-adapter/).

- [Configuration](https://ewels.github.io/starlight-codeblocks/configuration/): Learn how to set options for the whole site, or for a single code block.

## Python adapter

The Python adapter runs on `py`, `python` and `pycon` code blocks. It reads `import x`, `import x as y` and `from a import b as c` in the block. Then it links the names that those imports bind, and chains of attributes on them, such as `os.path.join`.

### `stdlib`

Link names from the Python standard library, through `https://docs.python.org/3/objects.inv`.

- Type: `boolean`
- Default: `true`

### `inventories`

More Sphinx `objects.inv` files. `base` is the URL that relative links start from, if it is not the folder of `url`.

- Type: `(string | { url: string; base?: string })[]`
- Default: `[]`

### `summaries`

Fetch the documentation page of each name from an inventory, and show the first sentence of its description on the card.

- Type: `boolean`
- Default: `true`

An `objects.inv` file has no signatures and no summaries. For its names, the card shows the kind, the qualified name and the documentation that it comes from. The adapter also fetches the documentation page of each name when the site builds. It shows the first sentence of the description on the card, cut to 16 words. The page stays on disk with the inventories. If the page does not load, the card has no summary, and the build shows no warning.

If the site also uses starlight-pydocs, install both plugins. The Python adapter then links the names of every package that starlight-pydocs documents, with no configuration:

```js title="astro.config.mjs"
starlight({
  plugins: [starlightPydocs({ packages: [{ name: 'myproject' }] }), codeblocks()],
});
```

For these names, the card has the signature and the first sentence of the docstring, as starlight-pydocs shows them. A name links to the site's own page, also if an inventory has the same name. Names that a package re-exports, such as `myproject.Report` from a private `myproject._report` module, link to the object's page. If starlight-pydocs documents one package at two bases, such as the current version and an older one, the first entry in its `packages` list wins.

To link a block to another version, set `pydocsBase` to the `base` of that package. starlight-pydocs sets it on the examples in its docstrings, so that each version links to its own pages. You can also set it on a block that you write:

````md
```py pydocsBase="1x/api/myproject"
from myproject import Report
```
````

A name that the package at `pydocsBase` does not have links to the first package that has it, or to an inventory. If no package has the base, the build shows a warning, and the block links as it does without the attribute.

## Nextflow adapter

The Nextflow adapter runs on `nextflow` and `nf` code blocks. It has the channel factories and operators of the Nextflow reference, so it needs no network. It links:

- Channel factories, such as `channel.of` and `channel.fromPath`.
- Operators in a chain after a channel factory, such as `.map` and `.view`.
- Operators on a variable that holds a channel in every assignment in the block.
- Processes and workflows from `include` statements, if you give the `modules` option.

### `modules`

The reference page of an included process or workflow.

- Type: `({ name, path }) => string | object | undefined`
- Default: None

`modules` gets the name in the module and the path after `from`. It returns the URL of the page, or an object with `href` and, if you want them, `kind`, `signature`, `summary` and `source`. It returns `undefined` for a name that must stay plain text. This site links nf-core modules to their pages on the nf-core site:

```js title="astro.config.mjs"
nextflow({
  modules: ({ name }) => ({
    href: `https://nf-co.re/modules/${name.toLowerCase()}`,
    kind: 'process',
    source: 'nf-core modules',
  }),
});
```

## Limitations

- The Python adapter does not follow assignments. After `p = Path("run.json")`, the name `p.read_text` stays plain text.
- The Python adapter does not link built-in names, such as `print` and `len`.
- A name that the block binds again, for example with `json = {}` or as a function parameter, does not link anywhere in the block.
- The Nextflow adapter does not link operators after a process output, such as `FASTQC.out.html.map`, or after the `|` operator.
- The files in `node_modules/.cache/starlight-codeblocks/` do not expire. Delete the folder to fetch the indexes again.
- A link cannot span two lines.
- Names on the line that a `[!link]` directive targets do not link, so that a link is never inside another link.

## Related

- [Code links](https://ewels.github.io/starlight-codeblocks/features/code-links/): link one piece of text to a URL that you choose. Use them for names that no adapter knows.
- [Write an API link adapter](https://ewels.github.io/starlight-codeblocks/extend/write-an-api-link-adapter/): add links for another language or library.

---

<!-- https://ewels.github.io/starlight-codeblocks/features/line-permalinks/ -->

# Line permalinks

> Give a code block line numbers that link to each line, so readers can share a link to the exact lines they mean. Shift-click to select multiple lines.

A normal code block has no address for its lines. A reader who asks a question about one setting can only link to the page, or to the heading above the block. Line permalinks give a block line numbers, and each number is a link to its line.

````md
```yaml title="config.yml" id="cfg"
server:
  host: 0.0.0.0
  port: 8080
cache:
  dir: .cache
  max_age: 3600
logging:
  level: info
```
````

Click a line number to highlight that line. The address of the page changes to `#cfg-L2`, and the page does not move. Hold Shift and click a second number to highlight every line between the two, as `#cfg-L2-L4`. Open that address in a new tab, and the page scrolls to the lines and highlights them.

## Syntax

| Syntax | Where |
|---|---|
| `id="<id>"` | Code block fence line |

The `id` turns on line numbers for that block. It is also the `id` of the block in the page, so `#cfg` links to the whole block. Each block on a page needs its own `id`.

Pick an `id` from what the block contains, such as its file name. The `id` keeps links to the block working when you add other blocks to the page.

## Examples

### Numbers that match the file

A block that shows part of a file can start at the line number of that part, so the numbers match the file:

````md
```py title="app.py" id="app" startLineNumber=41
@app.get("/health")
def health():
    return {"status": "ok"}
```
````

### With hidden lines and a callout

This example combines line permalinks with hidden lines and an inline callout on purpose. The hidden-lines marker and the callout arrow line up with the code after the line numbers:

````md
```ts title="server.ts" id="server" hidden={1-2}
import { createServer } from 'node:http';
import { handler } from './handler.ts';

const port = Number(process.env.PORT ?? 3000);
// [!callout /listen/] Starts the server on the port.
createServer(handler).listen(port);
```
````

## Behaviour

- The links:
  - Each line number links to `#<id>-L<n>`, where `<n>` is the number that the reader sees. If the fence line (the first line of the code block, with the language) has `startLineNumber`, the numbers start there.
  - Clicking a number highlights that line and changes the address with `history.replaceState`. The page does not scroll, and the browser history gets no new entry.
  - Clicking a number with Shift held highlights the range from the last number you clicked, as `#<id>-L<a>-L<b>`.
- Opening a link:
  - When the page loads, or the address changes, the plugin highlights the lines in the address and scrolls them into view. If a line is a [hidden line](https://ewels.github.io/starlight-codeblocks/features/hidden-lines/), its marker opens. If a line is in a `<Tabs>` panel that is not selected, its tab opens.
- Keyboard and screen readers:
  - The line numbers are links, so you can reach them with the Tab key and press Enter to highlight a line. Shift and Enter together highlights a range. Screen readers announce each one as "Link to line N", and the highlighted numbers have `aria-current`.
- Copy:
  - Line numbers are not part of the copied text, and a manual selection of the code leaves them out.
- Warnings:
  - Two blocks with the same `id` on one page cause a build warning.
- Without JavaScript:
  - The links go to their line, without the highlight.

## Options

Line permalinks have no options. Turn the feature off for the whole site with `permalinks: false`:

```js title="astro.config.mjs"
codeblocks({
  permalinks: false,
});
```

With `permalinks: false`, the plugin ignores `id` on the fence line.

- [Configuration](https://ewels.github.io/starlight-codeblocks/configuration/): Learn how to set options for the whole site, or for a single code block.

## Limitations

- Line numbers take space on the left of every line. On a phone, a block with long lines scrolls sooner.
- The plugin highlights one range at a time on a page. A new highlight in any block removes the old highlight.
- An `id` must not match the `id` of a heading on the page. Heading ids come from the heading text, such as `#options`.
- The `starlight-links-validator` plugin reports links to a block or a line, such as `#cfg-L2`, as broken. Give it `exclude: linksValidatorExclude`, imported from `starlight-codeblocks`.

## Related

- [Line states](https://ewels.github.io/starlight-codeblocks/features/line-states/): mark a line as an error, a warning or a note in the source, for every reader.
- [Code mentions](https://ewels.github.io/starlight-codeblocks/features/code-mentions/): highlight lines from a phrase in the prose, without a line number.
- [Hidden lines](https://ewels.github.io/starlight-codeblocks/features/hidden-lines/): keep set-up lines out of view. Their line numbers still count.

---

<!-- https://ewels.github.io/starlight-codeblocks/features/code-tabs/ -->

# Code tabs

> Show several code blocks as one, with editor tabs in the title bar, such as the files of a project or the commands for each package manager.

Examples often come in several files, or in versions for each package manager or language. Stacked one after the other, they fill the page with code that most readers skip. Code tabs show them as one block, with a tab for each block in the title bar, as in a code editor.

````md
:::code-tabs
```yaml title=".github/workflows/ci.yml"
name: CI
on: push
jobs:
  greet:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - run: python greet.py
      - run: node greet.js
```
```py title="greet.py"
import sys

name = sys.argv[1] if len(sys.argv) > 1 else "world"
print(f"Hello, {name}!")
```
```js title="greet.js"
const name = process.argv[2] ?? 'world';
console.log(`Hello, ${name}!`);
```
:::
````

Select **greet.py**, and the block shows the Python file. Each tab shows the `title` of its block, with its file icon.

## Syntax

| Syntax | Where |
|---|---|
| `:::code-tabs` ... `:::` | Around the code blocks |
| `sync="<key>"` | After `:::code-tabs`, in braces |
| `control="tabs"` or `control="menu"` | After `:::code-tabs`, in braces |
| `label="<text>"` | Code block fence line of each variant |

Put one or more fenced code blocks between the `:::code-tabs` line and the `:::` line. The directive can contain only code blocks. Anything else, such as a paragraph, fails the build with a message that names the file.

Each code block is a variant. A tab shows the `title` of its variant. A variant with no `title` shows its `label`, and a variant with no `label` shows the name of its language, such as "Python" for `py`. The label also matches variants across blocks with the same `sync` key. Two variants with the same label fail the build. For example, `sh` and `bash` both show "Shell", so give each one a `label`.

## Examples

### Package managers

A tab with no `title` shows the `label`, with no file icon. Blocks with the same `sync` key switch together, on this page and on the other pages of the site. Select **pnpm**, and the install command on the [home page](https://ewels.github.io/starlight-codeblocks/) changes too:

````md
:::code-tabs{sync="pm"}
```sh label="npm"
npm install starlight-codeblocks
```
```sh label="pnpm"
pnpm add starlight-codeblocks
```
```sh label="Yarn"
yarn add starlight-codeblocks
```
:::
````

To show an icon on a tab with no `title`, give the block an [`icon`](https://ewels.github.io/starlight-codeblocks/features/file-icons/), such as `icon="pnpm"`.

### Switch by language

Two blocks with the same `sync` key and no labels or titles switch together by language. Select **JavaScript** in one block, and the other block changes too:

````md
:::code-tabs{sync="lang"}
```py
import json

with open("config.json") as fh:
    config = json.load(fh)
```
```js
import { readFile } from 'node:fs/promises';

const config = JSON.parse(await readFile('config.json', 'utf8'));
```
```rust
let text = std::fs::read_to_string("config.json")?;
let config: serde_json::Value = serde_json::from_str(&text)?;
```
:::

:::code-tabs{sync="lang"}
```py
with open("config.json", "w") as fh:
    json.dump(config, fh, indent=2)
```
```js
await writeFile('config.json', JSON.stringify(config, null, 2));
```
```rust
std::fs::write("config.json", serde_json::to_string_pretty(&config)?)?;
```
:::
````

### A menu in place of tabs

With `control="menu"`, the title bar shows the `title` of the variant that shows, and a menu on the right that picks the variant. The menu shows the icon of the language, and names each variant by its label. Here, a tool reads its settings from YAML or TOML:

````md
:::code-tabs{control="menu"}
```yaml title="config.yml"
server:
  port: 8080
```
```toml title="config.toml"
[server]
port = 8080
```
:::
````

## Behaviour

- The title bar:
  - Only one variant shows at a time.
  - Tabs: the title bar has a tab for each variant, in the order of the blocks. The tab of the variant that shows is the editor tab of Expressive Code. Each tab has the file icon of its `title`, or the icon that the block names with `icon`.
  - Tabs use the editor frame, also for shell commands, which otherwise get a terminal frame.
  - If the tabs do not fit, the row of tabs scrolls sideways.
  - Menu: the title bar shows the `title` of the variant, if it has one, and the menu on the right. The menu starts with the icon of the language of the variant, such as the Python logo for `py`. A language with no icon gets a generic code icon.
- Switching variants:
  - Selecting a tab, or an entry in the menu, shows that variant. Keyboard focus moves to the same tab or the menu in the new variant.
  - Blocks with the same `sync` key switch together, matched by label. The browser keeps the choice for each key in `localStorage`, so it applies across the site and on the next visit.
  - If a block does not have the saved label, it shows its first variant.
  - A block with no `sync` key switches on its own, and the browser does not keep the choice.
- Keyboard and screen readers:
  - The tabs are a tab list with the accessible name "Variant". <kbd>Tab</kbd> moves focus to the selected tab. <kbd>Left Arrow</kbd> and <kbd>Right Arrow</kbd> select the previous and next tab, and <kbd>Home</kbd> and <kbd>End</kbd> select the first and last tab.
  - The menu is a native `select` element with the accessible name "Variant".
- Copy and print:
  - The copy button copies the variant that shows.
  - The variant that shows prints, with its own tab. The other tabs and the menu do not print.
- Without JavaScript:
  - The first variant shows, with its own tab. The other tabs and the menu do not show.

## Options

### `codeTabs`

Combines several variants of a block, with tabs or a menu in the title bar. Set it to `false` to turn the feature off.

- Type: `false | object`
- Default: On

### `codeTabs.control`

Editor tabs in the title bar, or a menu on its right. A `:::code-tabs` directive can set its own with `control="…"`.

- Type: `'tabs' | 'menu'`
- Default: `'tabs'`

To use the menu on every block of the site, set `control` to `'menu'`. A directive with `control="tabs"` still shows tabs:

```js title="astro.config.mjs"
codeblocks({
  codeTabs: { control: 'menu' },
});
```

With `codeTabs: false`, each code block in the directive renders on its own, one after the other. The directive lines do not show.

- [Configuration](https://ewels.github.io/starlight-codeblocks/configuration/): Learn how to set options for the whole site, or for a single code block.

## Code tabs or Starlight tabs

Starlight has a `<Tabs>` component that also shows one version at a time and remembers the choice across pages. The two differ in what they can contain and in how they look.

| Property | Code tabs | `<Tabs>` |
|---|---|---|
| Contains | Code blocks only | Any content: prose, lists, code blocks, components |
| Control | Editor tabs or a menu in the title bar of the block | A row of tabs above the content |
| Works in | Markdown and MDX | MDX only |
| Keeps the choice | With `sync="<key>"` | With `syncKey="<key>"` |
| Space on the page | One code block | One code block, plus the row of tabs |

- If every version is one code block, use code tabs.
- If a version needs prose, a list or a second code block, use `<Tabs>`.
- If the page is a `.md` file, use code tabs, or change the file to `.mdx` for `<Tabs>`.

For example, the steps to install a tool can differ for each operating system, with a sentence of explanation before each command:

````md
<Tabs syncKey="os">
<TabItem label="macOS">

Install the tool with Homebrew:

```sh
brew install jq
```

</TabItem>
<TabItem label="Windows">

Install the tool with winget:

```sh
winget install jqlang.jq
```

</TabItem>
</Tabs>
````

The two keys are separate. Code tabs with `sync="pm"` and a `<Tabs>` group with `syncKey="pm"` do not switch together. Use one of the two for each kind of choice on a site.

## Limitations

- The directive works in Markdown and MDX files. It does not work around a `<Code>` component.
- Labels match by their exact text. "npm" and "NPM" are two different labels.
- A saved choice applies after the page loads, so a block can show its first variant for a moment.

## Related

- [Fill-in placeholders](https://ewels.github.io/starlight-codeblocks/features/fill-in-placeholders/): one block with fields for the values that differ, instead of one variant for each value.

---

<!-- https://ewels.github.io/starlight-codeblocks/features/fill-in-placeholders/ -->

# Fill-in placeholders

> Turn placeholders such as YOUR_TOKEN into fields, so readers type their own values into every block and the copied code.

Examples for an API often contain values that each reader has to change, such as `YOUR_TOKEN`. In a normal code block, readers copy the code and then edit it by hand. The `placeholder` attribute turns those values into fields. What a reader types fills every block on the site, and the copied code.

````md
```sh placeholder="YOUR_TOKEN,WORKSPACE_ID"
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://api.example.com/workspaces/WORKSPACE_ID/runs
```

```py placeholder="YOUR_TOKEN"
from example import Client

client = Client(token="YOUR_TOKEN")
```
````

Type a token into a `YOUR_TOKEN` field in one block, and the field in the other block shows it too. Each field is as wide as its text, and keeps the colour of the string it is in. The copy button copies the code with your values.

## Syntax

| Syntax | Where |
|---|---|
| `placeholder="<A>,<B>"` | Code block fence line |
| `placeholders.storage="local"`, `"session"` or `"none"` | Code block fence line |

The attribute lists the literal texts to turn into fields, separated by commas. Every match of each text in the block becomes a field. If one text contains another, the longer text wins where both match.

## Examples

### Values in a playground

This block combines fill-in placeholders with a playground button, to show that the playground gets the reader's value. Type a token, then click **Open in TS Playground**:

````md
```ts placeholder="YOUR_TOKEN" playground="typescript"
const response = await fetch('https://api.example.com/v1/runs', {
  headers: { Authorization: 'Bearer YOUR_TOKEN' },
});
console.log(await response.json());
```
````

## Behaviour

- Fields:
  - A field shows its placeholder text until the reader types. Its accessible name is the placeholder text.
  - A field is as wide as its placeholder text or its value, whichever is longer.
- Typing:
  - Typing in a field updates every field with the same text on the page. Pages that load later show the value too.
  - Escape in a field clears its value, in every field with the same text.
  - Values stay in the reader's browser. The plugin never sends them anywhere.
- Copy, playgrounds and print:
  - The copy button copies the code with the reader's values. An empty field copies its placeholder text. A manual copy of a selection in the block copies the same way.
  - A [playground](https://ewels.github.io/starlight-codeblocks/features/open-in-playground/) button opens the code with the reader's values.
  - A field prints as its text, without the border: the value if the reader typed one, or else the placeholder text.
- Warnings:
  - If a text in the attribute is not in the code, the build logs a warning.
- Without JavaScript:
  - Fields are plain inputs. They do not update each other, and the copy button copies the placeholder text.

**Danger:**
Tell readers where their values go. With the default `storage: 'local'`, the browser keeps the values after the reader closes the tab. On a shared computer, the next person can see them.

## Options

### `placeholders`

Turns placeholder text into input fields. Set it to `false` to turn the feature off.

- Type: `false | object`
- Default: On

### `placeholders.storage`

Where the browser keeps the values that readers type. A code block can set its own on its fence line.

- Type: `'local' | 'session' | 'none'`
- Default: `'local'`

`'local'` keeps values across visits. `'session'` keeps them until the reader closes the tab. `'none'` keeps them only while the page is open. For a site where readers type secrets, such as API tokens, use `'session'`:

```js title="astro.config.mjs"
codeblocks({
  placeholders: { storage: 'session' },
});
```

- [Configuration](https://ewels.github.io/starlight-codeblocks/configuration/): Learn how to set options for the whole site, or for a single code block.

## Limitations

- A field matches literal text only. A text that also appears in a place that is not a placeholder becomes a field there too. Choose texts such as `YOUR_TOKEN` that appear nowhere else.
- A custom `url` playground gets the reader's values only if it puts the code in the URL with `encodeURIComponent()`. A custom `post` playground must put the code in a field as it is.

## Related

- [Open in playground](https://ewels.github.io/starlight-codeblocks/features/open-in-playground/): open the code, with the reader's values, in an online playground.
- [Hidden lines](https://ewels.github.io/starlight-codeblocks/features/hidden-lines/): hide set-up lines, such as the line that reads a token from the environment.

---

<!-- https://ewels.github.io/starlight-codeblocks/features/smart-shell-copy/ -->

# Smart shell copy

> Add a Copy commands button to terminal blocks, which copies the commands without the prompts or the output.

A terminal block in Starlight often shows a session: commands after a prompt, and the output they print. Readers who copy that block get the prompts and the output too, and the paste fails in their shell. Smart shell copy reads the prompts, and adds a **Copy commands** button to the title bar. The button copies the commands only.

````md
```sh frame="terminal"
$ uv tool install ruff
Resolved 1 package in 180ms
Installed 1 executable: ruff
$ ruff check src/ \
    --fix
Found 3 errors (3 fixed, 0 remaining).
```
````

The two lines that start with `$ ` are commands, and `--fix` continues the command above it. The other lines are output, in a muted colour. **Copy commands** copies the two commands without the prompts, with the continuation line kept. The copy button copies the whole block, as it does in every other block.

## Syntax

Smart shell copy has no directive. It applies to every block with a terminal frame that has at least one prompt line.

| Block | Terminal frame |
|---|---|
| A shell language, such as `sh`, `bash`, `zsh` or `powershell` | Yes, from Expressive Code's automatic frame |
| Any language with `frame="terminal"` | Yes |
| A shell language with `frame="code"` or `frame="none"` | No |

A prompt is text at the start of a line. The default prompts are `$ ` and `> `, each with a space after it. To use other prompts in one block, add `shellCopy.prompts="<text>"` to the fence line, once for each prompt, such as `shellCopy.prompts="% "`. The fence line is the first line of the code block, with the language. These prompts replace the defaults for the block.

A `pycon` block with a line that starts with `>>> ` is a Python session. A `python` or `py` block is a session when its first line starts with `>>> `. It gets the same button, and keeps the editor frame. See [Python sessions](#python-sessions).

## Examples

### A custom prompt

A PowerShell session uses its own prompt. This site adds `PS> ` to `shellCopy.prompts`, so **Copy commands** in the block below copies two commands:

````md
```powershell
PS> Get-ChildItem -Name
report.csv
summary.txt
PS> Get-Content summary.txt
Rows: 1204
```
````

### A session in any language

A block in any language can show a session, if it has `frame="terminal"`:

````md
```txt frame="terminal" title="Install the package"
$ python -m pip install example-client
Collecting example-client
Successfully installed example-client-2.1.0
```
````

## Behaviour

- Commands and output:
  - A line that starts with a prompt is a command. The prompt has its own colour, and a manual selection leaves it out.
  - A command line that ends with `\` continues on the next line. That line is part of the command too.
  - Every other line is output. Output lines have no syntax colours and use a muted colour.
  - A terminal block with no prompt line renders and copies as Expressive Code shows it.
- Copying:
  - The **Copy commands** button in the title bar copies each command without its prompt, one command on each line. After a copy, its label is **Copied** for a short time, and screen readers announce "Copied".
  - The copy button works as in every other block. It copies the whole block: the prompts, the commands and the output.
  - Hidden lines that are commands are part of the text that **Copy commands** copies. Hidden output lines are not.
- Without JavaScript:
  - The two buttons need JavaScript, as in Expressive Code. Without JavaScript, the **Copy commands** button is hidden, and readers can select the code by hand. The selection leaves out the prompts.

## Python sessions

A Python session in a docstring or a tutorial shows commands after `>>> ` and the values that they print. Smart shell copy reads these blocks with no configuration and no `frame="terminal"`:

````md
```py
>>> from collections import Counter
>>> counts = Counter(["ok", "ok", "failed"])
>>> for status, n in counts.most_common():
...     print(f"{status:<8} {n}")
...
ok       2
failed   1
```
````

**Copy commands** copies the three commands without the prompts, and keeps the two continuation lines. The rules follow the Python REPL:

- A line that starts with `>>> ` is a command.
- A line that starts with `... `, or a bare `...`, continues the command while its statement is open. A compound statement stays open until a bare `...` line. It starts with a keyword such as `def`, `class`, `if`, `for` or `with`, or with a `@` decorator. Any other statement stays open while it has an open bracket, a trailing `\` or an open triple-quoted string.
- After a complete statement, a line that starts with `...` is output, for example the text that `print("...")` shows.
- Every other line is output.

[API auto-linking](https://ewels.github.io/starlight-codeblocks/features/api-auto-linking/) links names in the commands of a session, and not in its output.

## Options

### `shellCopy`

Adds a Copy commands button to terminal blocks with prompts, which copies the commands only. Set it to `false` to turn the feature off.

- Type: `false | object`
- Default: On

### `shellCopy.prompts`

Line starts that mark a command. A code block can set its own on its fence line.

- Type: `string[]`
- Default: `['$ ','> ']`

The default prompts do not include `#`, because `#` also starts a comment in shell code. If your examples use a root prompt, add it:

```js title="astro.config.mjs"
codeblocks({
  shellCopy: { prompts: ['$ ', '# '] },
});
```

With `shellCopy: false`, terminal blocks have no **Copy commands** button, and prompts show as part of the code.

- [Configuration](https://ewels.github.io/starlight-codeblocks/configuration/): Learn how to set options for the whole site, or for a single code block.

## Limitations

- A prompt must be the first text on the line. The plugin does not find a prompt after spaces.
- Output lines lose their syntax colours, so output that contains code shows in one colour.
- `#` is not a default prompt. A line such as `# apt install curl` is output, unless you add `# ` to the prompts.
- In a Python session, a line that starts with `>>> ` is always a command, also if it is output that a command printed.

## Related

- [Hidden lines](https://ewels.github.io/starlight-codeblocks/features/hidden-lines/): hide set-up commands that readers need to copy but not to read.
- [Fill-in placeholders](https://ewels.github.io/starlight-codeblocks/features/fill-in-placeholders/): let readers type their own values into a command before they copy it.

---

<!-- https://ewels.github.io/starlight-codeblocks/features/open-in-playground/ -->

# Open in playground

> Add a title bar button that opens the example in an online playground, with the code already filled in.

A code block in Starlight shows code that readers can copy, but not run. Many languages have an online playground that runs code in the browser. The `playground` attribute adds a button to the title bar that opens the example in one, with the code already filled in.

````md
```ts playground="typescript"
type Status = 'queued' | 'running' | 'done';

function label(s: Status): string {
  return s === 'done' ? 'Finished' : s;
}

console.log(label('done'));
```
````

The block has no title, so the plugin adds a title bar for the button. Click **Open in TS Playground** to open the TypeScript Playground in a new tab, with this code in the editor.

## Syntax

| Syntax | Where |
|---|---|
| `playground="<name>"` | Code block fence line |

The name is a built-in playground, or a playground that the site adds in its configuration.

| Name | Label | Code goes in |
|---|---|---|
| `typescript` | **Open in TS Playground** | The URL, compressed with lz-string |
| `rust` | **Open in Rust Playground** | The URL |

## Examples

### A custom playground

A Python example opens in Python Tutor, the custom playground that this site adds in its [options](#options):

````md
```py playground="pythontutor"
from statistics import median

print(median([3, 1, 4, 1, 5]))
```
````

### A playground that takes a form post

This site adds StackBlitz, which takes a project in a form post ([Add a playground](https://ewels.github.io/starlight-codeblocks/extend/add-a-playground/)). The button is then part of a form:

````md
```js title="index.js" playground="stackblitz"
const words = ['queued', 'running', 'done'];
document.body.textContent = words.join(' then ');
```
````

## Behaviour

- The button:
  - A playground that takes the code in its URL renders as a link with the look of a button. It opens in a new tab.
  - A playground that takes the code in a form post renders as a form with hidden fields. It opens in a new tab too.
- The code it sends:
  - The playground gets the copied text of the block. Directives are removed, hidden lines are kept, and a terminal session sends only its commands.
- Screen readers:
  - Screen readers announce "opens in a new tab" after the label.
- Warnings:
  - If a URL is longer than 8,000 characters, the build logs a warning, because some browsers cut long URLs.
  - If the name is not a known playground, the build logs a warning and the block has no button.
- Print:
  - The button does not print.
- Without JavaScript:
  - The button works without JavaScript. Only the values that readers type into [fill-in placeholders](https://ewels.github.io/starlight-codeblocks/features/fill-in-placeholders/) need JavaScript to reach the playground.

## Options

### `playgrounds`

Adds a button that opens the code in an online playground. Set it to `false` to turn the feature off. `playground` attributes then have no effect.

- Type: `false | object`
- Default: On

### `playgrounds.<name>`

Custom playgrounds by name, in addition to the built-in ones.

- Type: an object with a `label` and one of `url` or `post`
- Default: None

A custom playground has a label and one function. `url` returns the URL to open. `post` returns a form action and its fields. This site adds Python Tutor, which takes the code in its URL:

```js title="astro.config.mjs"
codeblocks({
  playgrounds: {
    pythontutor: {
      label: 'Open in Python Tutor',
      url: ({ code }) => `https://pythontutor.com/visualize.html#mode=edit&py=3&code=${encodeURIComponent(code)}`,
    },
  },
});
```

The guide to [adding a playground](https://ewels.github.io/starlight-codeblocks/extend/add-a-playground/) describes both functions and the form post.

- [Configuration](https://ewels.github.io/starlight-codeblocks/configuration/): Learn how to set options for the whole site, or for a single code block.

## Limitations

- The playground runs the copied text only. The code must be complete, or it fails in the playground. Put the imports and set-up in [hidden lines](https://ewels.github.io/starlight-codeblocks/features/hidden-lines/) if they distract from the example.
- A block can open one playground.
- The plugin cannot check that a custom playground accepts the code. Test each custom playground once in a browser.

## Related

- [Hidden lines](https://ewels.github.io/starlight-codeblocks/features/hidden-lines/): keep the code complete for the playground, while readers see only the part you explain.
- [Fill-in placeholders](https://ewels.github.io/starlight-codeblocks/features/fill-in-placeholders/): send the values that readers type to the playground.
- [Add a playground](https://ewels.github.io/starlight-codeblocks/extend/add-a-playground/): the interface for custom playgrounds.

---

<!-- https://ewels.github.io/starlight-codeblocks/features/run-code/ -->

# Run code

> Add a Run code button that runs the example in the browser and shows the output under the block.

A code block in Starlight shows code, but readers must copy it to a terminal to see what it does. The `runnable` attribute adds a **Run code** button under the block. The button runs the code in the browser and shows the output above the button.

````md
```py runnable
from statistics import mean, stdev

reads = [1520, 1610, 1480, 1575]
print(f"mean {mean(reads):.0f}, sd {stdev(reads):.1f}")
```
````

Click **Run code**. The first time, the browser downloads Python (Pyodide, a build of Python for the browser), which takes a few seconds. The output panel shows "Loading the Python runtime…" until it is ready, then the output of the code.

## Syntax

| Syntax | Where |
|---|---|
| `runnable` | Code block fence line |
| `runnable.label="<text>"`, `runnable.againLabel="<text>"` | Code block fence line |
| `runnable.timeout=<ms>` | Code block fence line |
| `runnable.packages="<name> <name>"` | Code block fence line |
| `runnable.button="below"`, `runnable.button="title"`, `runnable.button="both"` | Code block fence line |
| `[!output]`, `[!output end]` | Comment in the code, on its own line |
| `[!wait <ms>]` | Comment at the end of a line of output |
| `runnable.output="<text>"`, `runnable.outputDelay=<ms>` | Code block fence line |

### Languages

The language of the block chooses the runtime. Three languages work with no set-up:

| Language | Fence language | Runtime |
|---|---|---|
| Python | `py`, `python`, `pycon` | [Pyodide](https://pyodide.org/), a build of Python for the browser. It downloads from a CDN on the first click. |
| JavaScript | `js`, `javascript`, `mjs`, `cjs` | The browser's own JavaScript engine, in a web worker. |
| TypeScript | `ts`, `typescript`, `mts`, `cts` | The JavaScript runtime, after [Sucrase](https://sucrase.io/) removes the types. |

- For other languages, a site adds a runtime in the [`runtimes` option](#options). The guide to [adding a runtime](https://ewels.github.io/starlight-codeblocks/extend/add-a-runtime/) shows how.
- A site runtime for Python, JavaScript or TypeScript replaces the built-in one.
- Sites without Starlight add each runtime themselves, as in [Without Starlight](https://ewels.github.io/starlight-codeblocks/reference/expressive-code-plugins/#without-starlight).

In JavaScript and TypeScript, `console.log()` and `console.info()` go to standard output. `console.error()` and `console.warn()` go to standard error. The code runs as the body of an `async` function, so `await` works at the top level. The code cannot use `import` statements.

The TypeScript runtime removes the types and does not check them. Code with a type error runs, as it would with `tsx` or Node.js. The runtime downloads Sucrase (about 50 kB) on the first click of a TypeScript block.

### Python packages

The Python runtime reads the `import` lines of the code before it runs it, and installs the packages they need:

1. Packages that are part of Pyodide install from the Pyodide CDN. Pyodide has about 350 packages, such as NumPy, pandas, SciPy and scikit-learn. The [Pyodide package list](https://pyodide.org/en/stable/usage/packages-in-pyodide.html) has them all.
2. Other imports install from [PyPI](https://pypi.org/) with [micropip](https://micropip.pyodide.org/), under the name of the import. This works for pure Python packages: packages with a wheel that ends in `py3-none-any.whl`.

When the package name is not the import name, add `runnable.packages` to the fence line. For example, `import slugify` needs the `python-slugify` package. Without the attribute, the runtime would install the package called `slugify`, which is a different one. Separate several packages with spaces. A name can have a version, such as `tabulate==0.9.0`. The packages install before the code runs, and a package that does not install shows an error in the panel.

For code that cannot run in the browser, such as a command line tool, write its output in the block. The lines after `[!output]` are the output. They leave the code, and the button prints them a line at a time, as if the code ran. `[!output end]` ends the output, for code after it. Without it, the output goes to the end of the block.

The block needs no `runnable` attribute and no runtime, so it works in every language. `[!wait <ms>]` on a line of output waits that long before the next line.

`runnable.output` on the fence line does the same, with `\n` for each new line.

## Examples

### JavaScript, with standard error

`console.log()` goes to standard output and `console.error()` to standard error:

````md
```js runnable
const sizes = [3, 1, 4, 1, 5];
const total = sizes.reduce((sum, size) => sum + size, 0);
console.log('Total:', total);
console.error('Sizes of 1 are deprecated.');
```
````

### TypeScript

A TypeScript block runs after the runtime removes the types:

````md
```ts runnable
interface Sample {
  id: string;
  reads: number;
}

const samples: Sample[] = [
  { id: 'S1', reads: 1520 },
  { id: 'S2', reads: 1610 },
];
const total = samples.reduce((sum: number, s: Sample) => sum + s.reads, 0);
console.log(`${samples.length} samples, ${total} reads`);
```
````

### A package that Pyodide does not have

Tabulate is not part of Pyodide, so the runtime installs it from PyPI. The import name is the package name, so the block needs no attribute:

````md
```py runnable
from tabulate import tabulate

print(tabulate([["S1", 1520], ["S2", 1610]], headers=["Sample", "Reads"]))
```
````

### A package with another name

The import is `slugify`, but the package is `python-slugify`, so `runnable.packages` names it:

````md
```py runnable runnable.packages="python-slugify"
from slugify import slugify

print(slugify("Hello, World: Run Code!"))
```
````

### An error

An error in Python shows the traceback, from the line of the example that failed:

````md
```py runnable
counts = {"passed": 3, "failed": 0}
print(counts["passed"] / counts["failed"])
```
````

### The timeout

Code that never ends stops at the timeout. This loop waits for a value that never changes, so the panel shows the timeout message after 5 seconds:

````md
```js runnable
let ready = false;
while (!ready) {}
```
````

### Scripted output

This command cannot run in the browser, so the block has the output that the command prints. The lines show one at a time, 200 milliseconds apart, with a longer wait while the task runs:

````md
```sh
nextflow run hello.nf
# [!output]
N E X T F L O W  ~  version 25.04.0
Launching hello.nf [nice_curie] DSL2
executor >  local (3) # [!wait 1500]
[4e/8a1f2c] sayHello (3) | 3 of 3 ✔
Hello world!
Bonjour le monde!
Hola mundo!
```
````

### Output only

A block with only output shows the button in the middle of the empty code area. The button fades out when a reader clicks it, and the output takes its place:

````md
```sh
# [!output]
Pulling nextflow-io/hello ...
 downloaded from https://github.com/nextflow-io/hello.git # [!wait 1000]
Hello world!
```
````

### The button in the title bar

`runnable.button="title"` puts the button in the title bar, as the copy button is. `both` shows the button in both places:

````md
```py runnable runnable.button="title"
print(sorted(["chr2", "chr10", "chr1"], key=lambda c: int(c[3:])))
```
````

## Behaviour

- Running code:
  - The button is under the block, in the style of the [code walkthrough](https://ewels.github.io/starlight-codeblocks/features/code-walkthrough/) buttons. The `button` option moves it to the title bar, or shows it in both places.
  - The runtime loads only when a reader clicks **Run code** for the first time. A page with runnable blocks loads a small script, and no runtime.
  - After the first run, the button reads **Run again**. Each run replaces the output of the run before it. The `label` and `againLabel` options change the two texts, for example for a site in another language.
  - The code that runs is the copied text of the block. Directives are removed, and hidden lines are kept. The values that readers type into [fill-in placeholders](https://ewels.github.io/starlight-codeblocks/features/fill-in-placeholders/) are part of it too. For a Python session with `>>>` prompts, only the commands run, as **Copy commands** copies them. They run as in the Python REPL, so the output shows the value of each expression.
  - Every runtime runs the code in a web worker, so the page stays responsive while code runs. Each run starts with no names from earlier runs. In Python, `__name__` is `"__main__"`.
  - In JavaScript and TypeScript, a run ends when the top-level code is done. Output from a timer or a callback that the code does not `await` is lost.
  - A run stops after 10 seconds, with a message in the panel. The download of the runtime and of the packages that the code imports does not count towards this time.
- Scripted output:
  - The panel shows "Running…", then the lines of output, with `outputDelay` milliseconds (200 by default) before each line. With `0`, all the lines show at once. `[!wait]` changes the wait after one line.
  - Scripted output shows as standard output. The button does not run the code, and the block needs no runtime.
  - The output lines are not part of the code that readers see or copy.
  - A block with only output has no copy button. Its **Run code** button is in the middle of the empty code area, and fades out on the first click. Keyboard focus then moves to the output.
- Output:
  - The output panel has the label "Output". Standard output shows in green. Standard error shows in red, with a bar at its start, so the colour is not the only difference.
- Keyboard and screen readers:
  - The output panel is a polite live region. Screen readers announce the loading message and the output when they change.
  - The button keeps the keyboard focus during a run, so readers can run the code again with <kbd>Enter</kbd> or <kbd>Space</kbd>.
- Print:
  - The button does not print.
- Without JavaScript:
  - The button is hidden.

## Options

### `runnable`

Adds a button that runs the code in the browser. Set it to `false` to turn the feature off. `runnable` attributes then have no effect.

- Type: `false | object`
- Default: On

### `runnable.runtimes`

Runtime modules by language: a package path, or a path from the project root. The site entries are added to the built-in Python, JavaScript and TypeScript runtimes, or replace them.

- Type: `Record<string, string>`
- Default: `python`, `javascript` and `typescript`

### `runnable.timeout`

Milliseconds before a run stops, from 1 to 2147483647, the largest delay browsers accept. A code block can set its own on its fence line.

- Type: `number`
- Default: `10000`

### `runnable.label`

The text of the button. A code block can set its own on its fence line.

- Type: `string`
- Default: `'Run code'`

### `runnable.againLabel`

The text of the button after the first run. A code block can set its own on its fence line.

- Type: `string`
- Default: `'Run again'`

### `runnable.button`

Where the button goes: under the block, in the title bar, or both. A code block can set its own on its fence line.

- Type: `'below' | 'title' | 'both'`
- Default: `'below'`

### `runnable.outputDelay`

Milliseconds between the lines of scripted output (`runnable.output`), so that it prints as if the code ran. `0` prints it all at once. A code block can set its own on its fence line.

- Type: `number`
- Default: `200`

A runtime module is a package path, or a path from the project root. This site gives runs 5 seconds, and a site with a Ruby runtime adds it to `runtimes`:

```js title="astro.config.mjs"
codeblocks({
  runnable: {
    runtimes: { ruby: './src/runtimes/ruby.ts' },
    timeout: 5000,
  },
});
```

The guide to [adding a runtime](https://ewels.github.io/starlight-codeblocks/extend/add-a-runtime/) shows how to write one.

- [Configuration](https://ewels.github.io/starlight-codeblocks/configuration/): Learn how to set options for the whole site, or for a single code block.

## Limitations

- The code must be complete to run. Put the imports and set-up in [hidden lines](https://ewels.github.io/starlight-codeblocks/features/hidden-lines/) if they distract from the example.
- The Python runtime has no standard input, so `input()` fails.
- Python packages from PyPI must be pure Python. A package with compiled code works only if it is part of Pyodide.
- JavaScript and TypeScript code cannot `import` modules, and has no access to the page.
- TypeScript blocks with JSX (`tsx`) do not run.
- The Python runtime loads Pyodide from the jsDelivr CDN, and packages from PyPI. Every runtime runs its worker from a `blob:` URL. A Content Security Policy must allow all three.
- To stop a Python run, the runtime ends its worker. The next run downloads the runtime again, from the browser cache if the browser kept it.

## Related

- [Open in playground](https://ewels.github.io/starlight-codeblocks/features/open-in-playground/): send the code to an online playground, for languages that cannot run in the browser.
- [Hidden lines](https://ewels.github.io/starlight-codeblocks/features/hidden-lines/): keep the code complete for the **Run code** button, while readers see only the part you explain.
- [Add a runtime](https://ewels.github.io/starlight-codeblocks/extend/add-a-runtime/): run another language, with the interface that the built-in runtimes use.

---

<!-- https://ewels.github.io/starlight-codeblocks/extend/write-an-api-link-adapter/ -->

# Write an API link adapter

> Add API auto-linking for another language or library, with an adapter that finds names in code and resolves them to reference pages.

[API auto-linking](https://ewels.github.io/starlight-codeblocks/features/api-auto-linking/) links names in code blocks through adapters. The plugin has adapters for Python and Nextflow. A site can add its own adapter for another language, or for its own library, in the `apiLinks.adapters` option.

## The interface

An adapter is an object with a name, a list of languages, two functions and an optional third:

```ts
interface ApiLinkAdapter {
  name: string;
  languages: string[];
  setup(context: AdapterContext): Promise<void>;
  findSymbols(code: string, language: string, attributes: Record<string, string>): SymbolRef[];
  describe?(symbol: SymbolRef): Promise<string | undefined>;
}

interface SymbolRef {
  start: number;
  end: number;
  href: string;
  name: string;
  kind?: string;
  signature?: string;
  summary?: string;
  source: string;
  icon?: string | false;
}
```

| Property | Description |
|---|---|
| `name` | The name of the adapter. Build warnings start with it. |
| `languages` | The languages of the code blocks that the adapter reads, such as `py`. A name also covers the other names of its language: `py` covers `python`. |
| `setup` | Loads the indexes. The plugin calls it once, before the first code block in one of the languages. |
| `findSymbols` | Returns the names in the code that are links, with the link and the text of the card. `attributes` has the attributes on the fence line of the code block that have a text value, such as `title`. |
| `describe` | Optional. Returns a summary for a name that `findSymbols` returned with no `summary`. Use it for text that needs a fetch, such as a documentation page. |

A `SymbolRef` is one name in `code`, its link and the text of its card:

| Property | Description |
|---|---|
| `start` | The index of the first character of the name in `code`. |
| `end` | The index after the last character of the name. |
| `href` | The URL of the reference page. A URL that starts with `/` gets Astro's `base` in front of it. |
| `name` | The qualified name, such as `pathlib.Path`. |
| `kind` | The kind of object, such as `function`, `class` or `process`. |
| `signature` | The first line of the card. Without a signature, the card shows the kind and the name. |
| `summary` | One sentence under the signature. |
| `source` | Where the link comes from, at the bottom of the card. |
| `icon` | The [Simple Icons](https://simpleicons.org/) slug of the icon before the source, such as `flask`, or `false` for no icon. By default, the plugin uses the project at the start of `source`: `NumPy 2.1 documentation` gets the NumPy icon. |

## The adapter context

`setup()` gets a context with these properties:

| Property | Description |
|---|---|
| `root` | The project root, as an absolute path. |
| `cacheDir` | Astro's cache folder, where other integrations keep their data. |
| `fetch(url, check?, options?)` | Gets a URL once, and keeps the body on disk. Returns the body as a `Uint8Array`, or `null`. With `{ quiet: true }`, a failed request shows no warning. |
| `warn(message)` | Logs a build warning with the name of the adapter. |

Use `fetch` from the context to load an index from another site. The body stays in `node_modules/.cache/starlight-codeblocks/`, so later builds read it from disk and work without the network. If the request fails and there is no copy on disk, `fetch` logs a warning and returns `null`. Continue without that index:

```js
async setup(context) {
  const data = await context.fetch('https://example.com/docs/index.json');
  if (data) index = JSON.parse(new TextDecoder().decode(data));
},
```

A server can send an HTML error page with a success status. To stop `fetch` from keeping that page, give it a `check` function that throws for a body you cannot use. `fetch` then keeps nothing, logs a warning that ends with the error message, and returns `null`. If a copy on disk fails the check, `fetch` gets the URL again:

```js
async setup(context) {
  await context.fetch('https://example.com/docs/index.json', (data) => {
    index = JSON.parse(new TextDecoder().decode(data));
  });
},
```

## An example adapter

This site links the names that a JavaScript block imports from starlight-codeblocks to their reference pages. The adapter reads the `import` lines, then finds each imported name outside strings and comments:

```js title="src/adapters/codeblocks-api.mjs"
/** Reference pages of the names that this package exports. */
const pages = {
  codeblocks: {
    href: '/reference/options/',
    signature: 'codeblocks(options?: CodeblocksOptions): StarlightPlugin',
    summary: 'Adds the features to the Starlight site.',
  },
  pluginCodeblocks: {
    href: '/reference/expressive-code-plugins/',
    signature: 'pluginCodeblocks(options?: CodeblocksOptions): ExpressiveCodePlugin[]',
    summary: 'Returns every feature as Expressive Code plugins.',
  },
  python: {
    href: '/features/api-auto-linking/#python-adapter',
    signature: 'python(options?: PythonAdapterOptions): ApiLinkAdapter',
    summary: 'Links Python names through the imports in each block.',
  },
  nextflow: {
    href: '/features/api-auto-linking/#nextflow-adapter',
    signature: 'nextflow(options?: NextflowAdapterOptions): ApiLinkAdapter',
    summary: 'Links Nextflow channel factories, operators and modules.',
  },
};

// Comments and strings come first, so that names inside them never match as names.
const TOKENS = /\/\/.*|\/\*[\s\S]*?\*\/|'(?:\\.|[^'\\\n])*'|"(?:\\.|[^"\\\n])*"|`(?:\\.|[^`\\])*`|[A-Za-z_$][\w$]*/g;
const IMPORT = /^import\s+(?:(\w+)\s*,?\s*)?(?:\{([^}]*)\})?\s+from\s+'starlight-codeblocks(?:\/[\w/-]+)?';?$/gm;

/** Links the names that a JavaScript block imports from starlight-codeblocks to their reference pages. */
export function codeblocksApi() {
  return {
    name: 'codeblocks-api',
    languages: ['js', 'mjs', 'ts'],
    async setup() {},
    findSymbols(code) {
      const imported = new Set();
      for (const [, name, list] of code.matchAll(IMPORT)) {
        for (const item of [name, ...(list?.split(',') ?? [])]) if (item) imported.add(item.trim());
      }
      const symbols = [];
      for (const { 0: name, index } of code.matchAll(TOKENS)) {
        const page = imported.has(name) && pages[name];
        const isKeyOrProperty = code[index - 1] === '.' || /^\s*:(?!:)/.test(code.slice(index + name.length));
        if (page && !isKeyOrProperty) {
          symbols.push({
            start: index,
            end: index + name.length,
            name,
            ...page,
            source: 'starlight-codeblocks reference',
          });
        }
      }
      return symbols;
    },
  };
}
```

To use an adapter, add it to `apiLinks.adapters`. Keep the built-in adapters in the list, because the list replaces the default:

```js title="astro.config.mjs"
import codeblocks from 'starlight-codeblocks';
import { nextflow } from 'starlight-codeblocks/adapters/nextflow';
import { python } from 'starlight-codeblocks/adapters/python';
import { codeblocksApi } from './src/adapters/codeblocks-api.mjs';

codeblocks({
  apiLinks: { adapters: [python(), nextflow(), codeblocksApi()] },
});
```

The code block above shows the result: `codeblocks`, `nextflow` and `python` are links.

## Rules

- Leave out a name when you are not certain about its link. A wrong link is worse than no link.
- Never return names inside strings or comments from `findSymbols`.
- Give positions in the `code` that `findSymbols` gets. The plugin ignores a name that spans two lines.
- Keep `findSymbols` synchronous. Do all slow work, such as a fetch, in `setup`.
- Return the same result for the same code. The functions run at build time, so they cannot read anything from the browser.
- Do not throw in `setup` for a missing index. Log a warning with `context.warn` and continue. If `setup` throws, the build logs a warning, and the adapter links nothing.
- Use `http` or `https` URLs, or URLs inside the site. The plugin drops a link with any other scheme, such as `javascript:`.

If two adapters return the same name, or names that overlap, the first adapter in the list wins.

## Cards on links outside code blocks

Another plugin can give its own links the same card, for example the type names in the signatures of starlight-pydocs. The plugin writes the text of the card on the link. starlight-codeblocks owns the script and the styles.

```md
<p data-scb-api-links="">A mapping is a <a href="https://docs.python.org/3/library/stdtypes.html#dict" target="_blank" rel="noopener" data-scb-api-head="class dict" data-scb-api-summary="Create a new dictionary." data-scb-api-source="Python 3 documentation" data-scb-api-action="Opens docs.python.org in a new tab." aria-description="class dict. Create a new dictionary. Python 3 documentation. Opens docs.python.org in a new tab.">dict</a> of names to values.</p>
```

| Attribute | Where | Description |
|---|---|---|
| `data-scb-api-links` | An element that holds the links | Loads the card script on the page. |
| `data-scb-api-head` | Each `a` element | The first line of the card, such as a signature. The attribute marks the link for the card. |
| `data-scb-api-summary` | Each `a` element, optional | One sentence under the first line. |
| `data-scb-api-source` | Each `a` element, optional | Where the link comes from. |
| `data-scb-api-icon` | Each `a` element, optional | The key of the icon before the source, in `data-scb-api-icons`. |
| `data-scb-api-icons` | The element that holds the links, optional | JSON that maps each icon key to the path of a 24 by 24 SVG icon. |
| `data-scb-api-action` | Each `a` element, optional | What the link does when a reader clicks it, such as "Opens docs.python.org in a new tab." |

- The card works on every page, also on a page with no code blocks. It gets the colours of the code block themes.
- The card is only for sighted readers. Give each link an `aria-description` with the same text for screen readers.
- The attributes are a public interface. A change to them is a breaking change.
- The card needs `codeblocks()` in the Starlight plugins. It does not work with the Expressive Code preset alone.

---

<!-- https://ewels.github.io/starlight-codeblocks/extend/add-a-playground/ -->

# Add a playground

> Add a custom playground to the site, for any online playground that takes code in its URL or in a form post.

The plugin has two built-in playgrounds: `typescript` and `rust`. A site can add its own playgrounds in the `playgrounds` option. After that, a code block opens one with `playground="<name>"`, the same as a built-in playground.

## The interface

A playground is an object with a label and one of two functions:

```ts
interface PlaygroundDefinition {
  label: string;
  // One of these two:
  url?: (input: { code: string; lang: string; title?: string }) => string;
  post?: (input: { code: string; lang: string; title?: string }) => {
    action: string;
    fields: Record<string, string>;
  };
}
```

| Property | Description |
|---|---|
| `label` | The text of the button, such as **Open in Python Tutor**. |
| `url` | Returns the URL that opens the playground. The button is a link. |
| `post` | Returns the address of a form and the values of its fields. The button submits the form. |

The input of both functions has three properties:

| Property | Description |
|---|---|
| `code` | The copied text of the block. Directives are removed, hidden lines are kept, and a terminal session has only its commands. |
| `lang` | The language of the block, as written on the first line of the code block, such as `py`. |
| `title` | The `title` attribute of the block, if it has one. |

The plugin calls the function once for each block, when the site builds. Both kinds of button open the playground in a new tab.

## Add a URL playground

Use `url` for a playground that reads the code from its address. This site adds Python Tutor:

1. Open `astro.config.mjs`.
2. Add an entry to `playgrounds` in the options of `codeblocks()`.
3. Put the code in the URL with `encodeURIComponent()`.

```js title="astro.config.mjs"
codeblocks({
  playgrounds: {
    pythontutor: {
      label: 'Open in Python Tutor',
      url: ({ code }) => `https://pythontutor.com/visualize.html#mode=edit&py=3&code=${encodeURIComponent(code)}`,
    },
  },
});
```

A code block with `playground="pythontutor"` now has the button. The [open in playground](https://ewels.github.io/starlight-codeblocks/features/open-in-playground/#examples) page shows it.

## Add a form post playground

Use `post` for a playground that takes a project in a form, such as StackBlitz. The plugin renders a form with one hidden field for each entry in `fields`. This site adds StackBlitz with this configuration:

```js title="astro.config.mjs"
codeblocks({
  playgrounds: {
    stackblitz: {
      label: 'Open in StackBlitz',
      post: ({ code, title }) => ({
        action: 'https://stackblitz.com/run',
        fields: {
          'project[title]': title ?? 'Example',
          'project[template]': 'javascript',
          'project[files][index.js]': code,
          'project[files][index.html]': '<script type="module" src="index.js"></script>',
        },
      }),
    },
  },
});
```

## Rules

- Give each playground one of `url` or `post`. The build fails if a playground has both, or neither.
- Return the same result for the same input. The function runs at build time, so it cannot read anything from the browser.
- Keep URLs under 8,000 characters. The build logs a warning for a longer URL, because some browsers cut it. Use `post` for playgrounds that take long code.
- Put the code in the URL with `encodeURIComponent()`, and put it in a form field as it is. The plugin can then put the values of [fill-in placeholders](https://ewels.github.io/starlight-codeblocks/features/fill-in-placeholders/) into the code when readers type.
- Name the playground after the site that runs the code. A custom playground with the name `typescript` or `rust` replaces the built-in one.
- Test each playground in a browser once. The plugin cannot check that the playground accepts the code.

---

<!-- https://ewels.github.io/starlight-codeblocks/extend/add-a-runtime/ -->

# Add a runtime

> Add a runtime for another language, so that the Run code button can run its code blocks in the browser.

The **Run code** button of [run code](https://ewels.github.io/starlight-codeblocks/features/run-code/) gives the code of a block to a runtime. The plugin has runtimes for Python, JavaScript and TypeScript. A site can add a runtime for any other language in the `runnable.runtimes` option, or replace a built-in one.

## The interface

A runtime is a module whose default export has two functions:

```ts
interface Runtime {
  load(code: string, options?: { packages?: string[] }): Promise<void>;
  run(code: string, options: { signal: AbortSignal; session?: boolean }): Promise<{ stdout: string; stderr: string }>;
}
```

| Function | Description |
|---|---|
| `load()` | Downloads and starts the runtime, and gets the packages that `code` needs. `packages` holds the names in the block's `runnable.packages` attribute. The plugin calls it with the code before each run, so it must return at once when the runtime and the packages are ready. The timeout does not apply to it. |
| `run()` | Runs the copied text of the block, and returns its standard output and standard error as text. |

The browser imports the module when a reader clicks **Run code** for the first time, and calls `load()` at once. Import the `Runtime` type from `starlight-codeblocks` to check a module in TypeScript.

When the block is a session with prompts, `code` is its commands and `session` is `true`. Run the commands as the language's REPL does, so that the output shows the value of each expression, as the block does.

The `signal` of `run()` aborts when the run takes longer than `runnable.timeout`. The runtime must then stop the code and reject the promise. The plugin shows the timeout message, and calls `load()` again before the next run.

## An example: the JavaScript runtime

The built-in JavaScript runtime is a complete example. It runs the code in a web worker. Each run gets a new worker, which the runtime ends when the top-level code is done or the signal aborts. The output of a timer or a callback that the code does not `await` is lost, because the worker is gone when it runs:

```ts title="starlight-codeblocks/src/runtimes/javascript.ts"
import type { Runtime } from '../options.ts';

// The worker has no access to the page. console.log, info, warn and error go to the output panel.
const source = `
const stdout = [];
const stderr = [];
const format = (a) => {
  if (typeof a === 'string') return a;
  if (typeof a === 'bigint') return a + 'n';
  if (a instanceof Error) return String(a);
  if (a instanceof Map || a instanceof Set) return a.constructor.name + ' ' + format([...a]);
  try {
    return JSON.stringify(a) ?? String(a);
  } catch {
    return String(a);
  }
};
const text = (args) => args.map(format).join(' ');
console.log = console.info = (...args) => stdout.push(text(args));
console.error = console.warn = (...args) => stderr.push(text(args));
const done = () => postMessage({ stdout: stdout.join('\\n'), stderr: stderr.join('\\n') });
// Errors in timers and other callbacks escape the try/catch.
onerror = (message) => {
  stderr.push(String(message));
  done();
  return true;
};
onunhandledrejection = ({ reason }) => {
  stderr.push(String(reason));
  done();
};
onmessage = async ({ data: code }) => {
  try {
    const AsyncFunction = (async () => {}).constructor;
    await new AsyncFunction(code)();
  } catch (error) {
    stderr.push(String(error));
  }
  done();
};`;

let url: string | undefined;

/** Runs JavaScript in a new web worker, which ends when the top-level code is done or the signal aborts. */
export function runJavaScript(code: string, { signal }: { signal: AbortSignal }) {
  url ??= URL.createObjectURL(new Blob([source], { type: 'text/javascript' }));
  const worker = new Worker(url);
  return new Promise<{ stdout: string; stderr: string }>((resolve, reject) => {
    signal.addEventListener('abort', () => {
      worker.terminate();
      reject(signal.reason);
    });
    worker.onmessage = ({ data }) => {
      worker.terminate();
      resolve(data);
    };
    worker.postMessage(code);
  });
}

const runtime: Runtime = {
  async load() {},
  run: runJavaScript,
};

export default runtime;
```

## Add a runtime to a site

1. Save the module in the project, for example as `src/runtimes/ruby.ts`.
2. Open `astro.config.mjs`.
3. Add the language and the path of the module to `runnable.runtimes`.

```js title="astro.config.mjs"
codeblocks({
  runnable: {
    runtimes: { ruby: './src/runtimes/ruby.ts' },
  },
});
```

A code block with ` ```ruby runnable ` now has the **Run code** button. The key is the language name, and its aliases work too: `rb` and `ruby` both use this runtime. A path that starts with `.` is from the project root. Any other path is a package path, such as `starlight-codeblocks/runtimes/pyodide`.

A runtime for `python`, `javascript` or `typescript` replaces the built-in one. The built-in runtimes are `starlight-codeblocks/runtimes/pyodide`, `starlight-codeblocks/runtimes/javascript` and `starlight-codeblocks/runtimes/typescript`. A site runtime can import them, for example to run JavaScript after it compiles another language.

## Change the Pyodide URL

The Python runtime loads Pyodide from the jsDelivr CDN. To load it from a different URL, make a runtime module with the `pyodide()` function of the package:

```ts title="src/runtimes/python.ts"
import { pyodide } from 'starlight-codeblocks/runtimes/pyodide';

export default pyodide({ url: 'https://example.com/pyodide/v314.0.7/full/' });
```

Then map `python` to it in `runnable.runtimes`, as for any other runtime. The URL is the folder that holds `pyodide.mjs`, with a trailing slash. The runtime resolves a relative URL, such as `/pyodide/full/` for a copy in `public/`, against the page.

## Rules

- Run the code away from the page, in a web worker or a sandboxed `iframe`. Code in a worker cannot freeze the page or read it.
- Stop the code when the signal aborts. Code in a worker stops only when the runtime ends the worker.
- Return an error in the code as `stderr`, and resolve the promise. Reject the promise only when the runtime cannot run code at all. The panel then shows the message of the error.
- Download nothing when the module is imported. Start downloads in `load()`.
- Give each run a clean state, so that the result of a block does not depend on the blocks that ran before it.
- Test the runtime in a browser, with an error, an endless loop and a block with no output.
- Without `codeblocks()`, a site that adds the Expressive Code plugins itself has no build step for runtimes. The values of `runnable.runtimes` are then URLs of JavaScript modules, and there are no built-in runtimes unless the site adds them.

---

<!-- https://ewels.github.io/starlight-codeblocks/reference/options/ -->

# Options

> Every option of codeblocks() and pluginCodeblocks(), with its type and default.

`codeblocks()` and `pluginCodeblocks()` take the same options object. A key with the type `false | object` takes `false` to turn the feature off, or an object with the settings below it. A key with the type `false` has no settings. The [configuration](https://ewels.github.io/starlight-codeblocks/configuration/) page shows how to use them.

## `focus`

Blurs the lines outside a focus range. Set it to `false` to turn the feature off. `[!code focus]` then stays in the code as written.

- Type: `false | object`
- Default: On
- Feature: [Focus](https://ewels.github.io/starlight-codeblocks/features/focus/)

## `focus.style`

Blur and fade the other lines, or only fade them. A code block can set its own on its fence line.

- Type: `'blur' | 'dim'`
- Default: `'blur'`
- Feature: [Focus](https://ewels.github.io/starlight-codeblocks/features/focus/)

## `lineStates`

Tints lines as errors, warnings, notes or successes, with an optional message. Set it to `false` to turn the feature off. The directives then stay in the code as written.

- Type: `false | object`
- Default: On
- Feature: [Line states](https://ewels.github.io/starlight-codeblocks/features/line-states/)

## `lineStates.states`

Custom states by name, in addition to `error`, `warning`, `info` and `success`. A name uses lower-case letters, digits and hyphens.

- Type: `Record<string, { label: string; colour: { dark: string; light: string } }>`
- Default: `{}`
- Feature: [Line states](https://ewels.github.io/starlight-codeblocks/features/line-states/)

## `lineStates.prefix`

Show the name of the state, such as **Error**, before each message, and on the first line of a run with no message. Off, the tint alone marks the state on screen. A code block can set its own on its fence line.

- Type: `boolean`
- Default: `true`
- Feature: [Line states](https://ewels.github.io/starlight-codeblocks/features/line-states/)

## `notation`

Reads directives in code comments. Set it to `false` to turn the feature off. Every comment then renders as written.

- Type: `false | object`
- Default: On
- Feature: [Comment notation](https://ewels.github.io/starlight-codeblocks/comment-notation/)

## `notation.comments`

Comment syntax for each language, added to the built-in map. An empty list removes a language.

- Type: `Record<string, string[]>`
- Default: `{}`
- Feature: [Comment notation](https://ewels.github.io/starlight-codeblocks/comment-notation/)

## `callouts`

Shows a note in a bubble above a line. Set it to `false` to turn the feature off.

- Type: `false`
- Default: On
- Feature: [Inline callouts](https://ewels.github.io/starlight-codeblocks/features/inline-callouts/)

## `annotations`

Adds numbered markers that open a note. Set it to `false` to turn the feature off.

- Type: `false | object`
- Default: On
- Feature: [Annotations](https://ewels.github.io/starlight-codeblocks/features/annotations/)

## `annotations.style`

Filled markers in the accent colour, or outlined markers in the magenta of the theme. Side annotations use it too. A code block can set its own on its fence line.

- Type: `'filled' | 'outline'`
- Default: `'filled'`
- Feature: [Annotations](https://ewels.github.io/starlight-codeblocks/features/annotations/)

## `footnotes`

Adds numbered badges to lines, with the notes in a list under the block. Set it to `false` to turn the feature off.

- Type: `false | object`
- Default: On
- Feature: [Footnotes](https://ewels.github.io/starlight-codeblocks/features/footnotes/)

## `footnotes.sticky`

Keep the list of footnotes in view while the block is on screen. A code block can set its own on its fence line.

- Type: `boolean`
- Default: `false`
- Feature: [Footnotes](https://ewels.github.io/starlight-codeblocks/features/footnotes/)

## `footnotes.style`

Filled badges in the accent colour, or outlined badges in the magenta of the theme. A code block can set its own on its fence line.

- Type: `'filled' | 'outline'`
- Default: `'outline'`
- Feature: [Footnotes](https://ewels.github.io/starlight-codeblocks/features/footnotes/)

## `hiddenLines`

Hides lines that readers need to run the code but not to understand it. Set it to `false` to turn the feature off.

- Type: `false`
- Default: On
- Feature: [Hidden lines](https://ewels.github.io/starlight-codeblocks/features/hidden-lines/)

## `shellCopy`

Adds a Copy commands button to terminal blocks with prompts, which copies the commands only. Set it to `false` to turn the feature off.

- Type: `false | object`
- Default: On
- Feature: [Smart shell copy](https://ewels.github.io/starlight-codeblocks/features/smart-shell-copy/)

## `shellCopy.prompts`

Line starts that mark a command. A code block can set its own on its fence line.

- Type: `string[]`
- Default: `['$ ','> ']`
- Feature: [Smart shell copy](https://ewels.github.io/starlight-codeblocks/features/smart-shell-copy/)

## `wordDiff`

Highlights the words that changed between a removed line and an added line. Set it to `false` to turn the feature off.

- Type: `false | object`
- Default: On
- Feature: [Word-level diff](https://ewels.github.io/starlight-codeblocks/features/word-level-diff/)

## `wordDiff.minSimilarity`

Pairs of lines less similar than this keep whole-line tints only. From 0 to 1. A code block can set its own on its fence line.

- Type: `number`
- Default: `0.4`
- Feature: [Word-level diff](https://ewels.github.io/starlight-codeblocks/features/word-level-diff/)

## `whitespace`

Shows spaces and tabs as faint glyphs. Set it to `false` to turn the feature off.

- Type: `false`
- Default: On
- Feature: [Visible whitespace](https://ewels.github.io/starlight-codeblocks/features/visible-whitespace/)

## `brackets`

Colours matching brackets by nesting depth. Set it to `false` to turn the feature off.

- Type: `false | object`
- Default: On
- Feature: [Colourised brackets](https://ewels.github.io/starlight-codeblocks/features/colourised-brackets/)

## `brackets.languages`

Languages that get colourised brackets in every block.

- Type: `string[]`
- Default: `[]`
- Feature: [Colourised brackets](https://ewels.github.io/starlight-codeblocks/features/colourised-brackets/)

## `swatches`

Shows a swatch of the colour before each CSS colour in code. Set it to `false` to turn the feature off.

- Type: `false | object`
- Default: On
- Feature: [Colour swatches](https://ewels.github.io/starlight-codeblocks/features/colour-swatches/)

## `swatches.languages`

Languages that get swatches. `swatches` on the fence line turns them on for one block of another language.

- Type: `'all' | string[]`
- Default: `'all'`
- Feature: [Colour swatches](https://ewels.github.io/starlight-codeblocks/features/colour-swatches/)

## `swatches.formats`

The kinds of colour that get swatches. `rgb` also covers `rgba()`, and `hsl` covers `hsla()`. `named` is the CSS colour names, such as `rebeccapurple`.

- Type: `Array<'hex' | 'rgb' | 'hsl' | 'hwb' | 'lab' | 'lch' | 'oklab' | 'oklch' | 'color' | 'named'>`
- Default: `['hex','rgb','hsl','hwb','lab','lch','oklab','oklch','color','named']`
- Feature: [Colour swatches](https://ewels.github.io/starlight-codeblocks/features/colour-swatches/)

## `swatches.shape`

The shape of each swatch. A code block can set its own on its fence line.

- Type: `'square' | 'rounded' | 'circle'`
- Default: `'rounded'`
- Feature: [Colour swatches](https://ewels.github.io/starlight-codeblocks/features/colour-swatches/)

## `swatches.size`

The width and height of each swatch, as a CSS length such as `10px` or `0.8em`.

- Type: `string`
- Default: `'0.8em'`
- Feature: [Colour swatches](https://ewels.github.io/starlight-codeblocks/features/colour-swatches/)

## `swatches.hover`

Tint the colour text in its own colour, and enlarge the swatch, when the mouse cursor is on it.

- Type: `boolean`
- Default: `true`
- Feature: [Colour swatches](https://ewels.github.io/starlight-codeblocks/features/colour-swatches/)

## `swatches.copy`

Copy the colour when the reader clicks it.

- Type: `boolean`
- Default: `true`
- Feature: [Colour swatches](https://ewels.github.io/starlight-codeblocks/features/colour-swatches/)

## `swatches.prose`

Also show swatches in the text of Markdown pages, and in inline code that is one colour. Named colours get a swatch only in inline code.

- Type: `boolean`
- Default: `false`
- Feature: [Colour swatches](https://ewels.github.io/starlight-codeblocks/features/colour-swatches/)

## `swatches.match`

Outside stylesheets, `value` shows a swatch only for a colour that looks like a value. `all` shows a swatch for every hex colour and colour function. A code block can set its own on its fence line.

- Type: `'value' | 'all'`
- Default: `'value'`
- Feature: [Colour swatches](https://ewels.github.io/starlight-codeblocks/features/colour-swatches/)

## `swatches.delimiters`

More text that can come before or after a colour that looks like a value, such as `|`. They add to the built-in delimiters.

- Type: `{ before?: string[]; after?: string[] }`
- Default: `{}`
- Feature: [Colour swatches](https://ewels.github.io/starlight-codeblocks/features/colour-swatches/)

## `swatches.byLanguage`

A `match` and `delimiters` for the blocks of each language. They replace the site settings for that language.

- Type: `Record<string, { match?: 'value' | 'all'; delimiters?: { before?: string[]; after?: string[] } }>`
- Default: `{}`
- Feature: [Colour swatches](https://ewels.github.io/starlight-codeblocks/features/colour-swatches/)

## `fileIcons`

Shows the icon of the file type before the title of a code block. Set it to `false` to turn the feature off. `icon` attributes then have no effect.

- Type: `false | object`
- Default: On
- Feature: [File icons](https://ewels.github.io/starlight-codeblocks/features/file-icons/)

## `fileIcons.set`

The icons: the coloured icons of vscode-icons, Material Icon Theme or Catppuccin, or the one-colour Seti icons of the Starlight file tree. Material and Catppuccin need their `@iconify-json` package, such as `@iconify-json/catppuccin`.

- Type: `'seti' | 'material' | 'vscode-icons' | 'catppuccin'`
- Default: `'vscode-icons'`
- Feature: [File icons](https://ewels.github.io/starlight-codeblocks/features/file-icons/)

## `fileIcons.style`

The icon alone, or the icon on a square with rounded corners. A language or a code block can set its own.

- Type: `'plain' | 'tile'`
- Default: `'plain'`
- Feature: [File icons](https://ewels.github.io/starlight-codeblocks/features/file-icons/)

## `fileIcons.languages`

Settings for the blocks of each language: the icon when the title gives none, as an icon name or SVG markup, or `false` for none, a CSS colour for the icon or the tile, and the style.

- Type: `Record<string, { icon?: string | false; colour?: string; style?: 'plain' | 'tile' }>`
- Default: `{}`
- Feature: [File icons](https://ewels.github.io/starlight-codeblocks/features/file-icons/)

## `fileIcons.files`

Icon names, or `false` for no icon, by file name, such as `nextflow.config`, by extension, such as `.nf`, or by path pattern, such as `.github/**`. A `*` matches within one folder, and `**` across folders. They come before the built-in rules.

- Type: `Record<string, string | false>`
- Default: `{}`
- Feature: [File icons](https://ewels.github.io/starlight-codeblocks/features/file-icons/)

## `fileIcons.icons`

Custom icons by name: SVG markup, or the path data of a 24 by 24 icon. A custom name replaces a built-in icon of the same name.

- Type: `Record<string, string>`
- Default: `{}`
- Feature: [File icons](https://ewels.github.io/starlight-codeblocks/features/file-icons/)

## `codeLinks`

Turns text on a line into a link. Set it to `false` to turn the feature off.

- Type: `false`
- Default: On
- Feature: [Code links](https://ewels.github.io/starlight-codeblocks/features/code-links/)

## `apiLinks`

Links names in code to their reference pages. Set it to `false` to turn the feature off.

- Type: `false | object`
- Default: On
- Feature: [API auto-linking](https://ewels.github.io/starlight-codeblocks/features/api-auto-linking/)

## `apiLinks.adapters`

Adapters that find and resolve names.

- Type: `ApiLinkAdapter[]`
- Default: `[python(), nextflow()]`
- Feature: [API auto-linking](https://ewels.github.io/starlight-codeblocks/features/api-auto-linking/)

## `expandable`

Shows the first lines of long blocks, with a button to show the rest. Set it to `false` to turn the feature off. `expandable` and `expandable={N}` then have no effect.

- Type: `false | object`
- Default: On
- Feature: [Expandable blocks](https://ewels.github.io/starlight-codeblocks/features/expandable-blocks/)

## `expandable.lines`

Lines to show before the block expands. A code block can set its own on its fence line.

- Type: `number`
- Default: `12`
- Feature: [Expandable blocks](https://ewels.github.io/starlight-codeblocks/features/expandable-blocks/)

## `expandable.auto`

Makes every block with more lines than this expandable, without the attribute. `expandable=false` turns it off for one block.

- Type: `number | false`
- Default: `false`
- Feature: [Expandable blocks](https://ewels.github.io/starlight-codeblocks/features/expandable-blocks/)

## `playgrounds`

Adds a button that opens the code in an online playground. Set it to `false` to turn the feature off. `playground` attributes then have no effect.

- Type: `false | object`
- Default: On
- Feature: [Open in playground](https://ewels.github.io/starlight-codeblocks/features/open-in-playground/)

## `playgrounds.<name>`

Custom playgrounds by name, in addition to the built-in ones.

- Type: an object with a `label` and one of `url` or `post`
- Default: None
- Feature: [Open in playground](https://ewels.github.io/starlight-codeblocks/features/open-in-playground/)

## `mentions`

Highlights lines when the reader hovers over a link in the prose. Set it to `false` to turn the feature off.

- Type: `false`
- Default: On
- Feature: [Code mentions](https://ewels.github.io/starlight-codeblocks/features/code-mentions/)

## `permalinks`

Turns line numbers into links to each line. Set it to `false` to turn the feature off.

- Type: `false`
- Default: On
- Feature: [Line permalinks](https://ewels.github.io/starlight-codeblocks/features/line-permalinks/)

## `placeholders`

Turns placeholder text into input fields. Set it to `false` to turn the feature off.

- Type: `false | object`
- Default: On
- Feature: [Fill-in placeholders](https://ewels.github.io/starlight-codeblocks/features/fill-in-placeholders/)

## `placeholders.storage`

Where the browser keeps the values that readers type. A code block can set its own on its fence line.

- Type: `'local' | 'session' | 'none'`
- Default: `'local'`
- Feature: [Fill-in placeholders](https://ewels.github.io/starlight-codeblocks/features/fill-in-placeholders/)

## `codeTabs`

Combines several variants of a block, with tabs or a menu in the title bar. Set it to `false` to turn the feature off.

- Type: `false | object`
- Default: On
- Feature: [Code tabs](https://ewels.github.io/starlight-codeblocks/features/code-tabs/)

## `codeTabs.control`

Editor tabs in the title bar, or a menu on its right. A `:::code-tabs` directive can set its own with `control="…"`.

- Type: `'tabs' | 'menu'`
- Default: `'tabs'`
- Feature: [Code tabs](https://ewels.github.io/starlight-codeblocks/features/code-tabs/)

## `walkthrough`

Animates the code between the steps of a `<CodeWalkthrough>` component. Set it to `false` to turn the feature off. `<CodeWalkthrough>` then shows each step as a separate block, with its label after the title, and loads no script.

- Type: `false`
- Default: On
- Feature: [Code walkthrough](https://ewels.github.io/starlight-codeblocks/features/code-walkthrough/)

## `scrollycoding`

Changes the focus of a sticky block as the prose steps scroll past. Set it to `false` to turn the feature off.

- Type: `false`
- Default: On
- Feature: [Scrollycoding](https://ewels.github.io/starlight-codeblocks/features/scrollycoding/)

## `inlineHighlighting`

Adds syntax colours to inline code with a `{:lang}` suffix. Set it to `false` to turn the feature off.

- Type: `false | object`
- Default: On
- Feature: [Inline code highlighting](https://ewels.github.io/starlight-codeblocks/features/inline-code-highlighting/)

## `inlineHighlighting.defaultLanguage`

The language of inline code with no suffix. `{:txt}` keeps one piece of inline code plain.

- Type: `string | false`
- Default: `false`
- Feature: [Inline code highlighting](https://ewels.github.io/starlight-codeblocks/features/inline-code-highlighting/)

## `runnable`

Adds a button that runs the code in the browser. Set it to `false` to turn the feature off. `runnable` attributes then have no effect.

- Type: `false | object`
- Default: On
- Feature: [Run code](https://ewels.github.io/starlight-codeblocks/features/run-code/)

## `runnable.runtimes`

Runtime modules by language: a package path, or a path from the project root. The site entries are added to the built-in Python, JavaScript and TypeScript runtimes, or replace them.

- Type: `Record<string, string>`
- Default: `python`, `javascript` and `typescript`
- Feature: [Run code](https://ewels.github.io/starlight-codeblocks/features/run-code/)

## `runnable.timeout`

Milliseconds before a run stops, from 1 to 2147483647, the largest delay browsers accept. A code block can set its own on its fence line.

- Type: `number`
- Default: `10000`
- Feature: [Run code](https://ewels.github.io/starlight-codeblocks/features/run-code/)

## `runnable.label`

The text of the button. A code block can set its own on its fence line.

- Type: `string`
- Default: `'Run code'`
- Feature: [Run code](https://ewels.github.io/starlight-codeblocks/features/run-code/)

## `runnable.againLabel`

The text of the button after the first run. A code block can set its own on its fence line.

- Type: `string`
- Default: `'Run again'`
- Feature: [Run code](https://ewels.github.io/starlight-codeblocks/features/run-code/)

## `runnable.button`

Where the button goes: under the block, in the title bar, or both. A code block can set its own on its fence line.

- Type: `'below' | 'title' | 'both'`
- Default: `'below'`
- Feature: [Run code](https://ewels.github.io/starlight-codeblocks/features/run-code/)

## `runnable.outputDelay`

Milliseconds between the lines of scripted output (`runnable.output`), so that it prints as if the code ran. `0` prints it all at once. A code block can set its own on its fence line.

- Type: `number`
- Default: `200`
- Feature: [Run code](https://ewels.github.io/starlight-codeblocks/features/run-code/)

---

<!-- https://ewels.github.io/starlight-codeblocks/reference/attributes/ -->

# Attributes

> Every attribute that the plugin reads on the first line of a code block, with an example of each.

An attribute goes on the fence line (the first line of the code block), after the language. A flag, such as `brackets`, is a name on its own. A value is in quotes, as in `playground="rust"`, or in braces for a range or a number, as in `focus={2-4}`. The [comment notation](https://ewels.github.io/starlight-codeblocks/comment-notation/) page explains how line numbers count in a range.

The attributes of Expressive Code, such as `title`, `frame`, `mark`, `ins`, `del`, `wrap` and `showLineNumbers`, keep working as before. The [Expressive Code docs](https://expressive-code.com/) describe them.

## `focus={range}`

Focuses the lines in the range. The other lines are blurred.

- Feature: [Focus](https://ewels.github.io/starlight-codeblocks/features/focus/)

````md
```js focus={2}
const host = 'localhost'
const port = 8080
const debug = false
```
````

## `error={range}`, `warning={range}`, `info={range}`, `success={range}`, `note={range}`, `warn={range}`

Marks the lines in the range with a line state. `note` is the same as `info`, and `warn` the same as `warning`. The attribute gives no message. Use a directive for a message.

- Feature: [Line states](https://ewels.github.io/starlight-codeblocks/features/line-states/)

````md
```js error={2}
const retries = 3
const delay = -1
const timeout = 5000
```
````

## `<state>={range}`

Marks the lines in the range with a custom line state from the `lineStates.states` option. This site defines `todo`.

- Feature: [Line states](https://ewels.github.io/starlight-codeblocks/features/line-states/)

````md
```js todo={2}
const host = 'localhost'
const port = 8080
const debug = false
```
````

## `hidden={range}`

Hides the lines in the range behind a marker. The copy button still copies them.

- Feature: [Hidden lines](https://ewels.github.io/starlight-codeblocks/features/hidden-lines/)

````md
```js hidden={1-2}
import { readFile } from 'node:fs/promises';

const text = await readFile('config.json', 'utf8');
```
````

## `whitespace`, `whitespace="all"`

Shows spaces and tabs as faint glyphs. The flag shows leading whitespace only. `"all"` shows every space and tab.

- Feature: [Visible whitespace](https://ewels.github.io/starlight-codeblocks/features/visible-whitespace/)

````md
```yaml whitespace
server:
  port: 8080
  hosts:
    - example.com
```
````

## `brackets`, `brackets=false`

Colours matching brackets by nesting depth. The `brackets.languages` option turns it on for whole languages, and `brackets=false` turns it off for one block.

- Feature: [Colourised brackets](https://ewels.github.io/starlight-codeblocks/features/colourised-brackets/)

````md
```js brackets
const total = items.map((item) => item.price * (1 + tax));
```
````

## `swatches`, `swatches=false`

Shows a swatch before each CSS colour. Swatches are on for every block by default, and `swatches=false` turns them off for one block. With `swatches.languages` set, `swatches` turns them on for a block of another language.

- Feature: [Colour swatches](https://ewels.github.io/starlight-codeblocks/features/colour-swatches/)

````md
```css swatches=false
.button {
  color: #ffffff;
  background: rebeccapurple;
}
```
````

## `swatches.shape="square"`, `swatches.shape="rounded"`, `swatches.shape="circle"`

Sets the shape of the swatches in the block. It overrides the `swatches.shape` option for the block.

- Feature: [Colour swatches](https://ewels.github.io/starlight-codeblocks/features/colour-swatches/)

````md
```css swatches.shape="circle"
.badge {
  background: #2563eb;
}
```
````

## `swatches.match="all"`, `swatches.match="value"`

Sets which colours get a swatch in the block. `"all"` shows a swatch for every hex colour and colour function. It overrides the `swatches.match` option for the block.

- Feature: [Colour swatches](https://ewels.github.io/starlight-codeblocks/features/colour-swatches/)

````md
```text swatches.match="all"
line: main | Main | #4caf50
```
````

## `icon="<name>"`, `icon=false`, `no-icon`

Sets the file icon before the title: an icon of the icon set, a Seti icon such as `react`, or a name from the `fileIcons.icons` option. `icon=false` and `no-icon` remove it.

- Feature: [File icons](https://ewels.github.io/starlight-codeblocks/features/file-icons/)

````md
```js title="vite.config.js" icon="vite"
export default {};
```
````

## `fileIcons.set="seti"`, `fileIcons.set="material"`, `fileIcons.set="vscode-icons"`, `fileIcons.set="catppuccin"`

Takes the file icon from vscode-icons, Material Icon Theme, Catppuccin or the Seti icons. It overrides the `fileIcons.set` option for the block. Material and Catppuccin need their `@iconify-json` package.

- Feature: [File icons](https://ewels.github.io/starlight-codeblocks/features/file-icons/)

````md
```json title="package.json" fileIcons.set="material"
{ "name": "my-site" }
```
````

## `fileIcons.style="plain"`, `fileIcons.style="tile"`

Shows the file icon alone, or on a square with rounded corners. It overrides the `fileIcons.style` option for the block.

- Feature: [File icons](https://ewels.github.io/starlight-codeblocks/features/file-icons/)

````md
```py title="app.py" fileIcons.style="tile"
print("Hello")
```
````

## `fileIcons.colour="<colour>"`

Sets the colour of the file icon, or of the square in the `tile` style, as a CSS colour such as `#3776ab`.

- Feature: [File icons](https://ewels.github.io/starlight-codeblocks/features/file-icons/)

````md
```py title="app.py" fileIcons.colour="#3776ab"
print("Hello")
```
````

## `wordDiff=false`

Turns off word-level diff for the block. Changed lines keep their whole-line tints.

- Feature: [Word-level diff](https://ewels.github.io/starlight-codeblocks/features/word-level-diff/)

````md
```diff wordDiff=false
-const port = 3000
+const port = 8080
```
````

## `apiLinks=false`

Turns off API auto-linking for the block. Names stay plain text.

- Feature: [API auto-linking](https://ewels.github.io/starlight-codeblocks/features/api-auto-linking/)

````md
```py apiLinks=false
import json

config = json.loads('{"port": 8080}')
```
````

## `pydocsBase="<base>"`

Makes the Python adapter link names to the starlight-pydocs package at this base first, such as `1x/api/myproject` for an older version. Names that this package does not have link as usual.

- Feature: [API auto-linking](https://ewels.github.io/starlight-codeblocks/features/api-auto-linking/)

## `expandable`, `expandable={N}`, `expandable=false`

Shows the first lines of the block, with a button to show the rest. The flag shows the number of lines in the `expandable.lines` option. `{N}` shows `N` lines. `false` turns off the `expandable.auto` option for the block.

- Feature: [Expandable blocks](https://ewels.github.io/starlight-codeblocks/features/expandable-blocks/)

````md
```yaml expandable={3}
name: Build
on: push
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
```
````

## `playground="<name>"`

Adds a button to the title bar that opens the code in a playground. The built-in names are `typescript` and `rust`.

- Feature: [Open in playground](https://ewels.github.io/starlight-codeblocks/features/open-in-playground/)

````md
```ts playground="typescript"
const greet = (name: string) => 'Hello, ' + name;
```
````

## `id="<id>"`

Turns on line numbers, and makes each number a link to its line, as `#<id>-L<n>`.

- Feature: [Line permalinks](https://ewels.github.io/starlight-codeblocks/features/line-permalinks/)

````md
```js id="server"
const host = 'localhost'
const port = 8080
```
````

## `placeholder="<A>,<B>"`

Turns each listed text in the block into an input field. The value that a reader types fills every block on the site.

- Feature: [Fill-in placeholders](https://ewels.github.io/starlight-codeblocks/features/fill-in-placeholders/)

````md
```sh placeholder="YOUR_TOKEN"
export API_TOKEN=YOUR_TOKEN
```
````

## `annotations="side"`

Shows the `[!annotate]` notes of the block in a column beside the code, on wide screens.

- Feature: [Side annotations](https://ewels.github.io/starlight-codeblocks/features/side-annotations/)

````md
```js annotations="side"
const port = 8080 // [!annotate] The port that the server listens on.
const host = 'localhost'
```
````

## `codeSide="right"`

With `annotations="side"`, puts the code in the right column and the notes in the left column. The default is `left`.

- Feature: [Side annotations](https://ewels.github.io/starlight-codeblocks/features/side-annotations/)

## `footnotes="sticky"`, `footnotes="static"`

Keeps the list of footnotes at the bottom of the window while the block is on screen, or not. It overrides the `footnotes.sticky` option for the block.

- Feature: [Footnotes](https://ewels.github.io/starlight-codeblocks/features/footnotes/)

````md
```js footnotes="sticky"
// [!ref] The port that the server listens on.
const port = 8080
const host = 'localhost'
```
````

## `startNoteNumber={N}`

Numbers the annotations or footnotes of the block from `N`, not from 1, to continue the numbers of an earlier block.

- Feature: [Annotations](https://ewels.github.io/starlight-codeblocks/features/annotations/)

````md
```js startNoteNumber={12}
const port = 8080 // [!annotate] The port that the server listens on.
```
````

## `label="<text>"`

Names a variant of a code tabs block. Its tab shows the label if the block has no title, and blocks with the same `sync` key match by label. It works only on a code block inside a `:::code-tabs` directive.

- Feature: [Code tabs](https://ewels.github.io/starlight-codeblocks/features/code-tabs/)

## `step="<text>"`

Gives the label of a step in a `<CodeWalkthrough>` component. The title bar shows the label after the title.

- Feature: [Code walkthrough](https://ewels.github.io/starlight-codeblocks/features/code-walkthrough/)

````md
```js title="server.js" step="Create the app"
import express from 'express';

const app = express();
```
````

## `runnable`

Adds a **Run code** button, which runs the code in the browser and shows the output under the block.

- Feature: [Run code](https://ewels.github.io/starlight-codeblocks/features/run-code/)

````md
```py runnable
print(sum([1, 2, 3]))
```
````

## `runnable.label="<text>"`

The text of the button of a `runnable` block. It overrides the `runnable.label` option for the block.

- Feature: [Run code](https://ewels.github.io/starlight-codeblocks/features/run-code/)

````md
```py runnable runnable.label="Try it"
print(sum([1, 2, 3]))
```
````

## `runnable.againLabel="<text>"`

The text of the button after the first run. It overrides the `runnable.againLabel` option for the block.

- Feature: [Run code](https://ewels.github.io/starlight-codeblocks/features/run-code/)

## `runnable.timeout=<ms>`

Milliseconds before a run stops. It overrides the `runnable.timeout` option for the block.

- Feature: [Run code](https://ewels.github.io/starlight-codeblocks/features/run-code/)

## `runnable.packages="<name> <name>"`

Python packages to install from Pyodide or PyPI before the code runs, separated by spaces. Use it when the package name is not the import name.

- Feature: [Run code](https://ewels.github.io/starlight-codeblocks/features/run-code/)

````md
```py runnable runnable.packages="python-slugify"
from slugify import slugify
print(slugify("Hello, World!"))
```
````

## `runnable.button="below"`, `runnable.button="title"`, `runnable.button="both"`

Puts the button under the block, in the title bar, or both. It overrides the `runnable.button` option for the block.

- Feature: [Run code](https://ewels.github.io/starlight-codeblocks/features/run-code/)

## `runnable.output="<text>"`

Output that the button prints instead of running the code, a line at a time. `\n` starts a new line. The block needs no runtime.

- Feature: [Run code](https://ewels.github.io/starlight-codeblocks/features/run-code/)

````md
```sh runnable.output="Downloading…\nDone."
nextflow run hello
```
````

## `runnable.outputDelay=<ms>`

Milliseconds between the lines of `runnable.output`. `0` prints them all at once. It overrides the `runnable.outputDelay` option for the block.

- Feature: [Run code](https://ewels.github.io/starlight-codeblocks/features/run-code/)

## `focus.style="blur"`, `focus.style="dim"`

Blurs and fades the lines outside the focus, or only fades them. It overrides the `focus.style` option for the block.

- Feature: [Focus](https://ewels.github.io/starlight-codeblocks/features/focus/)

````md
```js focus={2} focus.style="dim"
const host = 'localhost'
const port = 8080
const debug = false
```
````

## `lineStates.prefix=false`, `lineStates.prefix=true`

Shows the name of the state before each message, or not. It overrides the `lineStates.prefix` option for the block.

- Feature: [Line states](https://ewels.github.io/starlight-codeblocks/features/line-states/)

````md
```js lineStates.prefix=false
const retries = -1 // [!code error] Must be 0 or more
```
````

## `shellCopy.prompts="<text>"`

A prompt that starts a command in a terminal block, such as `shellCopy.prompts="% "`. Repeat it for more prompts. It replaces the `shellCopy.prompts` option for the block.

- Feature: [Smart shell copy](https://ewels.github.io/starlight-codeblocks/features/smart-shell-copy/)

````md
```sh shellCopy.prompts="% "
% npm run build
Built in 2.1 s
```
````

## `wordDiff.minSimilarity=<0-1>`

How similar a removed and an added line must be for word-level diff to compare them. It overrides the `wordDiff.minSimilarity` option for the block.

- Feature: [Word-level diff](https://ewels.github.io/starlight-codeblocks/features/word-level-diff/)

## `footnotes.sticky=false`, `footnotes.sticky=true`

Keeps the list of footnotes in view while the block is on screen, or not. It overrides the `footnotes.sticky` option for the block.

- Feature: [Footnotes](https://ewels.github.io/starlight-codeblocks/features/footnotes/)

## `footnotes.style="filled"`, `footnotes.style="outline"`

Draws the badges filled in the accent colour, or outlined in the magenta of the theme. It overrides the `footnotes.style` option for the block.

- Feature: [Footnotes](https://ewels.github.io/starlight-codeblocks/features/footnotes/)

````md
```js footnotes.style="filled"
// [!ref] Read from the environment.
const port = process.env.PORT
```
````

## `annotations.style="filled"`, `annotations.style="outline"`

Draws the markers filled in the accent colour, or outlined in the magenta of the theme. It overrides the `annotations.style` option for the block.

- Feature: [Annotations](https://ewels.github.io/starlight-codeblocks/features/annotations/)

````md
```js annotations.style="outline"
const port = 8080 // [!annotate] The default port.
```
````

## `expandable.lines=<N>`

The lines that the block shows before it expands, when it is expandable. It overrides the `expandable.lines` option for the block.

- Feature: [Expandable blocks](https://ewels.github.io/starlight-codeblocks/features/expandable-blocks/)

## `placeholders.storage="local"`, `placeholders.storage="session"`, `placeholders.storage="none"`

Where the browser keeps the values that readers type into the fields of the block. It overrides the `placeholders.storage` option for the block.

- Feature: [Fill-in placeholders](https://ewels.github.io/starlight-codeblocks/features/fill-in-placeholders/)

---

<!-- https://ewels.github.io/starlight-codeblocks/reference/directives/ -->

# Directives

> Every directive that the plugin reads in code comments, with an example of each.

A directive goes in a comment, in the comment syntax of the language of the block. End-of-line directives apply to the line they are on. Own-line directives take a whole line and apply to the line below it. The [comment notation](https://ewels.github.io/starlight-codeblocks/comment-notation/) page gives the rules that apply to every directive.

## `[!code highlight]`

Marks the line as highlighted, like the `mark` attribute of Expressive Code. With line states on, text after the directive shows as a message.

- Arguments: None
- Feature: [Comment notation](https://ewels.github.io/starlight-codeblocks/comment-notation/)

````md
```js
const host = 'localhost'
const port = 8080 // [!code highlight]
```
````

## `[!code ++]`

Marks the line as inserted, like the `ins` attribute of Expressive Code. With line states on, text after the directive shows as a message.

- Arguments: None
- Feature: [Comment notation](https://ewels.github.io/starlight-codeblocks/comment-notation/)

````md
```js
const host = 'localhost'
const port = 8080 // [!code ++]
```
````

## `[!code --]`

Marks the line as deleted, like the `del` attribute of Expressive Code. With line states on, text after the directive shows as a message.

- Arguments: None
- Feature: [Comment notation](https://ewels.github.io/starlight-codeblocks/comment-notation/)

````md
```js
const host = 'localhost'
const port = 8080 // [!code --]
```
````

## `[!code focus]`

Focuses the line. The other lines are blurred.

- Arguments: None
- Feature: [Focus](https://ewels.github.io/starlight-codeblocks/features/focus/)

````md
```js
const host = 'localhost'
const port = 8080 // [!code focus]
const debug = false
```
````

## `[!code error]`

Marks the line with the "Error" state. Text after the directive becomes the message.

- Arguments: Optional. The message.
- Feature: [Line states](https://ewels.github.io/starlight-codeblocks/features/line-states/)

````md
```js
const retries = -1 // [!code error] Must be 0 or more
```
````

## `[!code warning]`

Marks the line with the "Warning" state. Text after the directive becomes the message.

- Arguments: Optional. The message.
- Feature: [Line states](https://ewels.github.io/starlight-codeblocks/features/line-states/)

````md
```js
const retries = -1 // [!code warning] Must be 0 or more
```
````

## `[!code info]`

Marks the line with the "Note" state. Text after the directive becomes the message.

- Arguments: Optional. The message.
- Feature: [Line states](https://ewels.github.io/starlight-codeblocks/features/line-states/)

````md
```js
const retries = -1 // [!code info] Must be 0 or more
```
````

## `[!code success]`

Marks the line with the "Success" state. Text after the directive becomes the message.

- Arguments: Optional. The message.
- Feature: [Line states](https://ewels.github.io/starlight-codeblocks/features/line-states/)

````md
```js
const retries = -1 // [!code success] Must be 0 or more
```
````

## `[!code note]`

The same as `[!code info]`.

- Arguments: Optional. The message.
- Feature: [Line states](https://ewels.github.io/starlight-codeblocks/features/line-states/)

````md
```js
const retries = -1 // [!code note] Must be 0 or more
```
````

## `[!code warn]`

The same as `[!code warning]`.

- Arguments: Optional. The message.
- Feature: [Line states](https://ewels.github.io/starlight-codeblocks/features/line-states/)

````md
```js
const retries = -1 // [!code warn] Must be 0 or more
```
````

## `[!link]`

Links the first match of `/text/` on the line to the URL. Text after the directive shows in a card on hover and focus.

- Arguments: `/text/` to link, then the URL, then optional text for the card.
- Feature: [Code links](https://ewels.github.io/starlight-codeblocks/features/code-links/)

````md
```js
// [!link /const/ https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/const]
const port = 8080
```
````

## `[!mention]`

Tags the line with a name. A link to `#mention:<name>` in the prose highlights it.

- Arguments: A name for the line.
- Feature: [Code mentions](https://ewels.github.io/starlight-codeblocks/features/code-mentions/)

````md
```js
const base = 1 // [!mention base]
```
````

## `[!code hide]`

Hides the line behind a marker that shows it again.

- Arguments: None
- Feature: [Hidden lines](https://ewels.github.io/starlight-codeblocks/features/hidden-lines/)

````md
```js
const host = 'localhost' // [!code hide]
const port = 8080
```
````

## `[!output]`

Starts the output that the **Run code** button prints instead of running the code. `[!output end]` ends it; without it, the output goes to the end of the block. The block needs no `runnable` and no runtime.

- Arguments: Optional. `end`.
- Feature: [Run code](https://ewels.github.io/starlight-codeblocks/features/run-code/)

````md
```sh
nextflow run hello.nf
# [!output]
Hello world!
```
````

## `[!wait]`

Milliseconds to wait after this line of `[!output]`, before the next line prints.

- Arguments: Milliseconds.
- Feature: [Run code](https://ewels.github.io/starlight-codeblocks/features/run-code/)

````md
```sh
make
# [!output]
Compiling… # [!wait 2000]
Done.
```
````

## `[!callout]`

Shows the text in a bubble above the line, pointing at `/text/` on that line.

- Arguments: Optional. `/text/` to point at. Then the text of the bubble.
- Feature: [Inline callouts](https://ewels.github.io/starlight-codeblocks/features/inline-callouts/)

````md
```js
// [!callout /signal/] Stops the request.
fetch(url, { signal })
```
````

## `[!annotate]`

Adds a numbered marker after the code. Clicking it opens the text in a popover.

- Arguments: The text of the annotation.
- Feature: [Annotations](https://ewels.github.io/starlight-codeblocks/features/annotations/)

````md
```js
const port = 8080 // [!annotate] The default port.
```
````

## `[!ref]`

Adds a numbered badge to the line, and the text to a list under the block.

- Arguments: The text of the footnote.
- Feature: [Footnotes](https://ewels.github.io/starlight-codeblocks/features/footnotes/)

````md
```js
// [!ref] Read from the environment.
const port = process.env.PORT
```
````

---

<!-- https://ewels.github.io/starlight-codeblocks/reference/style-settings/ -->

# Style settings

> Every style setting of the plugin, with its defaults for dark and light themes.

Every colour and size of the plugin is an Expressive Code style setting. The settings are in groups: `codeblocks` has the settings that every feature shares, and each other group belongs to one feature. The [configuration](https://ewels.github.io/starlight-codeblocks/configuration/) page shows how to change a setting with `styleOverrides`.

Most colour defaults come from the colours of the Expressive Code theme, such as `terminal.ansiBlue`, or from another setting. The table says how. A change to `codeblocks.accent` also changes the markers, the focus ring and the link underlines. A default with two values has one for dark themes and one for light themes. A default with one value applies to both.

The colour defaults meet the contrast targets on the [accessibility](https://ewels.github.io/starlight-codeblocks/reference/accessibility/) page. If you change a colour, check its contrast against the code background of each theme.

## `codeblocks`

Shared settings, which every feature uses.

| Setting | Default | Description |
|---|---|---|
| `accent` | The `terminal.ansiBlue` colour of the theme, with 4.5:1 contrast on the code background. | Markers, numbered buttons and active states. Needs 3:1 contrast on the code background. |
| `accentHover` | `accent` mixed 45% towards `codeForeground`: lighter in dark themes, darker in light themes. | Step borders under the mouse cursor. |
| `accentForeground` | The code background, with 4.5:1 contrast on `accent`. | Text on an `accent` background. |
| `mutedForeground` | `codeForeground` mixed 30% towards the code background, with 4.5:1 contrast on it, on `popoverBackground`, on a 10% tint of `codeForeground` and on the frame tab bar. | Secondary text, such as output and marker labels. Needs 4.5:1 contrast on the code background. |
| `focusRing` | The value of `codeblocks.accent`. | The outline of a control that has keyboard focus. |
| `popoverBackground` | The code background mixed 12% towards `accent` in dark themes, and lightened in light themes. | The background of annotation notes and hover cards. |
| `popoverForeground` | `codeForeground`, with 4.5:1 contrast on `popoverBackground`. | The text of annotation notes and hover cards. |
| `popoverBorder` | `popoverBackground` mixed 30% towards `accent`. | The border of annotation notes and hover cards. |
| `popoverShadow` | `0 8px 28px rgb(10 14 24 / 0.45)` dark, `0 8px 28px rgb(12 20 36 / 0.18)` light | The shadow of annotation notes and hover cards. |
| `popoverRadius` | `6px` | The corner radius of annotation notes and hover cards. |
| `popoverMaxWidth` | `340px` | The width of annotation notes. Hover cards are 20px wider. Both stay 12px inside the window. |
| `popoverFontSize` | `0.8125rem` | The text size of annotation notes and hover cards. |

## `codeblocksFocus`

Settings of [Focus](https://ewels.github.io/starlight-codeblocks/features/focus/).

| Setting | Default | Description |
|---|---|---|
| `blur` | `1.1px` | The blur radius of lines outside the focus. |
| `opacity` | `0.48` | The opacity of lines outside the focus. |
| `transitionDuration` | `250ms` | The time that the lines take to become clear. |

## `codeblocksLineStates`

Settings of [Line states](https://ewels.github.io/starlight-codeblocks/features/line-states/).

| Setting | Default | Description |
|---|---|---|
| `barWidth` | `3px` | The width of the bar on the left edge of a line. |
| `labelFontSize` | `0.75rem` | The text size of messages. |
| `labelRadius` | `3px` | The corner radius of messages. |
| `error` | The `editorError.foreground` colour of the theme, with 3:1 contrast on the code background. | The colour of the error state. The other error settings come from it. |
| `warning` | The `editorWarning.foreground` colour of the theme, with 3:1 contrast on the code background. | The colour of the warning state. The other warning settings come from it. |
| `info` | The `editorInfo.foreground` colour of the theme, with 3:1 contrast on the code background. | The colour of the info state. The other info settings come from it. |
| `success` | The `terminal.ansiGreen` colour of the theme, with 3:1 contrast on the code background. | The colour of the success state. The other success settings come from it. |
| `<state>Background` | The state colour at 15% opacity. | The tint of a line with the state. There is one for each state, such as `errorBackground`. |
| `<state>LabelBackground` | The state colour at 20% opacity. | The background of a message. |
| `<state>LabelForeground` | The state colour mixed with the code colour, with 5:1 contrast on the message background. | The text of a message. |
| `<marker>LabelBackground` | Expressive Code's `textMarkers.<marker>BorderColor` at 20% opacity. | The background of a message after `[!code ++]`, `[!code --]` or `[!code highlight]`. There is one for each of `ins`, `del` and `mark`, such as `insLabelBackground`. |
| `<marker>LabelForeground` | The marker colour mixed with the code colour, with 5:1 contrast on the message background. | The text of a message after `[!code ++]`, `[!code --]` or `[!code highlight]`. |

## `codeblocksWordDiff`

Settings of [Word-level diff](https://ewels.github.io/starlight-codeblocks/features/word-level-diff/).

| Setting | Default | Description |
|---|---|---|
| `ins` | The `terminal.ansiGreen` colour of the theme. | The colour that the tint and the bar of added words come from. |
| `del` | The `terminal.ansiRed` colour of the theme. | The colour that the tint and the bar of removed words come from. |
| `insBackground` | `ins` at 25% opacity on dark themes, 40% on light themes. | The tint of added words. |
| `delBackground` | `del` at 25% opacity on dark themes, 40% on light themes. | The tint of removed words. |

## `codeblocksWhitespace`

Settings of [Visible whitespace](https://ewels.github.io/starlight-codeblocks/features/visible-whitespace/).

| Setting | Default | Description |
|---|---|---|
| `foreground` | `codeForeground` at 32% opacity in dark themes and 38% in light themes. | The colour of the glyphs. |

## `codeblocksBrackets`

Settings of [Colourised brackets](https://ewels.github.io/starlight-codeblocks/features/colourised-brackets/).

| Setting | Default | Description |
|---|---|---|
| `colour1` | The `editorBracketHighlight.foreground1` colour of the theme, or VS Code's default (`#ffd700` dark, `#0431fa` light`) if the theme has none, with 4.5:1 contrast on the code background. | Brackets at the first depth, and at every third depth after it. |
| `colour2` | The `editorBracketHighlight.foreground2` colour of the theme, or VS Code's default (`#da70d6` dark, `#319331` light`) if the theme has none, with 4.5:1 contrast on the code background. | Brackets at the second depth, and at every third depth after it. |
| `colour3` | The `editorBracketHighlight.foreground3` colour of the theme, or VS Code's default (`#179fff` dark, `#7b3814` light`) if the theme has none, with 4.5:1 contrast on the code background. | Brackets at the third depth, and at every third depth after it. |

## `codeblocksShellCopy`

Settings of [Smart shell copy](https://ewels.github.io/starlight-codeblocks/features/smart-shell-copy/).

| Setting | Default | Description |
|---|---|---|
| `promptForeground` | The `terminal.ansiCyan` colour of the theme, with 4.5:1 contrast on the code background. | The colour of prompts. |
| `outputForeground` | The value of `codeblocks.mutedForeground`. | The colour of output lines. |

## `codeblocksCodeLinks`

Settings of [Code links](https://ewels.github.io/starlight-codeblocks/features/code-links/).

| Setting | Default | Description |
|---|---|---|
| `underline` | The value of `codeblocks.accent`. | The underline of a link. Needs 3:1 contrast on the code background. |
| `hoverBackground` | `codeblocks.accent` at 10% opacity in dark themes and 12% in light themes. | The background of a link on hover and focus. |

## `codeblocksApiLinks`

Settings of [API auto-linking](https://ewels.github.io/starlight-codeblocks/features/api-auto-linking/).

| Setting | Default | Description |
|---|---|---|
| `underline` | `codeForeground` mixed 45% towards the code background, with 3:1 contrast on it. | The dotted underline of a link. Needs 3:1 contrast on the code background. |
| `hoverUnderline` | The value of `codeblocks.accent`. | The solid underline of a link on hover and focus. |
| `hoverBackground` | `codeblocks.accent` at 10% opacity in dark themes and 12% in light themes. | The background of a link on hover and focus. |

## `codeblocksMentions`

Settings of [Code mentions](https://ewels.github.io/starlight-codeblocks/features/code-mentions/).

| Setting | Default | Description |
|---|---|---|
| `bar` | The value of `codeblocks.accent`. | The bar on the left edge of a highlighted line. |
| `background` | `bar` at 10% opacity in dark themes and 12% in light themes. | The tint of a highlighted line. Needs 4.5:1 contrast for every syntax colour. |
| `fadeOpacity` | `0.42` | The opacity of the other lines while lines are highlighted. |

## `codeblocksPermalinks`

Settings of [Line permalinks](https://ewels.github.io/starlight-codeblocks/features/line-permalinks/).

| Setting | Default | Description |
|---|---|---|
| `foreground` | The gutter colour of the theme, with 4.5:1 contrast on the code background. | The colour of the line numbers. |
| `target` | The `terminal.ansiYellow` colour of the theme, with 3:1 contrast on the code background. | The bar on the left edge of a highlighted line. |
| `targetBackground` | `target` at 6% opacity in dark themes and 12% in light themes. | The tint of a highlighted line. |

## `codeblocksHiddenLines`

Settings of [Hidden lines](https://ewels.github.io/starlight-codeblocks/features/hidden-lines/).

| Setting | Default | Description |
|---|---|---|
| `badgeBackground` | `codeblocks.mutedForeground` at 10% opacity on the code background. | The background of the text on a marker. |
| `rule` | `codeblocks.mutedForeground` at 35% opacity. | The dashed rule of a marker. |
| `ruleHover` | The value of `codeblocks.mutedForeground`. | The dashed rule of a marker under the mouse cursor. |
| `ruleOpen` | `codeblocks.mutedForeground` at 22% opacity. | The dashed rule of a marker while its lines show. |
| `openBackground` | `codeForeground` at 4% opacity. | The tint of a hidden line that shows. |
| `openOpacity` | `0.75` | The opacity of the code of a hidden line that shows. |

## `codeblocksRunnable`

Settings of [Run code](https://ewels.github.io/starlight-codeblocks/features/run-code/).

| Setting | Default | Description |
|---|---|---|
| `outputForeground` | The `terminal.ansiGreen` colour of the theme, with 4.5:1 contrast on the code background. | Standard output. Needs 4.5:1 contrast on the code background. |
| `errorForeground` | The `terminal.ansiRed` colour of the theme, with 4.5:1 contrast on the code background. | Standard error and run errors. Needs 4.5:1 contrast on the code background. |
| `buttonBorder` | `codeForeground` mixed 50% towards the code background, with 3:1 contrast on it. | The border of the button under the block. Needs 3:1 contrast on the code background. |

## `codeblocksFileIcons`

Settings of [File icons](https://ewels.github.io/starlight-codeblocks/features/file-icons/).

| Setting | Default | Description |
|---|---|---|
| `size` | `0.85em` | The width and height of a file icon in the `plain` style. |
| `darkVariantDisplay` | `block` in dark themes, `none` in light themes. | The `display` of an icon that the set has a light variant of. |
| `lightVariantDisplay` | `none` in dark themes, `block` in light themes. | The `display` of the light variant of an icon. |
| `foreground` | `currentColor` | The colour of a file icon in the `plain` style. By default, the colour of the title. |
| `tileSize` | `1.1em` | The width and height of the square in the `tile` style. |
| `tileRadius` | `22%` | The corner radius of the square in the `tile` style. |
| `tileBackground` | The value of `codeblocks.accent`. | The colour of the square in the `tile` style. |
| `tileForeground` | `accentForeground`. | The colour of the icon on the square in the `tile` style. |

## `codeblocksWalkthrough`

Settings of [Code walkthrough](https://ewels.github.io/starlight-codeblocks/features/code-walkthrough/).

| Setting | Default | Description |
|---|---|---|
| `stepBorder` | `codeForeground` mixed 50% towards the code background, with 3:1 contrast on it. | The border of a step that is not done yet. |
| `doneForeground` | `codeblocks.accent` mixed 50% towards `codeForeground`, with 4.5:1 contrast on the code background. | The number of a step that is done. |
| `line` | The code background mixed 15% towards `codeForeground`. | The line between two steps that are not done yet. |
| `duration` | `480ms` | The time that the animation between two steps takes, in `ms` or `s`. |
| `newLineBackground` | The `terminal.ansiGreen` colour of the theme at 30% opacity. | The tint that flashes on a line that is new in a step, then fades out. |
| `newLineDuration` | `1000ms` | The time that the tint of a new line takes to fade out. |
| `themeIndex` | The index of the theme in the Expressive Code `themes` list. | The index of the theme, which the animation reads to pick token colours. Do not change it. |

## `codeblocksCallouts`

Settings of [Inline callouts](https://ewels.github.io/starlight-codeblocks/features/inline-callouts/).

| Setting | Default | Description |
|---|---|---|
| `background` | The value of `codeblocks.popoverBackground`. | The background of a bubble. |
| `foreground` | The value of `codeblocks.popoverForeground`. | The text of a bubble. |
| `border` | The value of `codeblocks.popoverBorder`. | The border and the arrow of a bubble. |
| `fontSize` | `0.925em` | The text size of a bubble. |
| `radius` | `5px` | The corner radius of a bubble. |

## `codeblocksAnnotations`

Settings of [Annotations](https://ewels.github.io/starlight-codeblocks/features/annotations/).

| Setting | Default | Description |
|---|---|---|
| `markerBackground` | The value of `codeblocks.accent`. | The background of a numbered marker. |
| `markerForeground` | The value of `codeblocks.accentForeground`. | The number on a marker. |
| `markerHoverBackground` | `markerBackground` mixed 45% towards `codeForeground`. | The background of a marker under the mouse cursor, with keyboard focus or with its note open. |
| `markerSize` | `1.55em` | The width and height of a marker. |
| `lineBackground` | `codeblocks.accent` at 10% opacity in dark themes and 12% in light themes. | The tint of the line of an open annotation. Needs 4.5:1 contrast for every syntax colour. |
| `outlineAccent` | The `terminal.ansiMagenta` colour of the theme, with 4.5:1 contrast on the code background. | With `style: 'outline'`: the border of a marker, the bar of a lit line and the background of an active marker. |
| `outlineNumberForeground` | `outlineAccent` mixed 30% towards `codeForeground`, with 4.5:1 contrast on the code background and on `outlineLineBackground`. | With `style: 'outline'`: the numbers. Needs 4.5:1 contrast on the code background. |
| `outlineActiveForeground` | The code background, with 4.5:1 contrast on `outlineAccent`. | With `style: 'outline'`: the number of an active marker, on an `outlineAccent` background. |
| `outlineLineBackground` | `outlineAccent` at 10% opacity, on the code background. | With `style: 'outline'`: the tint of a lit line. Needs 4.5:1 contrast for every syntax colour. |

## `codeblocksFootnotes`

Settings of [Footnotes](https://ewels.github.io/starlight-codeblocks/features/footnotes/).

| Setting | Default | Description |
|---|---|---|
| `accent` | The value of `codeblocks.accent`. | The background of a badge and the bar of a selected line. |
| `numberForeground` | `accent` mixed 30% towards `codeForeground`, with 4.5:1 contrast on the code background and on `lineBackground`. | List numbers. Needs 4.5:1 contrast on the code background. |
| `activeForeground` | The code background, with 4.5:1 contrast on `accent`. | The number on a badge, on an `accent` background. |
| `activeBackground` | `accent` mixed 45% towards `codeForeground`. | The background of a badge under the mouse cursor, with keyboard focus or on a selected line. |
| `lineBackground` | `accent` at 10% opacity in dark themes and 12% in light themes, on the code background. | The tint of a selected line. Needs 4.5:1 contrast for every syntax colour. |
| `outlineAccent` | The `terminal.ansiMagenta` colour of the theme, with 4.5:1 contrast on the code background. | With `style: 'outline'`: the border of a badge, the bar of a lit line and the background of an active badge. |
| `outlineNumberForeground` | `outlineAccent` mixed 30% towards `codeForeground`, with 4.5:1 contrast on the code background and on `outlineLineBackground`. | With `style: 'outline'`: the numbers. Needs 4.5:1 contrast on the code background. |
| `outlineActiveForeground` | The code background, with 4.5:1 contrast on `outlineAccent`. | With `style: 'outline'`: the number of an active badge, on an `outlineAccent` background. |
| `outlineLineBackground` | `outlineAccent` at 10% opacity, on the code background. | With `style: 'outline'`: the tint of a lit line. Needs 4.5:1 contrast for every syntax colour. |
| `stickyShadow` | `0 -8px 16px rgb(10 14 24 / 0.35)` dark, `0 -6px 14px rgb(12 20 36 / 0.1)` light | The shadow above a sticky list of footnotes. |

---

<!-- https://ewels.github.io/starlight-codeblocks/reference/expressive-code-plugins/ -->

# Expressive Code plugins

> The Expressive Code plugins that the package exports, for sites that configure Expressive Code themselves.

`codeblocks()` adds every feature to Starlight for you. Behind it, each feature is an Expressive Code plugin. The `starlight-codeblocks/expressive-code` subpath exports these plugins, and a preset that returns all of them. A site that uses Expressive Code without Starlight, or with its own `plugins` list in `ec.config.mjs`, uses them there.

## The preset

`pluginCodeblocks(options)` returns every plugin, in the correct order, with the options of [`codeblocks()`](https://ewels.github.io/starlight-codeblocks/reference/options/). Use the preset unless you have a reason to add plugins one by one. To leave a feature out, set its option to `false`:

```js title="ec.config.mjs"
import { pluginCodeblocks } from 'starlight-codeblocks/expressive-code';

export default {
  plugins: [pluginCodeblocks({ annotations: false, runnable: false })],
};
```

On a Starlight site with `codeblocks()`, call `pluginCodeblocks()` with no argument. It then reads the options that you gave to `codeblocks()`.

On a site without `codeblocks()`, give the preset Astro's `base` as the second argument, if the site has one. Links in code that start with `/` then get it in front:

```js title="ec.config.mjs"
plugins: [pluginCodeblocks({}, { base: '/docs' })],
```

## Plugins

Each plugin takes the settings of its option, as the [options reference](https://ewels.github.io/starlight-codeblocks/reference/options/) lists them. The table gives the plugins in the order that the preset adds them.

| Plugin | Option | Feature |
|---|---|---|
| `pluginCore()` | none | Shared style settings and styles |
| `pluginNotation(settings)` | `notation` | [Comment notation](https://ewels.github.io/starlight-codeblocks/comment-notation/) |
| `pluginFocus(settings)` | `focus` | [Focus](https://ewels.github.io/starlight-codeblocks/features/focus/) |
| `pluginLineStates(settings)` | `lineStates` | [Line states](https://ewels.github.io/starlight-codeblocks/features/line-states/) |
| `pluginWordDiff(settings)` | `wordDiff` | [Word-level diff](https://ewels.github.io/starlight-codeblocks/features/word-level-diff/) |
| `pluginWhitespace()` | `whitespace` | [Visible whitespace](https://ewels.github.io/starlight-codeblocks/features/visible-whitespace/) |
| `pluginBrackets(settings)` | `brackets` | [Colourised brackets](https://ewels.github.io/starlight-codeblocks/features/colourised-brackets/) |
| `pluginSwatches(settings)` | `swatches` | [Colour swatches](https://ewels.github.io/starlight-codeblocks/features/colour-swatches/) |
| `pluginShellCopy(settings)` | `shellCopy` | [Smart shell copy](https://ewels.github.io/starlight-codeblocks/features/smart-shell-copy/) |
| `pluginCodeLinks({ base })` | `codeLinks` | [Code links](https://ewels.github.io/starlight-codeblocks/features/code-links/) |
| `pluginApiLinks({ adapters, base })` | `apiLinks` | [API auto-linking](https://ewels.github.io/starlight-codeblocks/features/api-auto-linking/) |
| `pluginPlaceholders(settings)` | `placeholders` | [Fill-in placeholders](https://ewels.github.io/starlight-codeblocks/features/fill-in-placeholders/) |
| `pluginMentions()` | `mentions` | [Code mentions](https://ewels.github.io/starlight-codeblocks/features/code-mentions/) |
| `pluginPermalinks()` | `permalinks` | [Line permalinks](https://ewels.github.io/starlight-codeblocks/features/line-permalinks/) |
| `pluginHiddenLines()` | `hiddenLines` | [Hidden lines](https://ewels.github.io/starlight-codeblocks/features/hidden-lines/) |
| `pluginExpandable(settings)` | `expandable` | [Expandable blocks](https://ewels.github.io/starlight-codeblocks/features/expandable-blocks/) |
| `pluginPlayground(playgrounds)` | `playgrounds` | [Open in playground](https://ewels.github.io/starlight-codeblocks/features/open-in-playground/) |
| `pluginRunnable(settings)` | `runnable` | [Run code](https://ewels.github.io/starlight-codeblocks/features/run-code/) |
| `pluginFileIcons(settings)` | `fileIcons` | [File icons](https://ewels.github.io/starlight-codeblocks/features/file-icons/) |
| `pluginCodeTabs(fileIcons)` | `codeTabs` | [Code tabs](https://ewels.github.io/starlight-codeblocks/features/code-tabs/) |
| `pluginWalkthrough()` | `walkthrough` | [Code walkthrough](https://ewels.github.io/starlight-codeblocks/features/code-walkthrough/) |
| `pluginCallouts()` | `callouts` | [Inline callouts](https://ewels.github.io/starlight-codeblocks/features/inline-callouts/) |
| `pluginAnnotations()` | `annotations` | [Annotations](https://ewels.github.io/starlight-codeblocks/features/annotations/) and [side annotations](https://ewels.github.io/starlight-codeblocks/features/side-annotations/) |
| `pluginFootnotes(settings)` | `footnotes` | [Footnotes](https://ewels.github.io/starlight-codeblocks/features/footnotes/) |

`pluginCodeLinks()` and `pluginApiLinks()` take the `base` of the Astro site, for links that start with `/`. With `codeblocks()`, they read it from Astro. `pluginApiLinks()` has no default adapters. Give it the adapters from `starlight-codeblocks/adapters/python` and `starlight-codeblocks/adapters/nextflow`, or your own.

## Rules for single plugins

If you add plugins one by one, follow these rules:

1. Add `pluginCore()` first. Every other plugin uses its style settings.
2. Add `pluginNotation()` second, if any plugin after it reads directives.
3. Add the other plugins in the order of the table.

The order matters. For example, `pluginPlayground()` sends the copied text, so it must come after `pluginShellCopy()` and `pluginPlaceholders()`, which change that text. `pluginCallouts()` must come after `pluginHiddenLines()`, which rebuilds the lines of the block.

## Without Starlight

Some features need more than an Expressive Code plugin. Without `codeblocks()`, these parts are not there:

- The `:::code-tabs` directive and [inline code highlighting](https://ewels.github.io/starlight-codeblocks/features/inline-code-highlighting/) need the Markdown plugin that `codeblocks()` adds.
- The `<CodeWalkthrough>` and `<Scrollycoding>` components need Starlight.
- `runnable.runtimes` values are URLs that the browser imports as they are, because `codeblocks()` is not there to bundle the runtime modules. There are no built-in runtimes. Map each language to the URL of its runtime module, such as `https://cdn.jsdelivr.net/npm/starlight-codeblocks/dist/runtimes/pyodide.mjs`. The JavaScript and TypeScript runtimes are `javascript.mjs` and `typescript.mjs` in the same folder.
- Expressive Code turns each tab into spaces, because `codeblocks()` is not there to set `tabWidth: 0`. Set `tabWidth: 0` in `ec.config.mjs`, so that tabs reach the code blocks unchanged.

The client scripts of interactive features load inline on each page that needs them, so the features work without a change to the build.

---

<!-- https://ewels.github.io/starlight-codeblocks/reference/plugin-compatibility/ -->

# Plugin compatibility

> Configure the plugin next to other Starlight plugins, themes, Expressive Code plugins and Markdown processors.

A Starlight site often has more than one plugin. [Most plugins](https://ewels.github.io/starlight-codeblocks/reference/plugin-compatibility/#tested-plugins) work next to this one with no change. Some need a setting, or a place in the list of plugins. This page gives the set-up for each of them.

## Plugin order

List `codeblocks()` before any plugin or theme that sets the `expressiveCode` option of Starlight. For example, [`starlight-theme-nova`](https://github.com/ocavue/starlight-theme-nova) turns Expressive Code off unless the site sets the option:

```js title="astro.config.mjs"
starlight({
  plugins: [codeblocks(), starlightThemeNova()],
}),
```

If a theme must come first, set `expressiveCode: {}` in the Starlight config. The plugin stops the build with a message if Expressive Code is off.

## Expressive Code plugins in ec.config.mjs

If `ec.config.mjs` has a `plugins` list, the plugin cannot add its own Expressive Code plugins. Add `pluginCodeblocks()` to the list:

```js title="ec.config.mjs"
import { pluginLineNumbers } from '@expressive-code/plugin-line-numbers';
import { pluginCodeblocks } from 'starlight-codeblocks/expressive-code';

export default {
  plugins: [pluginLineNumbers(), pluginCodeblocks()],
};
```

`pluginCodeblocks()` can go before or after most other plugins. The features find each line wherever another plugin puts it, such as inside a collapsed section. `pluginCollapsibleSections()` must come before `pluginCodeblocks()`, and the build stops with a message if it does not.

[`expressive-code-twoslash`](https://twoslash.studiocms.dev) removes some lines of a block, such as the last lines after a `^?` query. A directive on a line that it removes has no effect, and the build logs a warning. Put the directive on a line that stays.

## Specific plugin guidance

### starlight-links-validator

[`starlight-links-validator`](https://github.com/HiDeoo/starlight-links-validator) reports links to [code mentions](https://ewels.github.io/starlight-codeblocks/features/code-mentions/) and [line permalinks](https://ewels.github.io/starlight-codeblocks/features/line-permalinks/) as broken. It cannot see those ids, because they exist only in the rendered code. Give it the `linksValidatorExclude` function from this plugin:

```js title="astro.config.mjs"
import codeblocks, { linksValidatorExclude } from 'starlight-codeblocks';
import starlightLinksValidator from 'starlight-links-validator';

starlight({
  plugins: [codeblocks(), starlightLinksValidator({ exclude: linksValidatorExclude })],
}),
```

The function skips `#mention:` links and links to the `id` of a code block, alone or with a line, such as `#cfg-L2`. The validator still checks every other link.

### starlight-llms-txt

[`starlight-llms-txt`](https://delucis.github.io/starlight-llms-txt/) makes its text from the HTML of each page. The plugin adds labels, buttons and notes to a block, and the text of those goes into the code. Every one of these elements has the class `scb-deco`. Remove them with one selector:

```js title="astro.config.mjs"
starlightLlmsTxt({
  customSelectors: { all: ['.scb-deco'] },
}),
```

The code in `llms-full.txt` is then the code that the copy button copies. Placeholder fields keep their text. Annotations, callouts and footnote badges go. Notes that show under a block, such as the list of footnotes, stay as a plain numbered list.

Pagefind needs no set-up. It does not index these elements, because each one has `data-pagefind-ignore`.

### Page actions and raw Markdown

[`starlight-page-actions`](https://starlight-page-actions.dlcastillop.com), [`starlight-page-context-action`](https://github.com/babblebey/starlight-page-context-action) and [`starlight-md-txt`](https://github.com/max-ostapenko/starlight-md-txt) give readers the Markdown source of a page. That source keeps the attributes on the first line of each code block and the directives in the code comments, as the author wrote them. The plugin does not change it. Most readers of the source, such as AI assistants, can read directives, because they are comments.

### starlight-versions and starlight-md-txt

[`starlight-versions`](https://github.com/HiDeoo/starlight-versions) and [`starlight-md-txt`](https://github.com/max-ostapenko/starlight-md-txt) read `.md` files as MDX. MDX reads a `{:js}` after the closing backtick of inline code as a JavaScript expression, and the build fails. Put the suffix of [inline code highlighting](https://ewels.github.io/starlight-codeblocks/features/inline-code-highlighting/) inside the backticks. That form is valid in `.md` and `.mdx` files.

### Markdoc

In Markdoc files (`.mdoc`), with [`@astrojs/markdoc`](https://docs.astro.build/en/guides/integrations-guide/markdoc/) and [`@astrojs/starlight-markdoc`](https://github.com/withastro/starlight/tree/main/packages/markdoc), the features inside a code block work. Markdoc does not take attributes on the fence line. Put them in a `meta` attribute of a Markdoc tag after the language:

````md title="src/content/docs/example.mdoc"
```js {% title="app.js" meta="focus={2}" %}
const app = express();
app.use(express.json());
app.listen(3000);
```
````

Directives in code comments work as in Markdown. Markdoc has its own parser, so the features that read the text outside a block do not run in `.mdoc` files:

- code tabs
- inline code highlighting
- the check of code mention links
- the check for duplicate block ids

Use `.md` or `.mdx` files for pages that need them.

## The unified() processor

Astro 7 uses Sätteri for Markdown. Some plugins need Astro's `unified()` processor, because they add remark plugins, such as [`starlight-markdown-blocks`](https://delucis.github.io/starlight-markdown-blocks/). Every feature works with `unified()` too. The plugin adds its own remark plugin when the site uses it:

```js title="astro.config.mjs"
import { unified } from '@astrojs/markdown-remark';

export default defineConfig({
  markdown: { processor: unified() },
  integrations: [starlight({ plugins: [codeblocks()] })],
});
```

Starlight adds [`remark-directive`](https://github.com/remarkjs/remark-directive) for `unified()`, which code tabs need. Sätteri stays the default of Astro 7, so keep it unless another plugin needs `unified()`.

## Tested plugins

These plugins were tested on a site with every feature of this plugin on. They need no change:

- Pages and content: [`starlight-openapi`](https://github.com/HiDeoo/starlight-openapi), [`starlight-typedoc`](https://github.com/HiDeoo/starlight-typedoc), [`starlight-pydocs`](https://ewels.github.io/starlight-pydocs), [`starlight-blog`](https://github.com/HiDeoo/starlight-blog), [`starlight-tags`](https://github.com/frostybee/starlight-tags), [`starlight-quiz`](https://ewels.github.io/starlight-quiz), [`starlight-videos`](https://github.com/HiDeoo/starlight-videos), [`astro-mermaid`](https://github.com/joesaby/astro-mermaid), [`starlight-github-alerts`](https://github.com/HiDeoo/starlight-github-alerts), [`starlight-kbd`](https://github.com/HiDeoo/starlight-kbd) and [`starlight-heading-badges`](https://github.com/HiDeoo/starlight-heading-badges).
- Navigation and search: [`starlight-sidebar-topics`](https://github.com/HiDeoo/starlight-sidebar-topics), [`starlight-auto-sidebar`](https://github.com/HiDeoo/starlight-auto-sidebar), [`starlight-site-graph`](https://github.com/fevol/starlight-site-graph), [`starlight-scroll-to-top`](https://github.com/frostybee/starlight-scroll-to-top), [`@astrojs/starlight-docsearch`](https://starlight.astro.build/guides/site-search/#algolia-docsearch) and [`starlight-telescope`](https://github.com/frostybee/starlight-telescope).
- Layout: [`starlight-image-zoom`](https://github.com/HiDeoo/starlight-image-zoom), [`starlight-fullview-mode`](https://windmillcode.github.io/starlight-fullview-mode), [`starlight-view-modes`](https://starlight-view-modes.netlify.app), [`starlight-ui-tweaks`](https://starlight-ui-tweaks.dlcastillop.com), [`starlight-announcement`](https://github.com/frostybee/starlight-announcement), [`starlight-package-managers`](https://github.com/HiDeoo/starlight-package-managers) and [`@astrojs/starlight-tailwind`](https://starlight.astro.build/guides/css-and-tailwind/#tailwind-css) with Tailwind 4.
- Themes: [`starlight-theme-rapide`](https://github.com/HiDeoo/starlight-theme-rapide), [`starlight-theme-flexoki`](https://delucis.github.io/starlight-theme-flexoki/), [`starlight-theme-next`](https://starlight-theme-next.netlify.app), [`starlight-theme-vintage`](https://github.com/HiDeoo/starlight-theme-vintage), [`starlight-theme-black`](https://github.com/adrian-ub/starlight-theme-black), [`starlight-theme-galaxy`](https://frostybee.github.io/starlight-theme-galaxy) and [`@catppuccin/starlight`](https://starlight.catppuccin.com/).
- Expressive Code plugins: [`@expressive-code/plugin-line-numbers`](https://expressive-code.com/plugins/line-numbers/), [`@expressive-code/plugin-collapsible-sections`](https://expressive-code.com/plugins/collapsible-sections/), [`expressive-code-color-chips`](https://delucis.github.io/expressive-code-color-chips/) and [`expressive-code-links`](https://github.com/towc/expressive-code-links).
- Full screen code blocks: [`starlight-codeblock-fullscreen`](https://github.com/frostybee/starlight-codeblock-fullscreen). The controls of every feature work in its full screen copy of a block.

## Related

- [Configuration](https://ewels.github.io/starlight-codeblocks/configuration/): turn features on and off, and configure them.
- [Expressive Code plugins](https://ewels.github.io/starlight-codeblocks/reference/expressive-code-plugins/): use the features one at a time in `ec.config.mjs`.

---

<!-- https://ewels.github.io/starlight-codeblocks/reference/themes/ -->

# Themes

> See the features in eight Expressive Code themes, and learn how the plugin takes its colours from the theme of your site.

Starlight shows code blocks in the Night Owl theme, with a dark and a light version. You can use any theme that Expressive Code knows instead. The plugin takes its colours from the theme, so markers, messages and notes match the syntax colours of the block.

Each example on this page shows the same code block in eight themes. The examples combine several features, so that one block shows many of the colours of the plugin.

## Notes and line states

This block has an annotation, a footnote and a warning. The marker of the annotation and the bar of the warning take the blue and the warning colour of each theme:

````md
```py title="app.py"
from flask import Flask

app = Flask(__name__)  # [!annotate] Creates the application object.

# [!ref] Runs this function for `GET /health`.
@app.get("/health")
def health():
    return {"ok": True}  # [!code warning] Always 200
```
````

## Changes

Word-level diff tints the words that changed with the green and the red of the terminal colours of each theme:

````md
```diff lang="js" title="client.js"
-const timeout = 5000;
+const timeout = options.timeout ?? 5000;
 const client = createClient({
-  retries: 3,
+  retries: options.retries,
 });
```
````

## Terminal commands

Smart shell copy colours the `$` at the start of each command with the terminal cyan of each theme, and mutes the output lines:

````md
```sh
$ npm install starlight-codeblocks
added 1 package in 2s
$ npx astro build
```
````

## Choose the themes of your site

Give the names of a dark and a light theme in the `expressiveCode` option of Starlight. The theme menu of Starlight switches between them:

```js title="astro.config.mjs" {3}
starlight({
  expressiveCode: {
    themes: ['dracula', 'solarized-light'],
  },
  plugins: [codeblocks()],
});
```

The names are the names of the themes that Shiki includes, such as `github-dark` or `catppuccin-latte`. The [Expressive Code docs](https://expressive-code.com/guides/themes/) list them, and explain how to load a theme from a JSON file.

## Change a colour

The plugin takes each of its colours from a colour of the theme. For example, the accent of Min Light is grey because its terminal blue is grey. The plugin then makes each colour lighter or darker, until it has its contrast target on the code background of that theme. The [accessibility](https://ewels.github.io/starlight-codeblocks/reference/accessibility/) page gives the targets. If a theme has no colour for a part, the plugin uses the default colour of VS Code.

<details>
<summary>Theme colour of each plugin colour</summary>

| Plugin colour | Theme colour |
|---|---|
| Markers, focus rings and active states (`codeblocks.accent`) | `terminal.ansiBlue` |
| Error, warning and info states | `editorError.foreground`, `editorWarning.foreground`, `editorInfo.foreground` |
| Colourised brackets | `editorBracketHighlight.foreground1` to `3` |
| Word-level diff, Run output and errors | `terminal.ansiGreen`, `terminal.ansiRed` |
| The `$` of shell commands | `terminal.ansiCyan` |
| Permalink target | `terminal.ansiYellow` |
| Muted text, popovers and borders | Mixes of the code colour and the code background |

</details>

To change a colour for every theme, set its style setting in the `styleOverrides` option of Expressive Code:

```js title="astro.config.mjs" {3-5}
starlight({
  expressiveCode: {
    themes: ['min-light', 'github-dark'],
    styleOverrides: { codeblocks: { accent: ['#58a6ff', '#0969da'] } },
  },
  plugins: [codeblocks()],
});
```

Each key in `styleOverrides` is a group of settings:

- The `codeblocks` group has the settings that all features share, such as `accent`, `mutedForeground` and `popoverBackground`.
- Each feature has its own group. The name of the group is `codeblocks` and then the name of the feature, such as `codeblocksShellCopy` for smart shell copy.

For example, the colour of the `$` in shell commands is the `promptForeground` setting in the `codeblocksShellCopy` group:

```js
styleOverrides: { codeblocksShellCopy: { promptForeground: ['#56d4dd', '#1b7c83'] } },
```

A pair gives the dark value, then the light value. The plugin does not correct the contrast of a colour that you set. Check it against the code background of each theme.

- [Style settings](https://ewels.github.io/starlight-codeblocks/reference/style-settings/): See every style setting, its group, and its default in dark and light themes.

## Limitations

- Min Light has a grey terminal blue, so its accent is grey. Colour is never the only mark of a feature, so the blocks still work.
- Custom line states keep the colours that you give in the `lineStates` option.
- If a theme sets the code background to a CSS variable, the plugin cannot read it. It measures the contrast against the background of the theme instead.

---

<!-- https://ewels.github.io/starlight-codeblocks/reference/accessibility/ -->

# Accessibility

> What each feature does for keyboard users, screen reader users and readers who ask for reduced motion, and the contrast that the default styles meet.

The features meet WCAG 2.2 AA in the light and the dark themes of Starlight, with the default style settings. The known exceptions are the fade of four features and the dimmed open lines of hidden lines, which the [contrast](#contrast) section explains. Line states with their names turned off are one more. This page lists what each feature does for readers who use a keyboard or a screen reader, or who ask for reduced motion. It also says where colour is part of the meaning, and what else carries that meaning.

## Rules for every feature

These rules apply to all features, so the sections below do not repeat them:

- Every control is a native `button`, `a`, `input` or `select` element. You can reach it with the Tab key and use it with Enter or Space.
- Every control shows a focus ring in `codeblocks.focusRing` when it has keyboard focus. The ring has 3:1 contrast or more on the code background. The code area of a block, which takes focus when it scrolls, uses the same ring.
- In forced colours mode, markers keep their outline and the current step keeps its highlight.
- A block with controls in its title bar has the title as its accessible name. Without a title, the name is "Code block". The labels of the controls are not part of the name.
- A change that happens on hover over a control also happens on keyboard focus, or when the reader clicks the control.
- Escape closes an open popover or hover card.
- When the reader's system asks for reduced motion, every transition and animation of the plugin stops, and so does the transition of the copy button. The change still happens, at once, and pages jump instead of scrolling smoothly.
- The copy button and a manual selection give the code only. Messages, markers, notes, line numbers and glyphs are not part of the copied text.
- The copy button includes [hidden lines](https://ewels.github.io/starlight-codeblocks/features/hidden-lines/). A manual selection includes only the hidden lines that are open.
- Code stays in the page for screen readers, also when it is blurred or faded. [Hidden lines](https://ewels.github.io/starlight-codeblocks/features/hidden-lines/) and the collapsed lines of [expandable blocks](https://ewels.github.io/starlight-codeblocks/features/expandable-blocks/) are the exceptions: screen readers do not read them until the reader opens them.
- Controls do not print. An expandable block prints in full, and hidden lines stay hidden.

## Contrast

The default colours come from the Expressive Code theme. The plugin makes each one lighter or darker until it meets its target on the code background of that theme. Unit tests check the targets with the default themes of Starlight and Expressive Code. They also check Dracula, Solarized Light, One Dark Pro, Catppuccin Latte, Nord and Min Light.

| Element | Target |
|---|---|
| Text, such as messages, output, notes, line numbers and prompts | 4.5:1 |
| Code on the tint of a line or a changed word | 4.5:1 |
| Messages of line states | 5:1 |
| Bars, underlines, markers, badges and focus rings | 3:1 |

Four features fade lines or text on purpose: [focus](https://ewels.github.io/starlight-codeblocks/features/focus/), [code mentions](https://ewels.github.io/starlight-codeblocks/features/code-mentions/), [scrollycoding](https://ewels.github.io/starlight-codeblocks/features/scrollycoding/) and [expandable blocks](https://ewels.github.io/starlight-codeblocks/features/expandable-blocks/). A collapsed expandable block fades its last visible lines. While it is faded, the text is below 4.5:1. This is a known exception to WCAG 1.4.3, and the plugin limits it in these ways:

- The faded text stays in the page. Screen readers read it the same as the other text, and a copy gives it in full.
- The reader can always bring the text back to full contrast. For focus, hover over the block or move keyboard focus into it. For code mentions, the fade lasts only while a mention link has hover or focus. For scrollycoding, scroll to the step, or move focus into the sticky block. For expandable blocks, click the button under the code.
- The fade does not hide information. It shows where to look.

Some tints are on known lines, such as a line state or a word-level diff. There, the plugin changes each syntax colour that falls below 4.5:1 on the tint. Expressive Code does the same for its own marked lines. A tint that any line can get, such as a permalink target, is light enough for every syntax colour of the default themes.

[Hidden lines](https://ewels.github.io/starlight-codeblocks/features/hidden-lines/) that show are dimmed to 75% opacity, so some syntax colours fall below 4.5:1, but stay at 3:1 or more.

If your site must meet 4.5:1 in every state, set `codeblocksFocus.opacity`, `codeblocksMentions.fadeOpacity` and `codeblocksHiddenLines.openOpacity` to `1` and `codeblocksFocus.blur` to `0px` in the style settings. Do not use scrollycoding or expandable blocks on that site.

If you change a colour in the [style settings](https://ewels.github.io/starlight-codeblocks/reference/style-settings/), check its contrast in both themes.

## Comment notation

The plugin reads directives at build time and removes them from the page. Readers get the result of each directive, as the sections for each feature describe.

## Explain code

### Annotations

- Each marker is a button with the label "Annotation N". Screen readers read the note after its marker. The number at the start of the note is hidden from screen readers, so they do not read it twice.
- The note fades in and out. With reduced motion, it opens and closes at once.
- Escape, or a click outside the markers and the notes, closes every open note.
- A hover note stays while the mouse cursor is on the marker or the note, and Escape closes it. Touch screens and the keyboard open a note only on a tap, or on Enter on the marker.
- When the page prints, the notes print as a numbered list under the block.

### Footnotes

- Each badge is a link with the label "Footnote N", and its note is its accessible description. The number in front of each note is a link back to its line, with the label "Footnote N, for line L".
- A badge moves keyboard focus to its note, and the number moves focus back to the badge.
- A badge that gets keyboard focus under a sticky list scrolls into view above the list.
- The number links are 24 by 24 pixels or more.
- A selected line and its note get a bar as well as a tint, so the highlight does not rely on colour.
- Hover highlights only. It shows nothing that a click does not show. A tap, or Enter on the keyboard, works as a click.
- Under reduced motion, the page jumps to the note or the line.

### Inline callouts

- The bubble has the `note` role. Screen readers read it before its line.
- A bubble has no animation and no control.

### Side annotations

- Keyboard focus on a note highlights its line, the same as hover. The note shows a focus ring.
- The numbers on the lines are hidden from screen readers. Screen readers read the notes as a list after the code.

### Scrollycoding

- Screen readers read the steps in order, then the code block. On a narrow screen, each step has its own copy of the block. When the code changes between steps, the step where each version starts also has that version as text for screen readers.
- The mouse cursor does not clear the focus of the sticky block. Move keyboard focus into the block to make every line sharp.
- Under reduced motion, the focus and the fade of the steps change at once.

### Code walkthrough

- The numbered steps and the **Previous** and **Next** buttons under the block are buttons. The left and right arrow keys go to the previous and the next step when a numbered step has focus.
- The row under the block also shows the step count in text, such as "Step 2 of 3".
- Screen readers announce the number and the label of the new step. The current step has `aria-current`.
- The green tint on new lines is a visual extra only. It fades out, and it gives no information that the code does not give.
- Under reduced motion, the code changes without the animation, and new lines get no tint.

## Draw attention

### Focus

- The code area takes keyboard focus when the block has focused lines. Focus in the code area makes every line clear.
- Screen readers read every line, because the blurred lines stay in the page.
- The blur and the fade are the only differences between focused lines and other lines. They show where to look, and hide no information.

### Line states

- Each state line has a tint and a bar on the left edge. A message starts with the name of the state in bold, so colour is not the only mark.
- With `lineStates.prefix` off, or `lineStates.prefix=false` on a block, the names do not show on screen. The tint is then the only visible mark of the state, which is an exception to WCAG 1.4.1. Screen readers still hear the name.
- Screen readers hear the name of the state before the line, for example "Error:", and then the message after the code.

### Code mentions

- Keyboard focus on a mention link highlights its lines, the same as hover.
- Screen readers read the tagged lines as the description of the link.
- Under reduced motion, the fade and the scroll happen at once.

## Make code easier to read

### Hidden lines

- Each marker is a button with `aria-expanded`. The title bar button also has `aria-expanded`, and its label changes from **Show** to **Hide**. Both have `aria-controls`, which names the lines they show.
- The marker text gives the number of lines, such as "3 hidden lines", so readers know what the button opens.
- Hidden lines that show are dimmed to 75% opacity. Some syntax colours then have less than 4.5:1 contrast, but at least 3:1. To turn the dimming off, set the `codeblocksHiddenLines.openOpacity` style setting to `1`.

### Expandable blocks

- The button under the code says how many lines it shows, such as "Show all 24 lines". It has `aria-expanded`.
- The collapsed lines use `hidden="until-found"`, so Find in the browser still finds text in them, and the block expands to show the match.
- The last lines that show fade into the background while the block is collapsed, so they are below 4.5:1. The [contrast](#contrast) section explains this exception.
- Screen readers do not read the collapsed lines. They read the lines that show, then the button. When the reader clicks the button, or Find in the browser opens the block, all the lines are read.

### Visible whitespace

The glyphs are hidden from screen readers, which read the same code as in a block without the attribute.

### Colourised brackets

- The colours are a reading aid. The brackets themselves stay in the code, so readers who cannot tell the colours apart lose no information.
- Hover over a bracket to outline it and its partner, which shows the pair by shape.
- Brackets cannot take keyboard focus. With caret browsing (F7 in most browsers), move the caret onto a bracket to get the same outline.

### Inline code highlighting

The highlighted code is a normal `code` element, with the same characters as before. The token colours have the same contrast correction as the code blocks.

### Word-level diff

- The line markers of Expressive Code show which lines are removed and which are added. The changed words get a stronger tint on top of them.
- A changed word has a bar under it, and a removed word also has a line through it. Colour is not the only mark.
- Each changed word has the `insertion` or the `deletion` role. Screen readers that support these roles announce the change. All screen readers get the removed line and the added line in full, so a reader can compare the two.

## Link code

### Code links

- A link is a normal link with an underline, so it does not rely on colour. It keeps its syntax colours.
- Readers reach the link with the Tab key.
- A link with a description shows the API links card on hover and on focus. Screen readers get the same text from the link's `aria-description`.

### API auto-linking

- A link has a dotted underline. On hover and on focus, the underline is solid.
- The hover card opens at once on keyboard focus. Escape closes it.
- Screen readers get the text of the card as the description of the link.

### Line permalinks

- The line numbers are links. Enter highlights a line, and Shift with Enter highlights a range.
- Screen readers announce each number as "Link to line N". Highlighted numbers have `aria-current`.
- A highlighted line gets a bar as well as a tint.

## Adapt to the reader

### Code tabs

- The tabs are a tab list with the accessible name "Variant". Only the selected tab is in the tab order. The arrow keys, <kbd>Home</kbd> and <kbd>End</kbd> select a tab.
- The menu is a native `select` element with the accessible name "Variant".
- Keyboard focus moves to the same tab or the menu in the variant that shows.
- The language icon in the menu is decorative and hidden from screen readers. The menu entries name the variants.

### Fill-in placeholders

- Each field is a native `input`. Its accessible name is its placeholder text.
- A field prints as its text, without the border.
- Escape in a field clears its value.

## Copy and run

### Smart shell copy

- Screen readers read the prompts, the commands and the output as they are on the page.
- The **Copy commands** button is a native `button` with a visible label that says what it copies. After a copy, a live region announces "Copied".
- The copy button copies the whole block, as in every other block.
- Output lines are muted and have no syntax colours. Their position after a command also marks them as output.
- In a Python session, the `>>>` and `...` prompts stay on the page and are read with the commands.

### Open in playground

- The button is a link, or a form button for playgrounds that take a post.
- Screen readers announce "opens in a new tab" after the label.

### Run code

- The **Run code** button keeps keyboard focus during a run, so readers can run the code again with Enter or Space. While code runs, the button has `aria-disabled`.
- The output panel is a polite live region. Screen readers announce the loading message and the output when they change.
- Standard error has a bar at its start and a hidden "Error:" prefix for screen readers, as well as its colour.
- The **Run code** button does not print.