Skip to content

Configuration

With no options, codeblocks() turns on every feature. Most features change a code block only when the block uses their attribute or directive. A few, such as file icons, colour swatches and word-level diff, apply to every matching block. Pages that use no interactive feature load no JavaScript from the plugin.

In the astro config file, the plugins codeblocks() function takes one object. Each feature has a key in it. Set a key to false to turn the feature off, or to an object to change its settings:

astro.config.mjs
starlight({
title: 'My docs',
plugins: [
codeblocks({
focus: { style: 'dim' },
expandable: { lines: 20 },
runnable: false,
}),
],
});

To change a setting for one block only, put the option on the fence line, with the same name as in codeblocks(). The fence line is the first line of the code block, with the language. The rest of the site keeps its setting:

```js focus={2} focus.style="dim" lineStates.prefix=false
const host = 'localhost'
const port = 8080 // [!code warning] Set in production
```

This works for every setting that applies to one block, such as wordDiff.minSimilarity=0.6 or runnable.label="Try it". A value of the wrong type gives a build warning, and the block uses the site setting. Options for the whole site, such as custom line states, playgrounds and runtimes, stay in codeblocks().

The plugin checks the options when the site starts. An unknown key or a value of the wrong type stops the build with a message that names the option:

Error:starlight-codeblocks: `focus.style` must be 'blur' | 'dim', got "fade".

A feature with no settings, such as callouts, takes only false. To keep the feature on, leave its key out.

Every colour and size of the plugin is an Expressive Code style setting. The default colours come from the Expressive Code theme of the site, such as its terminal blue for the accent. So they follow any theme, dark or light. The plugin makes each colour lighter or darker where it needs to, so that the defaults meet the contrast targets on the accessibility page.

To change a setting, add styleOverrides to the Expressive Code options of Starlight. The shared settings are in the codeblocks group. A string applies to both themes, and a pair gives the dark value and then the light value:

astro.config.mjs
starlight({
expressiveCode: {
styleOverrides: {
codeblocks: {
accent: ['#c792ea', '#7c3aed'],
popoverRadius: '4px',
},
},
},
plugins: [codeblocks()],
});

The buttons, labels and screen reader texts of the plugin come in English and in 17 more languages. On a Starlight site with more than one language, each page gets the texts of its language. The lang of a locale must match one of these codes:

LanguageCodes
Catalanca
Chinesezh, zh-CN, zh-TW
Esperantoeo
Frenchfr
Germande
Hindihi
Indonesianid
Italianit
Japaneseja
Koreanko
Norwegian Bokmålnb, no
Polishpl
Portuguesept, pt-BR, pt-PT
Russianru
Spanishes
Swedishsv
Turkishtr

Portuguese uses the Brazilian words, and Chinese uses simplified characters. A locale with another code, such as de-AT, does not get these texts.

To change a text, or to add a language, add its key to the file of the language in src/content/i18n/. These are the files of the UI strings of Starlight. The texts of the site come before the texts of the plugin:

src/content/i18n/de.json
{
"starlightCodeblocks.runnable.run": "Code starten",
"starlightCodeblocks.hiddenLines.marker_one": "{{count}} versteckte Zeile",
"starlightCodeblocks.hiddenLines.marker_other": "{{count}} versteckte Zeilen"
}

If a language has no text for a key, the page shows the text of the default language, then the English text.

A text with a count has one key for each plural form of the language. English has _one and _other, and Polish also has _few and _many. To change such a text, give all its plural keys. A name in double braces, such as {{count}}, is a value that the plugin fills in. Keep it in the translation.

The runnable.label and runnable.againLabel options, on the site or on a fence line, replace the translations of the Run code button. Custom line states and playgrounds show the label from their options. Sites without Starlight show the English texts.

Native speakers can make the translations better. To correct a text, or to add a language to the plugin, follow the contributing guide.

