Attributes

An attribute goes on the fence line (the first line of the code block), after the language. A flag, such as brackets, is a name on its own. A value is in quotes, as in playground="rust", or in braces for a range or a number, as in focus={2-4}. The comment notation page explains how line numbers count in a range.

The attributes of Expressive Code, such as title, frame, mark, ins, del, wrap and showLineNumbers, keep working as before. The Expressive Code docs describe them.

focus={range}

Focuses the lines in the range. The other lines are blurred.

Feature

Focus

Readers see

const host = 'localhost'
const port = 8080
const debug = false

You write

```js focus={2}
const host = 'localhost'
const port = 8080
const debug = false
```

error={range}, warning={range}, info={range}, success={range}, note={range}, warn={range}

Marks the lines in the range with a line state. note is the same as info, and warn the same as warning. The attribute gives no message. Use a directive for a message.

Feature

Line states

Readers see

const retries = 3
Error:const delay = -1Error
const timeout = 5000

You write

```js error={2}
const retries = 3
const delay = -1
const timeout = 5000
```

<state>={range}

Marks the lines in the range with a custom line state from the lineStates.states option. This site defines todo.

Feature

Line states

Readers see

const host = 'localhost'
To do:const port = 8080To do
const debug = false

You write

```js todo={2}
const host = 'localhost'
const port = 8080
const debug = false
```

hidden={range}

Hides the lines in the range behind a marker. The copy button still copies them.

Feature

Hidden lines

Readers see

Show 2 hidden lines

2 hidden lines
import { readFile } from 'node:fs/promises';

const text = await readFile('config.json', 'utf8');

You write

```js hidden={1-2}
import { readFile } from 'node:fs/promises';

const text = await readFile('config.json', 'utf8');
```

whitespace, whitespace="all"

Shows spaces and tabs as faint glyphs. The flag shows leading whitespace only. "all" shows every space and tab.

Feature

Visible whitespace

Readers see

server:
  port: 8080
  hosts:
    - example.com

You write

```yaml whitespace
server:
  port: 8080
  hosts:
    - example.com
```

brackets, brackets=false

Colours matching brackets by nesting depth. The brackets.languages option turns it on for whole languages, and brackets=false turns it off for one block.

Feature

Colourised brackets

Readers see

const total = items.map((item) => item.price * (1 + tax));

You write

```js brackets
const total = items.map((item) => item.price * (1 + tax));
```

swatches, swatches=false

Shows a swatch before each CSS colour. Swatches are on for every block by default, and swatches=false turns them off for one block. With swatches.languages set, swatches turns them on for a block of another language.

Feature

Colour swatches

Readers see

.button {
  color: #ffffff;
  background: rebeccapurple;
}

You write

```css swatches=false
.button {
  color: #ffffff;
  background: rebeccapurple;
}
```

swatches.shape="square", swatches.shape="rounded", swatches.shape="circle"

Sets the shape of the swatches in the block. It overrides the swatches.shape option for the block.

Feature

Colour swatches

Readers see

.badge {
  background: #2563eb;
}

You write

```css swatches.shape="circle"
.badge {
  background: #2563eb;
}
```

swatches.match="all", swatches.match="value"

Sets which colours get a swatch in the block. "all" shows a swatch for every hex colour and colour function. It overrides the swatches.match option for the block.

Feature

Colour swatches

Readers see

line: main | Main | #4caf50

You write

```text swatches.match="all"
line: main | Main | #4caf50
```

icon="<name>", icon=false, no-icon

Sets the file icon before the title: an icon of the icon set, a Seti icon such as react, or a name from the fileIcons.icons option. icon=false and no-icon remove it.

Feature

File icons

Readers see

vite.config.js

export default {};

You write

```js title="vite.config.js" icon="vite"
export default {};
```

fileIcons.set="seti", fileIcons.set="material", fileIcons.set="vscode-icons", fileIcons.set="catppuccin"

Takes the file icon from vscode-icons, Material Icon Theme, Catppuccin or the Seti icons. It overrides the fileIcons.set option for the block. Material and Catppuccin need their @iconify-json package.

Feature

File icons

Readers see

package.json

{ "name": "my-site" }

You write

```json title="package.json" fileIcons.set="material"
{ "name": "my-site" }
```

