---
title: "Plugin compatibility"
description: "Configure the plugin next to other Starlight plugins, themes, Expressive Code plugins and Markdown processors."
url: "https://ewels.github.io/starlight-codeblocks/reference/plugin-compatibility/"
markdown: "https://ewels.github.io/starlight-codeblocks/reference/plugin-compatibility.md"
section: "Reference"
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"
---

# Plugin compatibility

> Configure the plugin next to other Starlight plugins, themes, Expressive Code plugins and Markdown processors.

A Starlight site often has more than one plugin. [Most plugins](https://ewels.github.io/starlight-codeblocks/reference/plugin-compatibility/#tested-plugins) work next to this one with no change. Some need a setting, or a place in the list of plugins. This page gives the set-up for each of them.

## Plugin order

List `codeblocks()` before any plugin or theme that sets the `expressiveCode` option of Starlight. For example, [`starlight-theme-nova`](https://github.com/ocavue/starlight-theme-nova) turns Expressive Code off unless the site sets the option:

```js title="astro.config.mjs"
starlight({
  plugins: [codeblocks(), starlightThemeNova()],
}),
```

If a theme must come first, set `expressiveCode: {}` in the Starlight config. The plugin stops the build with a message if Expressive Code is off.

## Expressive Code plugins in ec.config.mjs

If `ec.config.mjs` has a `plugins` list, the plugin cannot add its own Expressive Code plugins. Add `pluginCodeblocks()` to the list:

```js title="ec.config.mjs"
import { pluginLineNumbers } from '@expressive-code/plugin-line-numbers';
import { pluginCodeblocks } from 'starlight-codeblocks/expressive-code';

export default {
  plugins: [pluginLineNumbers(), pluginCodeblocks()],
};
```

`pluginCodeblocks()` can go before or after most other plugins. The features find each line wherever another plugin puts it, such as inside a collapsed section. `pluginCollapsibleSections()` must come before `pluginCodeblocks()`, and the build stops with a message if it does not.

[`expressive-code-twoslash`](https://twoslash.studiocms.dev) removes some lines of a block, such as the last lines after a `^?` query. A directive on a line that it removes has no effect, and the build logs a warning. Put the directive on a line that stays.

## Specific plugin guidance

### starlight-links-validator

[`starlight-links-validator`](https://github.com/HiDeoo/starlight-links-validator) reports links to [code mentions](https://ewels.github.io/starlight-codeblocks/features/code-mentions/) and [line permalinks](https://ewels.github.io/starlight-codeblocks/features/line-permalinks/) as broken. It cannot see those ids, because they exist only in the rendered code. Give it the `linksValidatorExclude` function from this plugin:

```js title="astro.config.mjs"
import codeblocks, { linksValidatorExclude } from 'starlight-codeblocks';
import starlightLinksValidator from 'starlight-links-validator';

starlight({
  plugins: [codeblocks(), starlightLinksValidator({ exclude: linksValidatorExclude })],
}),
```

The function skips `#mention:` links and links to the `id` of a code block, alone or with a line, such as `#cfg-L2`. The validator still checks every other link.

### starlight-llms-txt

[`starlight-llms-txt`](https://delucis.github.io/starlight-llms-txt/) makes its text from the HTML of each page. The plugin adds labels, buttons and notes to a block, and the text of those goes into the code. Every one of these elements has the class `scb-deco`. Remove them with one selector:

```js title="astro.config.mjs"
starlightLlmsTxt({
  customSelectors: { all: ['.scb-deco'] },
}),
```

The code in `llms-full.txt` is then the code that the copy button copies. Placeholder fields keep their text. Annotations, callouts and footnote badges go. Notes that show under a block, such as the list of footnotes, stay as a plain numbered list.

Pagefind needs no set-up. It does not index these elements, because each one has `data-pagefind-ignore`.

### Page actions and raw Markdown

[`starlight-page-actions`](https://starlight-page-actions.dlcastillop.com), [`starlight-page-context-action`](https://github.com/babblebey/starlight-page-context-action) and [`starlight-md-txt`](https://github.com/max-ostapenko/starlight-md-txt) give readers the Markdown source of a page. That source keeps the attributes on the first line of each code block and the directives in the code comments, as the author wrote them. The plugin does not change it. Most readers of the source, such as AI assistants, can read directives, because they are comments.

### starlight-versions and starlight-md-txt

[`starlight-versions`](https://github.com/HiDeoo/starlight-versions) and [`starlight-md-txt`](https://github.com/max-ostapenko/starlight-md-txt) read `.md` files as MDX. MDX reads a `{:js}` after the closing backtick of inline code as a JavaScript expression, and the build fails. Put the suffix of [inline code highlighting](https://ewels.github.io/starlight-codeblocks/features/inline-code-highlighting/) inside the backticks. That form is valid in `.md` and `.mdx` files.

### Markdoc

In Markdoc files (`.mdoc`), with [`@astrojs/markdoc`](https://docs.astro.build/en/guides/integrations-guide/markdoc/) and [`@astrojs/starlight-markdoc`](https://github.com/withastro/starlight/tree/main/packages/markdoc), the features inside a code block work. Markdoc does not take attributes on the fence line. Put them in a `meta` attribute of a Markdoc tag after the language:

````md title="src/content/docs/example.mdoc"
```js {% title="app.js" meta="focus={2}" %}
const app = express();
app.use(express.json());
app.listen(3000);
```
````

Directives in code comments work as in Markdown. Markdoc has its own parser, so the features that read the text outside a block do not run in `.mdoc` files:

- code tabs
- inline code highlighting
- the check of code mention links
- the check for duplicate block ids

Use `.md` or `.mdx` files for pages that need them.

## The unified() processor

Astro 7 uses Sätteri for Markdown. Some plugins need Astro's `unified()` processor, because they add remark plugins, such as [`starlight-markdown-blocks`](https://delucis.github.io/starlight-markdown-blocks/). Every feature works with `unified()` too. The plugin adds its own remark plugin when the site uses it:

```js title="astro.config.mjs"
import { unified } from '@astrojs/markdown-remark';

export default defineConfig({
  markdown: { processor: unified() },
  integrations: [starlight({ plugins: [codeblocks()] })],
});
```

Starlight adds [`remark-directive`](https://github.com/remarkjs/remark-directive) for `unified()`, which code tabs need. Sätteri stays the default of Astro 7, so keep it unless another plugin needs `unified()`.

## Tested plugins

These plugins were tested on a site with every feature of this plugin on. They need no change:

- Pages and content: [`starlight-openapi`](https://github.com/HiDeoo/starlight-openapi), [`starlight-typedoc`](https://github.com/HiDeoo/starlight-typedoc), [`starlight-pydocs`](https://ewels.github.io/starlight-pydocs), [`starlight-blog`](https://github.com/HiDeoo/starlight-blog), [`starlight-tags`](https://github.com/frostybee/starlight-tags), [`starlight-quiz`](https://ewels.github.io/starlight-quiz), [`starlight-videos`](https://github.com/HiDeoo/starlight-videos), [`astro-mermaid`](https://github.com/joesaby/astro-mermaid), [`starlight-github-alerts`](https://github.com/HiDeoo/starlight-github-alerts), [`starlight-kbd`](https://github.com/HiDeoo/starlight-kbd) and [`starlight-heading-badges`](https://github.com/HiDeoo/starlight-heading-badges).
- Navigation and search: [`starlight-sidebar-topics`](https://github.com/HiDeoo/starlight-sidebar-topics), [`starlight-auto-sidebar`](https://github.com/HiDeoo/starlight-auto-sidebar), [`starlight-site-graph`](https://github.com/fevol/starlight-site-graph), [`starlight-scroll-to-top`](https://github.com/frostybee/starlight-scroll-to-top), [`@astrojs/starlight-docsearch`](https://starlight.astro.build/guides/site-search/#algolia-docsearch) and [`starlight-telescope`](https://github.com/frostybee/starlight-telescope).
- Layout: [`starlight-image-zoom`](https://github.com/HiDeoo/starlight-image-zoom), [`starlight-fullview-mode`](https://windmillcode.github.io/starlight-fullview-mode), [`starlight-view-modes`](https://starlight-view-modes.netlify.app), [`starlight-ui-tweaks`](https://starlight-ui-tweaks.dlcastillop.com), [`starlight-announcement`](https://github.com/frostybee/starlight-announcement), [`starlight-package-managers`](https://github.com/HiDeoo/starlight-package-managers) and [`@astrojs/starlight-tailwind`](https://starlight.astro.build/guides/css-and-tailwind/#tailwind-css) with Tailwind 4.
- Themes: [`starlight-theme-rapide`](https://github.com/HiDeoo/starlight-theme-rapide), [`starlight-theme-flexoki`](https://delucis.github.io/starlight-theme-flexoki/), [`starlight-theme-next`](https://starlight-theme-next.netlify.app), [`starlight-theme-vintage`](https://github.com/HiDeoo/starlight-theme-vintage), [`starlight-theme-black`](https://github.com/adrian-ub/starlight-theme-black), [`starlight-theme-galaxy`](https://frostybee.github.io/starlight-theme-galaxy) and [`@catppuccin/starlight`](https://starlight.catppuccin.com/).
- Expressive Code plugins: [`@expressive-code/plugin-line-numbers`](https://expressive-code.com/plugins/line-numbers/), [`@expressive-code/plugin-collapsible-sections`](https://expressive-code.com/plugins/collapsible-sections/), [`expressive-code-color-chips`](https://delucis.github.io/expressive-code-color-chips/) and [`expressive-code-links`](https://github.com/towc/expressive-code-links).
- Full screen code blocks: [`starlight-codeblock-fullscreen`](https://github.com/frostybee/starlight-codeblock-fullscreen). The controls of every feature work in its full screen copy of a block.

## Related

- [Configuration](https://ewels.github.io/starlight-codeblocks/configuration/): turn features on and off, and configure them.
- [Expressive Code plugins](https://ewels.github.io/starlight-codeblocks/reference/expressive-code-plugins/): use the features one at a time in `ec.config.mjs`.