Options

View as Markdown Open in Claude Open in ChatGPT

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

`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

`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

`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<string, { label: string; colour: { dark: string; light: string } }>
Default: {}
Feature: 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

`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

`notation.comments`

Comment syntax for each language, added to the built-in map. An empty list removes a language.

Type: Record<string, string[]>
Default: {}
Feature: 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

`annotations`

Adds numbered markers that open a note. Set it to false to turn the feature off.

Type: false | object
Default: On
Feature: 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

`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

`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

`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

`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

`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

`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

`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

`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

`whitespace`

Shows spaces and tabs as faint glyphs. Set it to false to turn the feature off.

Type: false
Default: On
Feature: 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

`brackets.languages`

Languages that get colourised brackets in every block.

Type: string[]
Default: []
Feature: 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

`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

`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

`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

`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

`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

`swatches.copy`

Copy the colour when the reader clicks it.

Type: boolean
Default: true
Feature: 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

`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

`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

`swatches.byLanguage`

A match and delimiters for the blocks of each language. They replace the site settings for that language.

Type: Record<string, { match?: 'value' | 'all'; delimiters?: { before?: string[]; after?: string[] } }>
Default: {}
Feature: 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

`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

`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

`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<string, { icon?: string | false; colour?: string; style?: 'plain' | 'tile' }>
Default: {}
Feature: 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<string, string | false>
Default: {}
Feature: 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<string, string>
Default: {}
Feature: 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

`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

`apiLinks.adapters`

Adapters that find and resolve names.

Type: ApiLinkAdapter[]
Default: [python(), nextflow()]
Feature: 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

`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

`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

`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

`playgrounds.<name>`

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

`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

`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

`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

`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

`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

`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

`walkthrough`

Animates the code between the steps of a <CodeWalkthrough> component. Set it to false to turn the feature off. <CodeWalkthrough> 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

`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

`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

`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

`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

`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<string, string>
Default: python, javascript and typescript
Feature: 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

`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

`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

`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

`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