@shikijs/transformers

Common transformers for Shiki, inspired by shiki-processor.

Install

npm i -D @shikijs/transformers

Usage

import {
  codeToHtml,
} from 'shiki'

import {
  transformerNotationDiff,
  // ...
} from '@shikijs/transformers'

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

Unstyled

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

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

console.log('hewwo')
console.log('hello')
console.log('goodbye')

• // [!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>
    <span class="line"><span>function</span><span>()</span><span></span><span>{</span></span>
    <span class="line diff remove">  <!-- Notice `diff` and `remove` -->
      <span></span><span>console</span><span>.</span><span>log</span><span>(</span><span>&#39;</span><span>hewwo</span><span>&#39;</span><span>) </span>
    </span>
    <span class="line diff add">  <!-- Notice `diff` and `add` -->
      <span></span><span>console</span><span>.</span><span>log</span><span>(</span><span>&#39;</span><span>hello</span><span>&#39;</span><span>) </span>
    </span>
    <span class="line"><span></span><span>}</span></span>
    <span class="line"><span></span></span>
  </code>
</pre>

---

transformerNotationHighlight

Use [!code highlight] to highlight a line.

```ts
console.log('Not highlighted')
console.log('Highlighted') // [!code highlight]
console.log('Not highlighted')
```

Renders (with custom CSS rules):

console.log('Not highlighted')
console.log('Highlighted')
console.log('Not highlighted')

• // [!code highlight] outputs: <span class="line highlighted">
• The outer <pre> tag is modified: <pre class="has-highlighted">

You can also highlight multiple lines with a single comment:

```ts
// [!code highlight:3]
console.log('Highlighted')
console.log('Highlighted')
console.log('Not highlighted')
```

Renders:

console.log('Highlighted')
console.log('Highlighted')
console.log('Not highlighted')

---

transformerNotationWordHighlight

Use [!code word:Hello] to highlight the word Hello in any subsequent code.

```ts
// [!code word:Hello]
const message = 'Hello World'
console.log(message) // prints Hello World
```

Renders (with custom CSS rules):

const message = 'Hello World'
console.log(message) // prints Hello World

Outputs: <span class="highlighted-word">Hello</span> for matched words.

You can also specify the number of lines to highlight words on, e.g. [!code word:Hello:1] will only highlight occurrences of Hello on the next line.

```ts
// [!code word:Hello:1]
const message = 'Hello World'
console.log(message) // prints Hello World
```

Renders:

const message = 'Hello World'
console.log(message) // prints Hello World

---

transformerNotationFocus

Use [!code focus] to focus a line.

```ts
console.log('Not focused');
console.log('Focused') // [!code focus]
console.log('Not focused');
```

Renders (with custom CSS rules):

console.log('Not focused')
console.log('Focused')
console.log('Not focused')

• Outputs: <span class="line focused">
• The outer <pre> tag is modified: <pre class="has-focused">

You can also focus multiple lines with a single comment:

```ts
// [!code focus:3]
console.log('Focused')
console.log('Focused')
console.log('Not focused')
```

Renders:

console.log('Focused')
console.log('Focused')
console.log('Not focused')

---

transformerNotationErrorLevel

Use [!code error] and [!code warning] to mark a line with an error and warning levels.

```ts
console.log('No errors or warnings')
console.error('Error') // [!code error]
console.warn('Warning') // [!code warning]
```

• Outputs: <span class="line highlighted error"> for errors
• Outputs: <span class="line highlighted warning"> for warnings
• The outer <pre> tag is modified: <pre class="has-highlighted">

With some additional CSS rules, you can make it look like this:

console.log('No errors or warnings')
console.error('Error')
console.warn('Warning')

---

transformerRenderWhitespace

Render whitespaces (tabs and spaces) as individual spans, with classes tab and space.

With some additional CSS rules, you can make it look like this:

function block( ) {
  space( )
		tab( ) 
}

Example CSS

.vp-code .tab,
.vp-code .space {
  position: relative;
}

.vp-code .tab::before {
  content: '⇥';
  position: absolute;
  opacity: 0.3;
}

.vp-code .space::before {
  content: '·';
  position: absolute;
  opacity: 0.3;
}

---

transformerMetaHighlight

Highlight lines based on the meta string provided on the code snippet.

```js {1,3-4}
console.log('1')
console.log('2')
console.log('3')
console.log('4')
```

Renders (with custom CSS rules):

console.log('1')
console.log('2')
console.log('3')
console.log('4')

• Outputs: <span class="line highlighted"> for included lines.

transformerMetaWordHighlight

Highlight words based on the meta string provided on the code snippet.

```js /Hello/
const msg = 'Hello World'
console.log(msg)
console.log(msg) // prints Hello World
```

Renders (with custom CSS rules):

const msg = 'Hello World'
console.log(msg) // prints Hello World

Outputs: <span class="highlighted-word">Hello</span> for matched words.

---

transformerCompactLineOptions

Support for shiki's lineOptions that is removed in shiki.

---

transformerRemoveLineBreak

Remove line breaks between <span class="line">. Useful when you set display: block to .line in CSS.