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.
The options object
Section titled “The options object”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:
starlight({ title: 'My docs', plugins: [ codeblocks({ focus: { style: 'dim' }, expandable: { lines: 20 }, runnable: false, }), ],});Options for one block
Section titled “Options for one block”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=falseconst 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().
Errors in the options
Section titled “Errors in the options”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.
Colours and sizes
Section titled “Colours and sizes”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:
starlight({ expressiveCode: { styleOverrides: { codeblocks: { accent: ['#c792ea', '#7c3aed'], popoverRadius: '4px', }, }, }, plugins: [codeblocks()],});Translate the plugin texts
Section titled “Translate the plugin texts”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:
| Language | Codes |
|---|---|
| Catalan | ca |
| Chinese | zh, zh-CN, zh-TW |
| Esperanto | eo |
| French | fr |
| German | de |
| Hindi | hi |
| Indonesian | id |
| Italian | it |
| Japanese | ja |
| Korean | ko |
| Norwegian Bokmål | nb, no |
| Polish | pl |
| Portuguese | pt, pt-BR, pt-PT |
| Russian | ru |
| Spanish | es |
| Swedish | sv |
| Turkish | tr |
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:
{ "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.
| Key | English text |
|---|---|
starlightCodeblocks.block.name | Code block |
starlightCodeblocks.block.nameWithTitle | Code: {{title}} |
starlightCodeblocks.lineStates.error | Error |
starlightCodeblocks.lineStates.warning | Warning |
starlightCodeblocks.lineStates.info | Note |
starlightCodeblocks.lineStates.success | Success |
starlightCodeblocks.squiggles.error | Error |
starlightCodeblocks.squiggles.warning | Warning |
starlightCodeblocks.squiggles.info | Info |
starlightCodeblocks.squiggles.errorLine | Line {{line}}, error |
starlightCodeblocks.squiggles.warningLine | Line {{line}}, warning |
starlightCodeblocks.squiggles.infoLine | Line {{line}}, info |
starlightCodeblocks.annotations.marker | Annotation {{number}} |
starlightCodeblocks.annotations.sideNote | Note {{number}}, for line {{line}}: |
starlightCodeblocks.footnotes.badge | Footnote {{number}} |
starlightCodeblocks.footnotes.number | Footnote {{number}}, for line {{line}} |
starlightCodeblocks.hiddenLines.marker_one | {{count}} hidden line |
starlightCodeblocks.hiddenLines.marker_other | {{count}} hidden lines |
starlightCodeblocks.hiddenLines.show_one | Show {{count}} hidden line |
starlightCodeblocks.hiddenLines.show_other | Show {{count}} hidden lines |
starlightCodeblocks.hiddenLines.hide_one | Hide {{count}} line |
starlightCodeblocks.hiddenLines.hide_other | Hide {{count}} lines |
starlightCodeblocks.expandable.showAll_one | Show all {{count}} line |
starlightCodeblocks.expandable.showAll_other | Show all {{count}} lines |
starlightCodeblocks.expandable.showFewer | Show fewer lines |
starlightCodeblocks.shellCopy.copy | Copy commands |
starlightCodeblocks.shellCopy.copied | Copied |
starlightCodeblocks.swatches.hint | Click to copy |
starlightCodeblocks.swatches.copy | Copy colour {{colour}} |
starlightCodeblocks.swatches.copied | Copied |
starlightCodeblocks.swatches.copiedColour | Copied {{colour}} |
starlightCodeblocks.permalinks.link | Link to line {{line}} |
starlightCodeblocks.codeTabs.variant | Variant |
starlightCodeblocks.codeTabs.plainText | Plain text |
starlightCodeblocks.playgrounds.typescript | Open in TS Playground |
starlightCodeblocks.playgrounds.rust | Open in Rust Playground |
starlightCodeblocks.playgrounds.newTab | (opens in a new tab) |
starlightCodeblocks.runnable.run | Run code |
starlightCodeblocks.runnable.again | Run again |
starlightCodeblocks.runnable.output | Output |
starlightCodeblocks.runnable.running | Running… |
starlightCodeblocks.runnable.loading | Loading the {{language}} runtime… |
starlightCodeblocks.runnable.loadFailed | The {{language}} runtime did not load. |
starlightCodeblocks.runnable.noOutput | The code ran with no output. |
starlightCodeblocks.runnable.timeout_one | The run stopped after {{count}} second. |
starlightCodeblocks.runnable.timeout_other | The run stopped after {{count}} seconds. |
starlightCodeblocks.runnable.error | Error: |
starlightCodeblocks.walkthrough.steps | Steps |
starlightCodeblocks.walkthrough.step | Step {{step}} |
starlightCodeblocks.walkthrough.stepWithLabel | Step {{step}}: {{label}} |
starlightCodeblocks.walkthrough.stepCount | Step {{step}} of {{total}} |
starlightCodeblocks.walkthrough.previous | Previous |
starlightCodeblocks.walkthrough.next | Next |
starlightCodeblocks.scrollycoding.codeFromStep | Code from this step on: |
Options with an ec.config.mjs file
Section titled “Options with an ec.config.mjs file”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.