---
title: "starlight-codeblocks"
description: "A Starlight plugin that adds focus, line states, annotations, API auto-linking and 22 more features to the code blocks of a site."
url: "https://ewels.github.io/starlight-codeblocks/"
markdown: "https://ewels.github.io/starlight-codeblocks/index.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"
---

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

This plugin adds 26 features to the [Expressive Code](https://expressive-code.com) blocks of [Starlight](https://starlight.astro.build). Use them to enrich code blocks, they're perfect for docs and training. Using an agent? [Point it at the bundled skill](https://ewels.github.io/starlight-codeblocks/agent-skill/).

## Features

### Explain code

- [Annotations](https://ewels.github.io/starlight-codeblocks/features/annotations/): Add numbered markers to lines. Each marker opens a note in a popover, so the code stays clean until a reader asks.
- [Side annotations](https://ewels.github.io/starlight-codeblocks/features/side-annotations/): Show the notes of an annotated block in a column beside the code, so readers see every note next to its line.
- [Footnotes](https://ewels.github.io/starlight-codeblocks/features/footnotes/): Add numbered badges to lines, with the notes in a list under the block, where readers see them all at once.
- [Inline callouts](https://ewels.github.io/starlight-codeblocks/features/inline-callouts/): Put a short note in a bubble above a line, with an arrow that points at the word it explains.
- [Scrollycoding](https://ewels.github.io/starlight-codeblocks/features/scrollycoding/): Explain a code block in prose steps that scroll past it, while the block stays in view and focuses the lines of each step.
- [Code walkthrough](https://ewels.github.io/starlight-codeblocks/features/code-walkthrough/): Step through versions of one code block, and watch the code move from each version to the next, so readers see what changed.

### Draw attention

- [Focus](https://ewels.github.io/starlight-codeblocks/features/focus/): Blur the lines outside a range, so that readers look at the lines that you name first.
- [Line states](https://ewels.github.io/starlight-codeblocks/features/line-states/): Tint lines as errors, warnings, notes or successes, with an optional message after the code, like the diagnostics in a code editor.
- [Code mentions](https://ewels.github.io/starlight-codeblocks/features/code-mentions/): Link a phrase in the prose to lines of the code block below it, so that readers see which lines the text is about.

### Make code easier to read

- [Hidden lines](https://ewels.github.io/starlight-codeblocks/features/hidden-lines/): Hide the imports and set-up that readers need to run an example but not to understand it.
- [Expandable blocks](https://ewels.github.io/starlight-codeblocks/features/expandable-blocks/): Show the first lines of a long block, with a fade and a button to reveal the rest.
- [Visible whitespace](https://ewels.github.io/starlight-codeblocks/features/visible-whitespace/): Show spaces and tabs as faint glyphs, for the blocks where indentation changes the meaning of the code.
- [Colourised brackets](https://ewels.github.io/starlight-codeblocks/features/colourised-brackets/): Colour matching brackets by nesting depth, so a dense line of code stays readable.
- [Colour swatches](https://ewels.github.io/starlight-codeblocks/features/colour-swatches/): Show a small swatch of each CSS colour next to its value, so readers see the colour without a colour picker.
- [File icons](https://ewels.github.io/starlight-codeblocks/features/file-icons/): Show the icon of the file type before the title of a code block, with the icons of the Starlight file tree or a coloured icon set.
- [Inline code highlighting](https://ewels.github.io/starlight-codeblocks/features/inline-code-highlighting/): Give inline code in the prose the syntax colours of the code blocks, from a language suffix or a default language for the site.
- [Word-level diff](https://ewels.github.io/starlight-codeblocks/features/word-level-diff/): Highlight the words that changed inside each line of a diff, so readers find a small edit in a long line.

### Link code

- [Code links](https://ewels.github.io/starlight-codeblocks/features/code-links/): Turn text in code into a link with a card that describes it, from a directive in the comment above.
- [API auto-linking](https://ewels.github.io/starlight-codeblocks/features/api-auto-linking/): Link the names in code examples to their reference pages, with a card that shows the signature and a summary.
- [Line permalinks](https://ewels.github.io/starlight-codeblocks/features/line-permalinks/): Give a code block line numbers that link to each line, so readers can share a link to the exact lines they mean. Shift-click to select multiple lines.

### Adapt to the reader

- [Code tabs](https://ewels.github.io/starlight-codeblocks/features/code-tabs/): Show several code blocks as one, with editor tabs in the title bar, such as the files of a project or the commands for each package manager.
- [Fill-in placeholders](https://ewels.github.io/starlight-codeblocks/features/fill-in-placeholders/): Turn placeholders such as YOUR_TOKEN into fields, so readers type their own values into every block and the copied code.

### Copy and run

- [Smart shell copy](https://ewels.github.io/starlight-codeblocks/features/smart-shell-copy/): Add a Copy commands button to terminal blocks, which copies the commands without the prompts or the output.
- [Open in playground](https://ewels.github.io/starlight-codeblocks/features/open-in-playground/): Add a title bar button that opens the example in an online playground, with the code already filled in.
- [Run code](https://ewels.github.io/starlight-codeblocks/features/run-code/): Add a Run code button that runs the example in the browser and shows the output under the block.

## Install

Add the package to the site:

:::code-tabs{sync="pm"}
```sh label="npm"
npm install starlight-codeblocks
```
```sh label="pnpm"
pnpm add starlight-codeblocks
```
```sh label="Yarn"
yarn add starlight-codeblocks
```
:::

Then add `codeblocks()` to the Starlight plugins in `astro.config.mjs`:

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';
import codeblocks from 'starlight-codeblocks'; // [!code focus ++] Import the plugin

export default defineConfig({
  integrations: [
    starlight({
      title: 'My docs',
      plugins: [codeblocks()], // [!code focus ++] Load the plugin
    }),
  ],
});
```

The [getting started](https://ewels.github.io/starlight-codeblocks/getting-started/) page has the full steps.

## Extend and reference

- [Extend](https://ewels.github.io/starlight-codeblocks/extend/write-an-api-link-adapter/): your own API link adapters, playgrounds and runtimes.
- [Reference](https://ewels.github.io/starlight-codeblocks/reference/options/): every option, attribute, directive and style setting.

## Using with an agent

This website is agent-friendly: each page has a Markdown version at the same address with `.md` at the end, such as [getting-started.md](https://ewels.github.io/starlight-codeblocks/getting-started.md).
[llms.txt](https://ewels.github.io/starlight-codeblocks/llms.txt) lists every page, and [llms-full.txt](https://ewels.github.io/starlight-codeblocks/llms-full.txt) has every page in one file.

Using an agent? [Point it at the bundled skill](https://ewels.github.io/starlight-codeblocks/agent-skill/). The skill tells the agent which feature suits each use, and how to write it.

## Thanks

This plugin builds on the excellent [Expressive Code](https://expressive-code.com), which renders every code block in Starlight.

The `[!code …]` comment notation comes from the [Shiki transformers](https://shiki.style/packages/transformers) and [VitePress](https://vitepress.dev/). Thank you to both projects. Most code blocks from VitePress work here unchanged.