@shikijs/transformers
Common transformers for Shiki, inspired by shiki-processor.
Install
npm i -D @shikijs/transformersUsage
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>'</span><span>hewwo</span><span>'</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>'</span><span>hello</span><span>'</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 WorldOutputs: <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 WorldtransformerNotationFocus
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 WorldOutputs: <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.
transformerRemoveNotationEscape
Transform // [\!code ...] to // [!code ...]. Avoid rendering the escaped notation syntax as it is.