KeyEnglish text
starlightCodeblocks.block.nameCode block
starlightCodeblocks.block.nameWithTitleCode: {{title}}
starlightCodeblocks.lineStates.errorError
starlightCodeblocks.lineStates.warningWarning
starlightCodeblocks.lineStates.infoNote
starlightCodeblocks.lineStates.successSuccess
starlightCodeblocks.squiggles.errorError
starlightCodeblocks.squiggles.warningWarning
starlightCodeblocks.squiggles.infoInfo
starlightCodeblocks.squiggles.errorLineLine {{line}}, error
starlightCodeblocks.squiggles.warningLineLine {{line}}, warning
starlightCodeblocks.squiggles.infoLineLine {{line}}, info
starlightCodeblocks.annotations.markerAnnotation {{number}}
starlightCodeblocks.annotations.sideNoteNote {{number}}, for line {{line}}:
starlightCodeblocks.footnotes.badgeFootnote {{number}}
starlightCodeblocks.footnotes.numberFootnote {{number}}, for line {{line}}
starlightCodeblocks.hiddenLines.marker_one{{count}} hidden line
starlightCodeblocks.hiddenLines.marker_other{{count}} hidden lines
starlightCodeblocks.hiddenLines.show_oneShow {{count}} hidden line
starlightCodeblocks.hiddenLines.show_otherShow {{count}} hidden lines
starlightCodeblocks.hiddenLines.hide_oneHide {{count}} line
starlightCodeblocks.hiddenLines.hide_otherHide {{count}} lines
starlightCodeblocks.expandable.showAll_oneShow all {{count}} line
starlightCodeblocks.expandable.showAll_otherShow all {{count}} lines
starlightCodeblocks.expandable.showFewerShow fewer lines
starlightCodeblocks.shellCopy.copyCopy commands
starlightCodeblocks.shellCopy.copiedCopied
starlightCodeblocks.swatches.hintClick to copy
starlightCodeblocks.swatches.copyCopy colour {{colour}}
starlightCodeblocks.swatches.copiedCopied
starlightCodeblocks.swatches.copiedColourCopied {{colour}}
starlightCodeblocks.permalinks.linkLink to line {{line}}
starlightCodeblocks.codeTabs.variantVariant
starlightCodeblocks.codeTabs.plainTextPlain text
starlightCodeblocks.playgrounds.typescriptOpen in TS Playground
starlightCodeblocks.playgrounds.rustOpen in Rust Playground
starlightCodeblocks.playgrounds.newTab(opens in a new tab)
starlightCodeblocks.runnable.runRun code
starlightCodeblocks.runnable.againRun again
starlightCodeblocks.runnable.outputOutput
starlightCodeblocks.runnable.runningRunning…
starlightCodeblocks.runnable.loadingLoading the {{language}} runtime…
starlightCodeblocks.runnable.loadFailedThe {{language}} runtime did not load.
starlightCodeblocks.runnable.noOutputThe code ran with no output.
starlightCodeblocks.runnable.timeout_oneThe run stopped after {{count}} second.
starlightCodeblocks.runnable.timeout_otherThe run stopped after {{count}} seconds.
starlightCodeblocks.runnable.errorError:
starlightCodeblocks.walkthrough.stepsSteps
starlightCodeblocks.walkthrough.stepStep {{step}}
starlightCodeblocks.walkthrough.stepWithLabelStep {{step}}: {{label}}
starlightCodeblocks.walkthrough.stepCountStep {{step}} of {{total}}
starlightCodeblocks.walkthrough.previousPrevious
starlightCodeblocks.walkthrough.nextNext
starlightCodeblocks.scrollycoding.codeFromStepCode from this step on:

Some sites keep their Expressive Code options in an ec.config.mjs file, next to astro.config.mjs. If that file has a plugins list, add pluginCodeblocks() to it, as in Sites with an ec.config.mjs file.

Give pluginCodeblocks() no argument. It reads its options from codeblocks(), so all options stay in astro.config.mjs. styleOverrides can go in either file.