Getting started

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

   npm install starlight-codeblocks

   pnpm

   pnpm add starlight-codeblocks

   Yarn

   yarn add starlight-codeblocks

2. Open astro.config.mjs.

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

   astro.config.mjs

   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:

ec.config.mjs

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():

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.

Next steps

ConfigurationLearn how to set options for the whole site, or for a single code block.

FeaturesBrowse all the features, with an example of each.