Starlight setup

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.

For an Astro site that does not use Starlight, follow Astro setup.

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.

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.