fileIcons.style="plain", fileIcons.style="tile"

Shows the file icon alone, or on a square with rounded corners. It overrides the fileIcons.style option for the block.

Feature

File icons

Readers see

app.py

print("Hello")

You write

```py title="app.py" fileIcons.style="tile"
print("Hello")
```

fileIcons.colour="<colour>"

Sets the colour of the file icon, or of the square in the tile style, as a CSS colour such as #3776ab.

Feature

File icons

Readers see

app.py

print("Hello")

You write

```py title="app.py" fileIcons.colour="#3776ab"
print("Hello")
```

wordDiff=false

Turns off word-level diff for the block. Changed lines keep their whole-line tints.

Feature

Word-level diff

Readers see

const port = 3000
const port = 8080

You write

```diff wordDiff=false
-const port = 3000
+const port = 8080
```

apiLinks=false

Turns off API auto-linking for the block. Names stay plain text.

Feature

API auto-linking

Readers see

import json

config = json.loads('{"port": 8080}')

You write

```py apiLinks=false
import json

config = json.loads('{"port": 8080}')
```

pydocsBase="<base>"

Makes the Python adapter link names to the starlight-pydocs package at this base first, such as 1x/api/myproject for an older version. Names that this package does not have link as usual.

Feature

API auto-linking

expandable, expandable={N}, expandable=false

Shows the first lines of the block, with a button to show the rest. The flag shows the number of lines in the expandable.lines option. {N} shows N lines. false turns off the expandable.auto option for the block.

Feature

Expandable blocks

Readers see

name: Build
on: push
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5

Show all 7 lines

You write

```yaml expandable={3}
name: Build
on: push
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
```

playground="<name>"

Adds a button to the title bar that opens the code in a playground. The built-in names are typescript and rust.

Feature

Open in playground

Readers see

Open in TS Playground (opens in a new tab)

const greet = (name: string) => 'Hello, ' + name;

You write

```ts playground="typescript"
const greet = (name: string) => 'Hello, ' + name;
```

id="<id>"

Turns on line numbers, and makes each number a link to its line, as #<id>-L<n>.

Feature

Line permalinks

Readers see

const host = 'localhost'
const port = 8080

You write

```js id="server"
const host = 'localhost'
const port = 8080
```

placeholder="<A>,<B>"

Turns each listed text in the block into an input field. The value that a reader types fills every block on the site.

Feature

Fill-in placeholders

Readers see

export API_TOKEN=YOUR_TOKEN

You write

```sh placeholder="YOUR_TOKEN"
export API_TOKEN=YOUR_TOKEN
```

annotations="side"

Shows the [!annotate] notes of the block in a column beside the code, on wide screens.

Feature

Side annotations

Readers see

const port = 80801
const host = 'localhost'

1. 1Note 1, for line 1: The port that the server listens on.

You write

```js annotations="side"
const port = 8080 // [!annotate] The port that the server listens on.
const host = 'localhost'
```

codeSide="right"

With annotations="side", puts the code in the right column and the notes in the left column. The default is left.

Feature

Side annotations

footnotes="sticky", footnotes="static"

Keeps the list of footnotes at the bottom of the window while the block is on screen, or not. It overrides the footnotes.sticky option for the block.

Feature

Footnotes

Readers see

const port = 8080
const host = 'localhost'

1. 1.The port that the server listens on.

You write

```js footnotes="sticky"
// [!ref] The port that the server listens on.
const port = 8080
const host = 'localhost'
```

startNoteNumber={N}

Numbers the annotations or footnotes of the block from N, not from 1, to continue the numbers of an earlier block.

Feature

Annotations

Readers see

const port = 808012
12
The port that the server listens on.

12. The port that the server listens on.

You write

```js startNoteNumber={12}
const port = 8080 // [!annotate] The port that the server listens on.
```

label="<text>"

Names a variant of a code tabs block. Its tab shows the label if the block has no title, and blocks with the same sync key match by label. It works only on a code block inside a :::code-tabs directive.

Feature

Code tabs

step="<text>"

Gives the label of a step in a <CodeWalkthrough> component. The title bar shows the label after the title.

Feature

Code walkthrough

Readers see

server.jsCreate the app

import express from 'express';

const app = express();

You write

```js title="server.js" step="Create the app"
import express from 'express';

const app = express();
```

