---
title: "Starlight setup"
description: "Install starlight-codeblocks and add it to a Starlight site."
url: "https://ewels.github.io/starlight-codeblocks/install/starlight/"
markdown: "https://ewels.github.io/starlight-codeblocks/install/starlight.md"
section: "Start here"
site: "starlight-codeblocks documentation"
context: "This page is from the documentation of starlight-codeblocks. A plugin for Starlight and Astro 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"
---

# Starlight setup

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

For an Astro site that does not use Starlight, follow [Astro setup](https://ewels.github.io/starlight-codeblocks/install/astro/).

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

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