Configuration

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:

astro.config.mjs

starlight({
  title: 'My docs',
  plugins: [
    codeblocks({
      focus: { style: 'dim' },
      expandable: { lines: 20 },
      runnable: false,
    }),
  ],
});

Options referenceSee 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:

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

Error: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 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:

astro.config.mjs

starlight({
  expressiveCode: {
    styleOverrides: {
      codeblocks: {
        accent: ['#c792ea', '#7c3aed'],
        popoverRadius: '4px',
      },
    },
  },
  plugins: [codeblocks()],
});

Style settings referenceSee every style setting, with its defaults.

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

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