runnable

Adds a **Run code** button, which runs the code in the browser and shows the output under the block.

Feature

Run code

Readers see

print(sum([1, 2, 3]))

Run code

You write

```py runnable
print(sum([1, 2, 3]))
```

runnable.label="<text>"

The text of the button of a runnable block. It overrides the runnable.label option for the block.

Feature

Run code

Readers see

print(sum([1, 2, 3]))

Try it

You write

```py runnable runnable.label="Try it"
print(sum([1, 2, 3]))
```

runnable.againLabel="<text>"

The text of the button after the first run. It overrides the runnable.againLabel option for the block.

Feature

Run code

runnable.timeout=<ms>

Milliseconds before a run stops. It overrides the runnable.timeout option for the block.

Feature

Run code

runnable.packages="<name> <name>"

Python packages to install from Pyodide or PyPI before the code runs, separated by spaces. Use it when the package name is not the import name.

Feature

Run code

Readers see

from slugify import slugify
print(slugify("Hello, World!"))

Run code

You write

```py runnable runnable.packages="python-slugify"
from slugify import slugify
print(slugify("Hello, World!"))
```

runnable.button="below", runnable.button="title", runnable.button="both"

Puts the button under the block, in the title bar, or both. It overrides the runnable.button option for the block.

Feature

Run code

runnable.output="<text>"

Output that the button prints instead of running the code, a line at a time. \n starts a new line. The block needs no runtime.

Feature

Run code

Readers see

nextflow run hello

Run code

You write

```sh runnable.output="Downloading…\nDone."
nextflow run hello
```

runnable.outputDelay=<ms>

Milliseconds between the lines of runnable.output. 0 prints them all at once. It overrides the runnable.outputDelay option for the block.

Feature

Run code

focus.style="blur", focus.style="dim"

Blurs and fades the lines outside the focus, or only fades them. It overrides the focus.style option for the block.

Feature

Focus

Readers see

const host = 'localhost'
const port = 8080
const debug = false

You write

```js focus={2} focus.style="dim"
const host = 'localhost'
const port = 8080
const debug = false
```

lineStates.prefix=false, lineStates.prefix=true

Shows the name of the state before each message, or not. It overrides the lineStates.prefix option for the block.

Feature

Line states

Readers see

Error:const retries = -1Must be 0 or more

You write

```js lineStates.prefix=false
const retries = -1 // [!code error] Must be 0 or more
```

shellCopy.prompts="<text>"

A prompt that starts a command in a terminal block, such as shellCopy.prompts="% ". Repeat it for more prompts. It replaces the shellCopy.prompts option for the block.

Feature

Smart shell copy

Readers see

Copy commands

% npm run build
Built in 2.1 s

You write

```sh shellCopy.prompts="% "
% npm run build
Built in 2.1 s
```

wordDiff.minSimilarity=<0-1>

How similar a removed and an added line must be for word-level diff to compare them. It overrides the wordDiff.minSimilarity option for the block.

Feature

Word-level diff

footnotes.sticky=false, footnotes.sticky=true

Keeps the list of footnotes in view while the block is on screen, or not. It overrides the footnotes.sticky option for the block.

Feature

Footnotes

footnotes.style="filled", footnotes.style="outline"

Draws the badges filled in the accent colour, or outlined in the magenta of the theme. It overrides the footnotes.style option for the block.

Feature

Footnotes

Readers see

const port = process.env.PORT

1. 1.Read from the environment.

You write

```js footnotes.style="filled"
// [!ref] Read from the environment.
const port = process.env.PORT
```

annotations.style="filled", annotations.style="outline"

Draws the markers filled in the accent colour, or outlined in the magenta of the theme. It overrides the annotations.style option for the block.

Feature

Annotations

Readers see

const port = 80801
1
The default port.

1. The default port.

You write

```js annotations.style="outline"
const port = 8080 // [!annotate] The default port.
```

expandable.lines=<N>

The lines that the block shows before it expands, when it is expandable. It overrides the expandable.lines option for the block.

Feature

Expandable blocks

placeholders.storage="local", placeholders.storage="session", placeholders.storage="none"

Where the browser keeps the values that readers type into the fields of the block. It overrides the placeholders.storage option for the block.

Feature

Fill-in placeholders