Skip to content
starlight-codeblocks

Plugin compatibility

View as MarkdownOpen in ClaudeOpen in ChatGPT

A Starlight site often has more than one plugin. Most 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

Section titled “Plugin order”

List codeblocks() before any plugin or theme that sets the expressiveCode option of Starlight. For example, starlight-theme-nova turns Expressive Code off unless the site sets the option:

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

Section titled “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:

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

Section titled “Specific plugin guidance”
Section titled “starlight-links-validator”

starlight-links-validator reports links to code mentions and 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:

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

Section titled “starlight-llms-txt”

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:

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

Section titled “Page actions and raw Markdown”

starlight-page-actions, starlight-page-context-action and 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

Section titled “starlight-versions and starlight-md-txt”

starlight-versions and 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 inside the backticks. That form is valid in .md and .mdx files.

Markdoc

Section titled “Markdoc”

In Markdoc files (.mdoc), with @astrojs/markdoc and @astrojs/starlight-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:

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

Section titled “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. Every feature works with unified() too. The plugin adds its own remark plugin when the site uses it:

astro.config.mjs
import { unified } from '@astrojs/markdown-remark';


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

Starlight adds 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

Section titled “Tested plugins”

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

Section titled “Related”