@shikijs/transformers

Common transformers for Shiki, inspired by shiki‑processor.

Install

npm i -D @shikijs/transformers

yarn add -D @shikijs/transformers

pnpm add -D @shikijs/transformers

bun add -D @shikijs/transformers

deno add npm:@shikijs/transformers

Usage

import { transformerNotationDiff } from '@shikijs/transformers'
import { codeToHtml } from 'shiki'

const code = `console.log('hello')`

const html = await codeToHtml(code, {
  lang: 'ts',
  theme: 'nord',
  transformers: [
    transformerNotationDiff(),
    // ... other transformers
  ],
})

Unstyled

Transformers only apply classes and do not come with styles; you can provide your own CSS rules to style them properly.

Matching Algorithm

We found that the algorithm for matching comments in v1 is sometimes counter‑intuitive, which we are fixing progressively. Since v1.29.0, we introduced a matchAlgorithm option to most transformers, allowing you to toggle between different matching algorithms.
Right now, the default is v1 (the old algorithm). v3 is the new algorithm, and when Shiki v3 is released, v3 will become the default.

const html = await codeToHtml(code, {
  lang: 'ts',
  theme: 'nord',
  transformers: [
    transformerNotationDiff({
      matchAlgorithm: 'v3', // or 'v1'
    }),
    // ... other transformers
  ],
})

matchAlgorithm: 'v1'

The matching algorithm mostly affects single‑line comment matching. In v1, it counts the comment line as the first line; in v3, it starts counting from the line below the comment.

// [!code highlight:3]
console.log('highlighted')
console.log('highlighted')
console.log('not highlighted')

matchAlgorithm: 'v3'

In v3, the matching algorithm starts counting from the line below the comment.

// [!code highlight:2]
console.log('highlighted')
console.log('highlighted')
console.log('not highlighted')

Transformers

transformerNotationDiff

Use [!code ++] and [!code --] to mark added and removed lines.

```ts
console.log('hewwo') // [!code --]
console.log('hello') // [!code ++]
console.log('goodbye')

Renders (with custom CSS rules):

```ts
<span class="line diff remove">console.log('hewwo')</span>
<span class="line diff add">console.log('hello')</span>
<span class="line">console.log('goodbye')</span>

• // [!code ++] outputs: <span class="line diff add">
• // [!code --] outputs: <span class="line diff remove">
• The outer <pre> tag is modified: <pre class="has-diff">

HTML Output

<!-- Output (stripped of `style` attributes for clarity) -->
<pre class="shiki has-diff"><!-- Notice `has-diff` -->
  <code>
    <span class="line"></span><!-- Notice `diff` and `remove` -->
      <span class="line diff remove"><!-- Notice `diff` and `remove` --></span>
      <span class="line diff remove">console.log('hewwo')</span>
    </span>
    <span class="line diff add"><!-- Notice `diff` and `add` --></span>
      <span class="line diff add">console.log('hello')</span>
    </span>
    <span class="line">console.log('goodbye')</span>
  </code>
</pre>

(Note: The full HTML output is lengthy; only a representative excerpt is shown.)