---
title: "Directives"
description: "Every directive that the plugin reads in code comments, with an example of each."
url: "https://ewels.github.io/starlight-codeblocks/reference/directives/"
markdown: "https://ewels.github.io/starlight-codeblocks/reference/directives.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"
---

# Directives

> Every directive that the plugin reads in code comments, with an example of each.

A directive goes in a comment, in the comment syntax of the language of the block. End-of-line directives apply to the line they are on. Own-line directives take a whole line and apply to the line below it. The [comment notation](https://ewels.github.io/starlight-codeblocks/comment-notation/) page gives the rules that apply to every directive.

## `[!code highlight]`

Marks the line as highlighted, like the `mark` attribute of Expressive Code. With line states on, text after the directive shows as a message.

- Arguments: None
- Feature: [Comment notation](https://ewels.github.io/starlight-codeblocks/comment-notation/)

````md
```js
const host = 'localhost'
const port = 8080 // [!code highlight]
```
````

## `[!code ++]`

Marks the line as inserted, like the `ins` attribute of Expressive Code. With line states on, text after the directive shows as a message.

- Arguments: None
- Feature: [Comment notation](https://ewels.github.io/starlight-codeblocks/comment-notation/)

````md
```js
const host = 'localhost'
const port = 8080 // [!code ++]
```
````

## `[!code --]`

Marks the line as deleted, like the `del` attribute of Expressive Code. With line states on, text after the directive shows as a message.

- Arguments: None
- Feature: [Comment notation](https://ewels.github.io/starlight-codeblocks/comment-notation/)

````md
```js
const host = 'localhost'
const port = 8080 // [!code --]
```
````

## `[!code focus]`

Focuses the line. The other lines are blurred.

- Arguments: None
- Feature: [Focus](https://ewels.github.io/starlight-codeblocks/features/focus/)

````md
```js
const host = 'localhost'
const port = 8080 // [!code focus]
const debug = false
```
````

## `[!code error]`

Marks the line with the "Error" state. Text after the directive becomes the message.

- Arguments: Optional. The message.
- Feature: [Line states](https://ewels.github.io/starlight-codeblocks/features/line-states/)

````md
```js
const retries = -1 // [!code error] Must be 0 or more
```
````

## `[!code warning]`

Marks the line with the "Warning" state. Text after the directive becomes the message.

- Arguments: Optional. The message.
- Feature: [Line states](https://ewels.github.io/starlight-codeblocks/features/line-states/)

````md
```js
const retries = -1 // [!code warning] Must be 0 or more
```
````

## `[!code info]`

Marks the line with the "Note" state. Text after the directive becomes the message.

- Arguments: Optional. The message.
- Feature: [Line states](https://ewels.github.io/starlight-codeblocks/features/line-states/)

````md
```js
const retries = -1 // [!code info] Must be 0 or more
```
````

## `[!code success]`

Marks the line with the "Success" state. Text after the directive becomes the message.

- Arguments: Optional. The message.
- Feature: [Line states](https://ewels.github.io/starlight-codeblocks/features/line-states/)

````md
```js
const retries = -1 // [!code success] Must be 0 or more
```
````

## `[!code note]`

The same as `[!code info]`.

- Arguments: Optional. The message.
- Feature: [Line states](https://ewels.github.io/starlight-codeblocks/features/line-states/)

````md
```js
const retries = -1 // [!code note] Must be 0 or more
```
````

## `[!code warn]`

The same as `[!code warning]`.

- Arguments: Optional. The message.
- Feature: [Line states](https://ewels.github.io/starlight-codeblocks/features/line-states/)

````md
```js
const retries = -1 // [!code warn] Must be 0 or more
```
````

## `[!link]`

Links the first match of `/text/` on the line to the URL. Text after the directive shows in a card on hover and focus.

- Arguments: `/text/` to link, then the URL, then optional text for the card.
- Feature: [Code links](https://ewels.github.io/starlight-codeblocks/features/code-links/)

````md
```js
// [!link /const/ https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/const]
const port = 8080
```
````

## `[!mention]`

Tags the line with a name. A link to `#mention:<name>` in the prose highlights it.

- Arguments: A name for the line.
- Feature: [Code mentions](https://ewels.github.io/starlight-codeblocks/features/code-mentions/)

````md
```js
const base = 1 // [!mention base]
```
````

## `[!code hide]`

Hides the line behind a marker that shows it again.

- Arguments: None
- Feature: [Hidden lines](https://ewels.github.io/starlight-codeblocks/features/hidden-lines/)

````md
```js
const host = 'localhost' // [!code hide]
const port = 8080
```
````

## `[!output]`

Starts the output that the **Run code** button prints instead of running the code. `[!output end]` ends it; without it, the output goes to the end of the block. The block needs no `runnable` and no runtime.

- Arguments: Optional. `end`.
- Feature: [Run code](https://ewels.github.io/starlight-codeblocks/features/run-code/)

````md
```sh
nextflow run hello.nf
# [!output]
Hello world!
```
````

## `[!wait]`

Milliseconds to wait after this line of `[!output]`, before the next line prints.

- Arguments: Milliseconds.
- Feature: [Run code](https://ewels.github.io/starlight-codeblocks/features/run-code/)

````md
```sh
make
# [!output]
Compiling… # [!wait 2000]
Done.
```
````

## `[!callout]`

Shows the text in a bubble above the line, pointing at `/text/` on that line.

- Arguments: Optional. `/text/` to point at. Then the text of the bubble.
- Feature: [Inline callouts](https://ewels.github.io/starlight-codeblocks/features/inline-callouts/)

````md
```js
// [!callout /signal/] Stops the request.
fetch(url, { signal })
```
````

## `[!annotate]`

Adds a numbered marker after the code. Clicking it opens the text in a popover.

- Arguments: The text of the annotation.
- Feature: [Annotations](https://ewels.github.io/starlight-codeblocks/features/annotations/)

````md
```js
const port = 8080 // [!annotate] The default port.
```
````

## `[!ref]`

Adds a numbered badge to the line, and the text to a list under the block.

- Arguments: The text of the footnote.
- Feature: [Footnotes](https://ewels.github.io/starlight-codeblocks/features/footnotes/)

````md
```js
// [!ref] Read from the environment.
const port = process.env.PORT
```
````