--- title: "Options" description: "Every option of codeblocks() and pluginCodeblocks(), with its type and default." url: "https://ewels.github.io/starlight-codeblocks/reference/options/" markdown: "https://ewels.github.io/starlight-codeblocks/reference/options.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" --- # Options > Every option of codeblocks() and pluginCodeblocks(), with its type and default. `codeblocks()` and `pluginCodeblocks()` take the same options object. A key with the type `false | object` takes `false` to turn the feature off, or an object with the settings below it. A key with the type `false` has no settings. The [configuration](https://ewels.github.io/starlight-codeblocks/configuration/) page shows how to use them. ## `focus` Blurs the lines outside a focus range. Set it to `false` to turn the feature off. `[!code focus]` then stays in the code as written. - Type: `false | object` - Default: On - Feature: [Focus](https://ewels.github.io/starlight-codeblocks/features/focus/) ## `focus.style` Blur and fade the other lines, or only fade them. A code block can set its own on its fence line. - Type: `'blur' | 'dim'` - Default: `'blur'` - Feature: [Focus](https://ewels.github.io/starlight-codeblocks/features/focus/) ## `lineStates` Tints lines as errors, warnings, notes or successes, with an optional message. Set it to `false` to turn the feature off. The directives then stay in the code as written. - Type: `false | object` - Default: On - Feature: [Line states](https://ewels.github.io/starlight-codeblocks/features/line-states/) ## `lineStates.states` Custom states by name, in addition to `error`, `warning`, `info` and `success`. A name uses lower-case letters, digits and hyphens. - Type: `Record` - Default: `{}` - Feature: [Line states](https://ewels.github.io/starlight-codeblocks/features/line-states/) ## `lineStates.prefix` Show the name of the state, such as **Error**, before each message, and on the first line of a run with no message. Off, the tint alone marks the state on screen. A code block can set its own on its fence line. - Type: `boolean` - Default: `true` - Feature: [Line states](https://ewels.github.io/starlight-codeblocks/features/line-states/) ## `notation` Reads directives in code comments. Set it to `false` to turn the feature off. Every comment then renders as written. - Type: `false | object` - Default: On - Feature: [Comment notation](https://ewels.github.io/starlight-codeblocks/comment-notation/) ## `notation.comments` Comment syntax for each language, added to the built-in map. An empty list removes a language. - Type: `Record` - Default: `{}` - Feature: [Comment notation](https://ewels.github.io/starlight-codeblocks/comment-notation/) ## `callouts` Shows a note in a bubble above a line. Set it to `false` to turn the feature off. - Type: `false` - Default: On - Feature: [Inline callouts](https://ewels.github.io/starlight-codeblocks/features/inline-callouts/) ## `annotations` Adds numbered markers that open a note. Set it to `false` to turn the feature off. - Type: `false | object` - Default: On - Feature: [Annotations](https://ewels.github.io/starlight-codeblocks/features/annotations/) ## `annotations.style` Filled markers in the accent colour, or outlined markers in the magenta of the theme. Side annotations use it too. A code block can set its own on its fence line. - Type: `'filled' | 'outline'` - Default: `'filled'` - Feature: [Annotations](https://ewels.github.io/starlight-codeblocks/features/annotations/) ## `footnotes` Adds numbered badges to lines, with the notes in a list under the block. Set it to `false` to turn the feature off. - Type: `false | object` - Default: On - Feature: [Footnotes](https://ewels.github.io/starlight-codeblocks/features/footnotes/) ## `footnotes.sticky` Keep the list of footnotes in view while the block is on screen. A code block can set its own on its fence line. - Type: `boolean` - Default: `false` - Feature: [Footnotes](https://ewels.github.io/starlight-codeblocks/features/footnotes/) ## `footnotes.style` Filled badges in the accent colour, or outlined badges in the magenta of the theme. A code block can set its own on its fence line. - Type: `'filled' | 'outline'` - Default: `'outline'` - Feature: [Footnotes](https://ewels.github.io/starlight-codeblocks/features/footnotes/) ## `hiddenLines` Hides lines that readers need to run the code but not to understand it. Set it to `false` to turn the feature off. - Type: `false` - Default: On - Feature: [Hidden lines](https://ewels.github.io/starlight-codeblocks/features/hidden-lines/) ## `shellCopy` Adds a Copy commands button to terminal blocks with prompts, which copies the commands only. Set it to `false` to turn the feature off. - Type: `false | object` - Default: On - Feature: [Smart shell copy](https://ewels.github.io/starlight-codeblocks/features/smart-shell-copy/) ## `shellCopy.prompts` Line starts that mark a command. A code block can set its own on its fence line. - Type: `string[]` - Default: `['$ ','> ']` - Feature: [Smart shell copy](https://ewels.github.io/starlight-codeblocks/features/smart-shell-copy/) ## `wordDiff` Highlights the words that changed between a removed line and an added line. Set it to `false` to turn the feature off. - Type: `false | object` - Default: On - Feature: [Word-level diff](https://ewels.github.io/starlight-codeblocks/features/word-level-diff/) ## `wordDiff.minSimilarity` Pairs of lines less similar than this keep whole-line tints only. From 0 to 1. A code block can set its own on its fence line. - Type: `number` - Default: `0.4` - Feature: [Word-level diff](https://ewels.github.io/starlight-codeblocks/features/word-level-diff/) ## `whitespace` Shows spaces and tabs as faint glyphs. Set it to `false` to turn the feature off. - Type: `false` - Default: On - Feature: [Visible whitespace](https://ewels.github.io/starlight-codeblocks/features/visible-whitespace/) ## `brackets` Colours matching brackets by nesting depth. Set it to `false` to turn the feature off. - Type: `false | object` - Default: On - Feature: [Colourised brackets](https://ewels.github.io/starlight-codeblocks/features/colourised-brackets/) ## `brackets.languages` Languages that get colourised brackets in every block. - Type: `string[]` - Default: `[]` - Feature: [Colourised brackets](https://ewels.github.io/starlight-codeblocks/features/colourised-brackets/) ## `swatches` Shows a swatch of the colour before each CSS colour in code. Set it to `false` to turn the feature off. - Type: `false | object` - Default: On - Feature: [Colour swatches](https://ewels.github.io/starlight-codeblocks/features/colour-swatches/) ## `swatches.languages` Languages that get swatches. `swatches` on the fence line turns them on for one block of another language. - Type: `'all' | string[]` - Default: `'all'` - Feature: [Colour swatches](https://ewels.github.io/starlight-codeblocks/features/colour-swatches/) ## `swatches.formats` The kinds of colour that get swatches. `rgb` also covers `rgba()`, and `hsl` covers `hsla()`. `named` is the CSS colour names, such as `rebeccapurple`. - Type: `Array<'hex' | 'rgb' | 'hsl' | 'hwb' | 'lab' | 'lch' | 'oklab' | 'oklch' | 'color' | 'named'>` - Default: `['hex','rgb','hsl','hwb','lab','lch','oklab','oklch','color','named']` - Feature: [Colour swatches](https://ewels.github.io/starlight-codeblocks/features/colour-swatches/) ## `swatches.shape` The shape of each swatch. A code block can set its own on its fence line. - Type: `'square' | 'rounded' | 'circle'` - Default: `'rounded'` - Feature: [Colour swatches](https://ewels.github.io/starlight-codeblocks/features/colour-swatches/) ## `swatches.size` The width and height of each swatch, as a CSS length such as `10px` or `0.8em`. - Type: `string` - Default: `'0.8em'` - Feature: [Colour swatches](https://ewels.github.io/starlight-codeblocks/features/colour-swatches/) ## `swatches.hover` Tint the colour text in its own colour, and enlarge the swatch, when the mouse cursor is on it. - Type: `boolean` - Default: `true` - Feature: [Colour swatches](https://ewels.github.io/starlight-codeblocks/features/colour-swatches/) ## `swatches.copy` Copy the colour when the reader clicks it. - Type: `boolean` - Default: `true` - Feature: [Colour swatches](https://ewels.github.io/starlight-codeblocks/features/colour-swatches/) ## `swatches.prose` Also show swatches in the text of Markdown pages, and in inline code that is one colour. Named colours get a swatch only in inline code. - Type: `boolean` - Default: `false` - Feature: [Colour swatches](https://ewels.github.io/starlight-codeblocks/features/colour-swatches/) ## `swatches.match` Outside stylesheets, `value` shows a swatch only for a colour that looks like a value. `all` shows a swatch for every hex colour and colour function. A code block can set its own on its fence line. - Type: `'value' | 'all'` - Default: `'value'` - Feature: [Colour swatches](https://ewels.github.io/starlight-codeblocks/features/colour-swatches/) ## `swatches.delimiters` More text that can come before or after a colour that looks like a value, such as `|`. They add to the built-in delimiters. - Type: `{ before?: string[]; after?: string[] }` - Default: `{}` - Feature: [Colour swatches](https://ewels.github.io/starlight-codeblocks/features/colour-swatches/) ## `swatches.byLanguage` A `match` and `delimiters` for the blocks of each language. They replace the site settings for that language. - Type: `Record` - Default: `{}` - Feature: [Colour swatches](https://ewels.github.io/starlight-codeblocks/features/colour-swatches/) ## `fileIcons` Shows the icon of the file type before the title of a code block. Set it to `false` to turn the feature off. `icon` attributes then have no effect. - Type: `false | object` - Default: On - Feature: [File icons](https://ewels.github.io/starlight-codeblocks/features/file-icons/) ## `fileIcons.set` The icons: the coloured icons of vscode-icons, Material Icon Theme or Catppuccin, or the one-colour Seti icons of the Starlight file tree. Material and Catppuccin need their `@iconify-json` package, such as `@iconify-json/catppuccin`. - Type: `'seti' | 'material' | 'vscode-icons' | 'catppuccin'` - Default: `'vscode-icons'` - Feature: [File icons](https://ewels.github.io/starlight-codeblocks/features/file-icons/) ## `fileIcons.style` The icon alone, or the icon on a square with rounded corners. A language or a code block can set its own. - Type: `'plain' | 'tile'` - Default: `'plain'` - Feature: [File icons](https://ewels.github.io/starlight-codeblocks/features/file-icons/) ## `fileIcons.languages` Settings for the blocks of each language: the icon when the title gives none, as an icon name or SVG markup, or `false` for none, a CSS colour for the icon or the tile, and the style. - Type: `Record` - Default: `{}` - Feature: [File icons](https://ewels.github.io/starlight-codeblocks/features/file-icons/) ## `fileIcons.files` Icon names, or `false` for no icon, by file name, such as `nextflow.config`, by extension, such as `.nf`, or by path pattern, such as `.github/**`. A `*` matches within one folder, and `**` across folders. They come before the built-in rules. - Type: `Record` - Default: `{}` - Feature: [File icons](https://ewels.github.io/starlight-codeblocks/features/file-icons/) ## `fileIcons.icons` Custom icons by name: SVG markup, or the path data of a 24 by 24 icon. A custom name replaces a built-in icon of the same name. - Type: `Record` - Default: `{}` - Feature: [File icons](https://ewels.github.io/starlight-codeblocks/features/file-icons/) ## `codeLinks` Turns text on a line into a link. Set it to `false` to turn the feature off. - Type: `false` - Default: On - Feature: [Code links](https://ewels.github.io/starlight-codeblocks/features/code-links/) ## `apiLinks` Links names in code to their reference pages. Set it to `false` to turn the feature off. - Type: `false | object` - Default: On - Feature: [API auto-linking](https://ewels.github.io/starlight-codeblocks/features/api-auto-linking/) ## `apiLinks.adapters` Adapters that find and resolve names. - Type: `ApiLinkAdapter[]` - Default: `[python(), nextflow()]` - Feature: [API auto-linking](https://ewels.github.io/starlight-codeblocks/features/api-auto-linking/) ## `expandable` Shows the first lines of long blocks, with a button to show the rest. Set it to `false` to turn the feature off. `expandable` and `expandable={N}` then have no effect. - Type: `false | object` - Default: On - Feature: [Expandable blocks](https://ewels.github.io/starlight-codeblocks/features/expandable-blocks/) ## `expandable.lines` Lines to show before the block expands. A code block can set its own on its fence line. - Type: `number` - Default: `12` - Feature: [Expandable blocks](https://ewels.github.io/starlight-codeblocks/features/expandable-blocks/) ## `expandable.auto` Makes every block with more lines than this expandable, without the attribute. `expandable=false` turns it off for one block. - Type: `number | false` - Default: `false` - Feature: [Expandable blocks](https://ewels.github.io/starlight-codeblocks/features/expandable-blocks/) ## `playgrounds` Adds a button that opens the code in an online playground. Set it to `false` to turn the feature off. `playground` attributes then have no effect. - Type: `false | object` - Default: On - Feature: [Open in playground](https://ewels.github.io/starlight-codeblocks/features/open-in-playground/) ## `playgrounds.` Custom playgrounds by name, in addition to the built-in ones. - Type: an object with a `label` and one of `url` or `post` - Default: None - Feature: [Open in playground](https://ewels.github.io/starlight-codeblocks/features/open-in-playground/) ## `mentions` Highlights lines when the reader hovers over a link in the prose. Set it to `false` to turn the feature off. - Type: `false` - Default: On - Feature: [Code mentions](https://ewels.github.io/starlight-codeblocks/features/code-mentions/) ## `permalinks` Turns line numbers into links to each line. Set it to `false` to turn the feature off. - Type: `false` - Default: On - Feature: [Line permalinks](https://ewels.github.io/starlight-codeblocks/features/line-permalinks/) ## `placeholders` Turns placeholder text into input fields. Set it to `false` to turn the feature off. - Type: `false | object` - Default: On - Feature: [Fill-in placeholders](https://ewels.github.io/starlight-codeblocks/features/fill-in-placeholders/) ## `placeholders.storage` Where the browser keeps the values that readers type. A code block can set its own on its fence line. - Type: `'local' | 'session' | 'none'` - Default: `'local'` - Feature: [Fill-in placeholders](https://ewels.github.io/starlight-codeblocks/features/fill-in-placeholders/) ## `codeTabs` Combines several variants of a block, with tabs or a menu in the title bar. Set it to `false` to turn the feature off. - Type: `false | object` - Default: On - Feature: [Code tabs](https://ewels.github.io/starlight-codeblocks/features/code-tabs/) ## `codeTabs.control` Editor tabs in the title bar, or a menu on its right. A `:::code-tabs` directive can set its own with `control="…"`. - Type: `'tabs' | 'menu'` - Default: `'tabs'` - Feature: [Code tabs](https://ewels.github.io/starlight-codeblocks/features/code-tabs/) ## `walkthrough` Animates the code between the steps of a `` component. Set it to `false` to turn the feature off. `` then shows each step as a separate block, with its label after the title, and loads no script. - Type: `false` - Default: On - Feature: [Code walkthrough](https://ewels.github.io/starlight-codeblocks/features/code-walkthrough/) ## `scrollycoding` Changes the focus of a sticky block as the prose steps scroll past. Set it to `false` to turn the feature off. - Type: `false` - Default: On - Feature: [Scrollycoding](https://ewels.github.io/starlight-codeblocks/features/scrollycoding/) ## `inlineHighlighting` Adds syntax colours to inline code with a `{:lang}` suffix. Set it to `false` to turn the feature off. - Type: `false | object` - Default: On - Feature: [Inline code highlighting](https://ewels.github.io/starlight-codeblocks/features/inline-code-highlighting/) ## `inlineHighlighting.defaultLanguage` The language of inline code with no suffix. `{:txt}` keeps one piece of inline code plain. - Type: `string | false` - Default: `false` - Feature: [Inline code highlighting](https://ewels.github.io/starlight-codeblocks/features/inline-code-highlighting/) ## `runnable` Adds a button that runs the code in the browser. Set it to `false` to turn the feature off. `runnable` attributes then have no effect. - Type: `false | object` - Default: On - Feature: [Run code](https://ewels.github.io/starlight-codeblocks/features/run-code/) ## `runnable.runtimes` Runtime modules by language: a package path, or a path from the project root. The site entries are added to the built-in Python, JavaScript and TypeScript runtimes, or replace them. - Type: `Record` - Default: `python`, `javascript` and `typescript` - Feature: [Run code](https://ewels.github.io/starlight-codeblocks/features/run-code/) ## `runnable.timeout` Milliseconds before a run stops, from 1 to 2147483647, the largest delay browsers accept. A code block can set its own on its fence line. - Type: `number` - Default: `10000` - Feature: [Run code](https://ewels.github.io/starlight-codeblocks/features/run-code/) ## `runnable.label` The text of the button. A code block can set its own on its fence line. - Type: `string` - Default: `'Run code'` - Feature: [Run code](https://ewels.github.io/starlight-codeblocks/features/run-code/) ## `runnable.againLabel` The text of the button after the first run. A code block can set its own on its fence line. - Type: `string` - Default: `'Run again'` - Feature: [Run code](https://ewels.github.io/starlight-codeblocks/features/run-code/) ## `runnable.button` Where the button goes: under the block, in the title bar, or both. A code block can set its own on its fence line. - Type: `'below' | 'title' | 'both'` - Default: `'below'` - Feature: [Run code](https://ewels.github.io/starlight-codeblocks/features/run-code/) ## `runnable.outputDelay` Milliseconds between the lines of scripted output (`runnable.output`), so that it prints as if the code ran. `0` prints it all at once. A code block can set its own on its fence line. - Type: `number` - Default: `200` - Feature: [Run code](https://ewels.github.io/starlight-codeblocks/features/run-code/)