---
title: "directives"
description: "Use comments to highlight lines and text in a code snippet."
source: https://twinkleplop.pngwn.at/docs/directives
---
# directives

Use comments to highlight lines and text in a code snippet.

Shiki had this brilliant idea of adding annotations to the actual source you are highlighting, in such a way that it doesn't mess with spacing or make the source unreadable.

Twinkleplop is a character of dubious reputation and has stolen this idea.

## what is it tho

Source directives add CSS classes to selected lines or text. They extend [Shiki's notation transformers](https://twinkleplop.pngwn.at/docs/migration#notation) with more ways to select parts of a snippet.

Write directives in comments in the source you want to highlight.

Each directive has a verb, such as `hl` for highlighting, and optional arguments that select the lines or text it applies to.

```ts title="input.ts"
import { add } from "math"

const NUM = 100 // [!del]
const NUM = 50 // [!add]

const v = add(NUM, "hi") // [!err add...*]
```

```ts title="output.ts"
import { add } from "math"

const NUM = 100
const NUM = 50

const v = add(NUM, "hi")
```

## syntax

A directive is `[!verb]` or `[!verb arguments]`, written inside a comment and closed on the same line. A verb starts with a letter and continues with letters, digits, `_` or `-`. The argument form decides what the directive applies to: line numbers select whole lines, anchors select text.

| form | mode | applies to |
| --- | --- | --- |
| `[!verb]` | line | the line the marker is on |
| `[!verb +N]` | line | the N lines below the marker |
| `[!verb :N]` | line | line N of the source |
| `[!verb :N..M]` | line | the lines between N and M, excluding both |
| `[!verb :N...M]` | line | lines N to M, including both |
| `[!verb a..b]` | token | the text between anchors `a` and `b` on the marker's line |
| `[!verb a...b]` | token | from `a` to `b` on the marker's line, including both |
| `[!verb ***]` | token | the code on the marker's line |
| `[!verb =a]` | token | every occurrence of `a` on the marker's line |
| `[!verb =a +N]` | token | every occurrence of `a` in the N lines below; `:N`, `:N..M` and `:N...M` work too |
| `[!verb =a :*]` | token | every occurrence of `a` in the snippet |
| `[!verb a...]` `[!verb ...b]` | token | a pair, from `a` on the opening marker's line to `b` on the closing marker's line; `..` excludes the anchors |
| `[!verb#id a...]` | token | names a pair, so pairs of the same verb can overlap |

There are three anchor formats:

| anchor | matches |
| --- | --- |
| `foo` | the whole word `foo`: letters, digits and `_`, so it does not match inside `foobar` |
| `"foo(bar"` | the exact text, spaces and punctuation included; `\"` and `\\` escape |
| `*` | the start of the line as the first anchor, the end of the line as the second |

- Anchors never match inside a comment, so a marker cannot match its own text.
- A line holding nothing but a marker comment is removed from the output, so a bare `[!verb]` has to follow code on the same line. `:N` line numbers still count removed lines.
- Unconfigured verbs are treated as ordinary comment text.
- A marker with arguments the parser cannot read stays in the output; one whose anchor is not found is removed and applies nothing. Both are reported to the `on_error` option of the annotation config, or with `console.warn` when it is not set.

Example using several directive formats:

```ts title="input.ts"
import { add } from "./math" // [!dim]
// [!hl +2]
const price = 100;
const tax = 20;
const total = add(price, tax); // [!em price...tax]
log(total, total); // [!err =total]
```

```ts title="output.ts"
import { add } from "./math"
const price = 100;
const tax = 20;
const total = add(price, tax);
log(total, total);
```

## using directives

Directives are disabled by default. Enable the ones you need in the highlighter configuration.

The built-in directives select line or token mode based on their arguments. There isn't anything special about this list, I just wanted to make sure there were enough to communicate different semantics.

| plugin | verb | classification | typical use |
| --- | --- | --- | --- |
| `em` | `em` | `emphasis` | draw attention |
| `hl` | `hl` | `highlight` | persistent highlight |
| `focus` | `focus` | `focus` | the lines to look at |
| `dim` | `dim` | `subdued` | fade siblings |
| `add` | `add` | `diff-add` | diff: added |
| `del` | `del` | `diff-del` | diff: removed |
| `mod` | `mod` | `diff-mod` | diff: modified |
| `err` | `err` | `error` | diagnostic squiggle: error |
| `warn` | `warn` | `warning` | diagnostic squiggle: warning |
| `info` | `info` | `info` | diagnostic squiggle: info |
