---
title: "Getting started"
description: "Install starlight-codeblocks and add it to a Starlight site."
url: "https://ewels.github.io/starlight-codeblocks/getting-started/"
markdown: "https://ewels.github.io/starlight-codeblocks/getting-started.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"
---

# Getting started

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

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

## Sites without Starlight

Astro sites that use Expressive Code without Starlight add the preset to the Expressive Code plugins. Give the options to `pluginCodeblocks()`:

```js title="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](https://ewels.github.io/starlight-codeblocks/reference/expressive-code-plugins/#without-starlight).

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