---
title: "Configuration"
description: "Turn features off, change their settings and change their colours with one options object."
url: "https://ewels.github.io/starlight-codeblocks/configuration/"
markdown: "https://ewels.github.io/starlight-codeblocks/configuration.md"
section: "Start here"
site: "starlight-codeblocks documentation"
context: "This page is from the documentation of 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."
index: "https://ewels.github.io/starlight-codeblocks/llms.txt"
---

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