# Shiki ๅผ
[](https://www.npmjs.com/package/shiki)
[](https://www.npmjs.com/package/shiki)
[](https://app.codecov.io/gh/shikijs/shiki/tree)
A beautiful syntax highlighter based on TextMate grammar, accurate and powerful.
[๐ **Documentation**](https://shiki.style)
## Branch
The main branch is currently at _v4.x_.
| Branch | Description |
| ---------------------------------------------- | ---------------------------------- |
| [v3](https://github.com/shikijs/shiki/tree/v3) | v3.23 of Shiki |
| [v2](https://github.com/shikijs/shiki/tree/v2) | v2.5 of Shiki |
| [v1](https://github.com/shikijs/shiki/tree/v1) | v1.29 of Shiki |
| [v0](https://github.com/shikijs/shiki/tree/v0) | v0.14 of Shiki, the legacy version |
## License
[MIT](./LICENSE)
---
### Overview (`packages/cli/README.md`)
# shiki-cli
Shiki in the command line.
[Documentation](https://shiki.style/packages/cli)
## License
MIT
---
### Overview (`packages/codegen/README.md`)
# @shikijs/codegen
Codegen for fine-grained Shiki bundles.
[Documentation](https://shiki.style/packages/codegen)
## License
MIT
---
### Overview (`packages/colorized-brackets/README.md`)
# @shikijs/colorized-brackets
VSCode-style colorized brackets transformer for [Shiki](https://github.com/shikijs/shiki).
[Documentation](https://shiki.style/packages/colorized-brackets)
## License
MIT
---
### Overview (`packages/core/README.md`)
# @shikijs/core
The core functionality of [Shiki](https://github.com/shikijs/shiki), without any grammar of themes bundled.
It's the same as importing `shiki/core`.
---
### Overview (`packages/engine-javascript/README.md`)
# @shikijs/engine-javascript
Engine for Shiki using JavaScript's native RegExp. Uses [Oniguruma-To-ES](https://github.com/slevithan/oniguruma-to-es) to transpile regex syntax and behavior.
[Documentation](https://shiki.style/guide/regex-engines)
## License
MIT
---
### Overview (`packages/engine-oniguruma/README.md`)
# @shikijs/engine-oniguruma
Engine for Shiki using Oniguruma RegExp engine in WebAssembly.
[Documentation](https://shiki.style/guide/regex-engines)
## License
MIT
---
### Overview (`packages/langs-precompiled/README.md`)
# @shikijs/langs-precompiled
Precompiled languages for Shiki that can runs in pure JavaScript environment.
Requires ES2024+ environment.
> **Experimental**
## Unsupported Languages
## License
MIT
---
### Overview (`packages/langs/README.md`)
# @shikijs/langs
TextMate grammars for Shiki.
## License
MIT
---
### Overview (`packages/magic-move/README.md`)
# @shikijs/magic-move
Smoothly animated code blocks with [shiki](https://github.com/shikijs/shiki). Useful for code-step animations in slide decks (e.g. [Slidev](https://sli.dev/guide/syntax#shiki-magic-move)) and tutorials.
[Documentation](https://shiki.style/packages/magic-move)
## License
MIT
---
### Overview (`packages/markdown-exit/README.md`)
# @shikijs/markdown-exit
[markdown-exit](https://github.com/serkodev/markdown-exit) plugin for [shiki](https://github.com/shikijs/shiki)
[Documentation](https://shiki.style/packages/markdown-exit)
## License
MIT
---
### Overview (`packages/markdown-it/README.md`)
# @shikijs/markdown-it
[markdown-it](https://markdown-it.github.io/) plugin for [shiki](https://github.com/shikijs/shiki)
[Documentation](https://shiki.style/packages/markdown-it)
## License
MIT
---
### Overview (`packages/monaco/README.md`)
# @shikijs/monaco
Use [shiki](https://github.com/shikijs/shiki) to highlight [Monaco Editor](https://microsoft.github.io/monaco-editor/).
[Documentation](https://shiki.style/packages/monaco)
## License
MIT
---
### Overview (`packages/rehype/README.md`)
# rehype-shiki
[rehype](https://github.com/rehypejs/rehype) plugin for [shiki](https://github.com/shikijs/shiki).
[Documentation](https://shiki.style/packages/rehype)
## License
MIT
---
### Overview (`packages/shiki/README.md`)
bar
', {
lang: 'html',
theme: 'min-dark'
})
```
```ts twoslash theme:catppuccin-mocha
// @twoslash-cache: {"v":1,"hash":"c2d38cc11de83aa2f1d11651d47d604c307a1a81460c52619a8483484bbcdeb6","data":"N4Igdg9gJgpgziAXAbVAFwJ4AcZJACwgDcYAnEAGhDRgA808AKAQwBsBLZuASgAIBjCGDhoB0GABUIACS5pEvRoNgKRpdmADmFXhCxp2QuAoDC4qbJEB5fYeEAeAEIBXMFFYwoAGWZbnzTRgdFzcPKAl8GABbGAA+PgBeWN4ABVIIKPY4GHsAJQgINFiAHTB2KKwIUlFlSRk5ShARZmqkAE4qDy00fCQARgAGKjQWwIZEEFqLBs6NXEQhyfwW5n4ackQ2gF8KdGx5gmIyRpp6PEFhUWWRBXzCxubWxAAWACZOmG7el+HRmHGCDMQBwwPN3ksVmtjogAGw7PY4PCEEjkYZ0AEsDhcPhTeoiJTiVRodRaHR6AxGUzmPFoGwUhwhdyeHx+AJBXiMsIRaJxbgKNIZLI5O5FUrlSrVMSwaYiB4jJ4AVgVHy+/UW8rG52plgYs1BSHB/GWpFW6362121H2SKOqOo6KYWHSOGqGD4rF8mgUxUmcDgPrlLXGbQ6wM+mh6SGev1ImomHq0jRB8wAzFQjZCzYhXvCrYiJsjjmizhNGE69GRMHwzLA6XY4ABlDSaDzcmJOVxM8KRGKxAB0PR5CjbMFyME0WWJzHpAEEwBheAAfXgN4nNrzsdZsACqZSEHdCnhHOjUzdigaefT60bDqsQyuofwBg5iSbmUfTxtN0JzAF10+IeDilUojAFKdQ6rwWy8AAZukUS8AA5HA+DsAA1uwiGlKUFwiLw1yiAkvDMAA7swm7gTKaCMIhA7ogAtKQni8GBgisFUChMVAADcUGITowClLwvAJl6SH8H6/FCbwL4wAoiH8NOWBYM4/D8Bo9FRBAGZYWAWzcI0MQjEgoDop8cB2HgaAIFsWxAA=="}
import { codeToHast } from 'shiki'
const hast = await codeToHast('.text-red { color: red; }', {
lang: 'css',
theme: 'catppuccin-mocha'
})
```
### Highlighter Usage
The [shorthands](#shorthands) we provided are executed asynchronously as we use WASM and load themes and languages on demand internally. In some cases, you may need to highlight code synchronously, so we provide the `createHighlighter` function to create a highlighter instance that can later be used synchronously.
The usage is pretty much the same as with `codeToHtml`, where each theme and language file is a dynamically imported ES module. It would be better to list the languages and themes **explicitly** to have the best performance.
```
/* Detailed source-code truncated for AI context efficiency. */
```
:::info Important Note
Highlighter instance should be **long-lived singleton**. You might need to cache it somewhere and reuse it across your application. Avoid calling `createHighlighter` in hot functions or loops.
If running on Node.js, we recommend using the [Shorthands](#shorthands) which manages the highlighter instance and dynamic theme/language loading for you.
:::
Additionally, if you want to load themes and languages after the highlighter is created, you can use the `loadTheme` and `loadLanguage` methods.
```ts twoslash
// @twoslash-cache: {"v":1,"hash":"8ce2944f34901319a707c331109f0ab6777c21709e2685cf9e4136e2d0985b06","data":"N4Igdg9gJgpgziAXAbVAFwJ4AcZJACwgDcYAnEAGhDRgA808BjCMONAAnwEsBzfAG174apROwASQwXxEBxGGDJdGAHgBCAVzBR+MKABkAhmB4bDPGBXabtuqABV8MALYwAfJRBtDpBogCsAAxUuiZo+EgAjJFUaD4WfgRSQiKegopRVIz4PoaMqYgAbAC+FOjYuIgExGSeNPR4ABRYpBA4vhgAlOwAytwA1lwAkmAiYIb86lo6ekYmZhZWNjMOTq5uAHT8EIarLjBijRvH4ftwh8t2jvvsAD7s164jWBoc9wA64Cwwn53IALrdAC8bnYAAVWs4uHAYCoiBAuFAPFQoBBGAgqvodlB2IZ2KdXPiIPinJxkjIyFY4MT+IYROwuBxGMZ2AAjGDsDQwnFwDBgbKtSBc/gYDaeby+JCFABMIQUPHCSAAnLF4jBEttdo9cCEuBlEDEQNlcvlagaABylco4PCEEjkWJ0RLMVgcbh8aTCMhiSQelJkeSKUjKKa2WbGUzmSzWaZXNbucVxSWIJX+OVhCIGw1JhK28leh0gdKVWVGnKkPIFEplagVW01Qv1RLNVrtTDdPpcQYjMYTUMrOaRxYxsN7dZbbGDhYHdhHY60kznWeXcPzKN3dhTqPPV4bno4RhcCZbix/QHsEHgyHQ2HwxHIkCo9F4LG7XHsBdDjloYmnMl+ilSCpGk6TIBkmRZdlOW5dheX5fBBQgYVRUTHw/EiQIAHZ0wVTNIlLHN1TwTUDAjac0j1EssnLSszUiS1/iyaBKhAAB6ViP2xEkzlxbQPzIqM4FxAAzelGFIGA6S4Fh3nGAB3QxGX/AR/VICctXjRoAHIiEZeAYQAWk9NAtM6WTDAUpT3RUwD1NItcLG09E4FMzxXDiJBQCdBQ4GksA8DQBBimKIA=="}
import { createHighlighter } from 'shiki'
const highlighter = await createHighlighter({ themes: [], langs: [] })
// ---cut---
// load themes and languages after creation
await highlighter.loadTheme('vitesse-light')
await highlighter.loadLanguage('css')
```
Since Shiki v1.0, it requires all themes and languages to be loaded explicitly.
```
/* Detailed source-code truncated for AI context efficiency. */
```
If you want to load all themes and languages (not recommended), you can iterate over all keys from `bundledLanguages` and `bundledThemes`.
```
/* Detailed source-code truncated for AI context efficiency. */
```
### Fine-grained Bundle
When importing `shiki`, all the themes and languages are bundled as async chunks. Normally it won't be a concern to you as they are not being loaded if you don't use them. In some cases, if you want to control what to bundle, you can use the core and compose your own bundle.
Check out the [Fine-grained Bundle](/guide/bundles#fine-grained-bundle) section for more details.
### Bundle Presets
We also provide some pre-composed bundles for you to use easily, you can learn more about them in the [bundles section](/guide/bundles).
### CJS Usage
`shiki` is published as ESM-only to reduce the package size. It's still possible to use it in CJS, as Node.js supports importing ESM modules dynamically in CJS.
For example, the following ESM code:
```
/* Detailed source-code truncated for AI context efficiency. */
```
Can be written in CJS as:
```
/* Detailed source-code truncated for AI context efficiency. */
```
### CDN Usage
To use `shiki` in the browser via CDN, you can use [esm.run](https://esm.run) or [esm.sh](https://esm.sh).
```html theme:rose-pine
```
It's quite efficient as it will only load the languages and themes on demand. For the code snippet above, only four requests will be fired (`shiki`, `@shikijs/themes/vitesse-light`, `@shikijs/langs/javascript`, `shiki/wasm.mjs`), with around 200KB data transferred in total.
[Demo](https://jsfiddle.net/t7brz23v/)
### Cloudflare Workers
Cloudflare Workers [does not support initializing WebAssembly from binary data](https://community.cloudflare.com/t/fixed-cloudflare-workers-slow-with-moderate-sized-webassembly-bindings/184668/3), so the default wasm build won't work. You need to upload the wasm as assets and import it directly.
Meanwhile, it's also recommended to use the [Fine-grained Bundle](#fine-grained-bundle) approach to reduce the bundle size.
```
/* Detailed source-code truncated for AI context efficiency. */
```
---
### Guide Load Lang (`docs/guide/load-lang.md`)
# Load Custom Languages
See [All Builtin Languages](/languages) first.
You can load custom languages by passing a TextMate grammar object into the `langs` array.
```
/* Detailed source-code truncated for AI context efficiency. */
```
You can also load languages after the highlighter has been created.
```
/* Detailed source-code truncated for AI context efficiency. */
```
## Migrate from v0.14
Since v1.0, `shiki` now is environment agnostic, we don't have access to the file system. That means the `path` property `shiki@0.14` supports is not available in v1.0, and you must to read the files yourself and pass in the object.
For example, the following would not work:
```ts
const highlighter = await createHighlighter({
langs: [
{
name: 'vue-vine',
scopeName: 'source.vue-vine',
// โผ๏ธ This would not work!
path: join(__dirname, './vine-ts.tmLanguage.json'),
embeddedLangs: [
'vue-html',
'css',
'scss',
'sass',
'less',
'stylus',
],
},
],
themes: []
})
```
Instead, load that file yourself (via `fs`, `import()`, `fetch()`, etc.):
```ts
const vineGrammar = JSON.parse(fs.readFileSync(join(__dirname, './vine-ts.tmLanguage.json'), 'utf8'))
const highlighter = await createHighlighter({
langs: [
{
name: 'vue-vine',
scopeName: 'source.vue-vine',
embeddedLangs: [
'vue-html',
'css',
'scss',
'sass',
'less',
'stylus',
],
...vineGrammar
},
],
themes: []
})
```
## Custom Language Aliases
You can register custom language aliases with the `langAlias` option. For example:
```
/* Detailed source-code truncated for AI context efficiency. */
```
---
### Guide Load Theme (`docs/guide/load-theme.md`)
# Load Custom Themes
See [All Builtin Themes](/themes) first.
You can load custom themes by passing a `Theme` object into the `themes` array.
```
/* Detailed source-code truncated for AI context efficiency. */
```
You can also load themes after the highlighter has been created.
```
/* Detailed source-code truncated for AI context efficiency. */
```
The theme is a TextMate theme in JavaScript object. For example, [it should look like this](https://github.com/antfu/textmate-grammars-themes/blob/main/packages/tm-themes/themes/dark-plus.json).
---
### Guide Migrate (`docs/guide/migrate.md`)
---
outline: deep
---
# Migration
We suggest you to migrate step by step, following each version's migration guide.
## Migrate from v3.0
If you are on v3.0, v4.0 only drops support for Node.js 18 and remove deprecated APIs, so you should be able to directly bump to v4.0. Read [Shiki v4.0](/blog/v4) for more details.
## Migrate from v2.0
If you are on v2.0 and there is no warning in your usage, you should be able to directly bump to v3.0, read [Shiki v3.0](/blog/v3) for more details.
## Migrate from v1.0
We recommend you to [migrate to v2.0 first](/blog/v2), then to v3.0.
## Migrate from v0.14
The v1.0 release of Shiki is a major rewrite that we took the chance to revise every design decision we made in the past. We originally had a separate package name as [Shikiji](https://github.com/antfu/shikiji) to experiment with the new design, now it's merged back to Shiki as v1.0.
> [!TIP] Learn more
> Interested in the story behind v1.0? Check out this [blog post](https://nuxt.com/blog/shiki-v1) for more details.
Compare to [`shiki@0.14.3`](https://github.com/shikijs/shiki/releases/tag/v0.14.3), the list of breaking changes are:
### Hard Breaking Changes
Breaking changes that you need to migrate manually:
- CJS and IIFE builds are dropped. See [CJS Usage](/guide/install#cjs-usage) and [CDN Usage](/guide/install#cdn-usage) for more details.
- `codeToHtml` uses [`hast`](https://github.com/syntax-tree/hast) internally. The generated HTML will be a bit different but should behave the same.
- `css-variables` theme is no longer supported. Use the [dual themes](/guide/dual-themes) approach instead, or learn more at the [Theme Colors Manipulation](/guide/theme-colors) page.
### Soft Breaking Changes
Breaking changes applies to main package `shiki`, but are shimmed by the [compatible build `@shikijs/compat`](/guide/compat#compatibility-build):
- Top-level named exports `setCDN`, `loadLanguage`, `loadTheme`, `setWasm` are dropped as they are not needed anymore.
- `BUNDLED_LANGUAGES`, `BUNDLED_THEMES` are moved to `@shikijs/langs` and `@shikijs/themes` and renamed to `bundledLanguages` and `bundledThemes` respectively.
- `theme` option for `createHighlighter` is dropped, use `themes` with an array instead.
- Highlighter does not maintain an internal default theme context. `theme` option is required for `codeToHtml` and `codeToTokens`.
- `codeToThemedTokens` is renamed to `codeToTokensBase`, a higher level `codeToTokens` is added.
- `codeToTokens` sets `includeExplanation` to `false` by default.
- `.ansiToHtml` is merged into `.codeToHtml` as a special language, `ansi`. Use `.codeToHtml(code, { lang: 'ansi' })` instead.
- `lineOptions` is dropped in favor of the fully customizable `transforms` option.
- `LanguageRegistration`'s `grammar` field is flattened to `LanguageRegistration` itself, refer to the types for more details.
### Ecosystem Packages
- `shiki-twoslash` has been completely rewritten. It's no longer a wrapper around Shiki highlighter, but instead, it's now a Shiki transformer that can be plugged in any integrations that supports SHiki transformers. The package is now [`@shikijs/twoslash`](/packages/twoslash).
- Integrations of `shiki-twoslash`, like `gatsby-remark-shiki-twoslash` etc, will be slowly moved to a general Shiki version. Before that, you can use [`@shikijs/rehype`](/packages/rehype) or [`@shikijs/markdown-it`](/packages/markdown-it) to integrate Shiki into those meta-frameworks.
- New official integrations like [`@shikijs/monaco`](/packages/monaco), [`@shikijs/cli`](/packages/cli), [`@shikijs/rehype`](/packages/rehype), [`@shikijs/markdown-it`](/packages/markdown-it) are introduced.
- `shiki-renderer-path` and `shiki-renderer-svg` packages are being deprecated due to low usage. If need them, please open an issue with your use case, we are open to bring them back.
- `vuepress-plugin-shiki` is deprecated as [VuePress](https://github.com/vuejs/vuepress#status) is no longer recommended. Its successor [VitePress](https://vitepress.dev/) has a built-in Shiki integration.
## Migrate from Shikiji
If you are already using [Shikiji](https://github.com/antfu/shikiji), first make sure you are on the latest minor v0.10. Then the migration should be very straightforward by renaming the packages:
- `shikiji` -> `shiki`
- `shikiji-core` -> `@shikijs/core`
- `shikiji-twoslash` -> `@shikijs/twoslash`
- `shikiji-transformers` -> `@shikijs/transformers`
- `shikiji-monaco` -> `@shikijs/monaco`
- `shikiji-cli` -> `@shikijs/cli`
- `markdown-it-shikiji` -> `@shikijs/markdown-it`
- `rehype-shikiji` -> `@shikijs/rehype`
---
### Guide Regex Engines (`docs/guide/regex-engines.md`)
---
outline: deep
---
# RegExp Engines
TextMate grammars are based on regular expressions that match tokens. More specifically, they assume that [Oniguruma](https://github.com/kkos/oniguruma) (a powerful regex engine written in C) will be used to interpret the regular expressions. To make this work in JavaScript, we compile Oniguruma to WebAssembly to run in the browser or Node.js.
Shiki also offers the ability to switch the regex engine or provide a custom implementation. To do so, add an `engine` option to `createHighlighter` or `createHighlighterCore`. For example:
```ts
import { createHighlighter } from 'shiki'
const shiki = await createHighlighter({
themes: ['nord'],
langs: ['javascript'],
engine: { /* custom engine */ }
})
```
Shiki comes with two built-in engines:
## Oniguruma Engine
This is the default engine that uses the compiled Oniguruma WebAssembly.
```ts
import { createHighlighter } from 'shiki'
import { createOnigurumaEngine } from 'shiki/engine/oniguruma'
const shiki = await createHighlighter({
themes: ['nord'],
langs: ['javascript'],
engine: createOnigurumaEngine(import('shiki/wasm'))
})
```
## JavaScript RegExp Engine
This engine uses JavaScript's native `RegExp`. Since regular expressions used by TextMate grammars are written for Oniguruma, we use [Oniguruma-To-ES](https://github.com/slevithan/oniguruma-to-es) to transpile Oniguruma patterns to native JavaScript regexes.
```ts {2,4,9}
import { createHighlighter } from 'shiki'
import { createJavaScriptRegexEngine } from 'shiki/engine/javascript'
const jsEngine = createJavaScriptRegexEngine()
const shiki = await createHighlighter({
themes: ['nord'],
langs: ['javascript'],
engine: jsEngine
})
const html = shiki.codeToHtml('const a = 1', { lang: 'javascript', theme: 'nord' })
```
The advantage of using the JavaScript engine is that it doesn't require loading a large WebAssembly file for Oniguruma. It is also faster for some languages, since the regular expressions run as native JavaScript.
Please check the [compatibility table](/references/engine-js-compat) for the support status of languages you are using. As of Shiki 3.9.1, all built-in languages are supported.
::: info
The JavaScript engine is best when running in the browser and in cases when you want to control the bundle size. If you run Shiki on Node.js (or at build time) and bundle size or WebAssembly support is not a concern, the Oniguruma engine ensures maximum language compatibility.
:::
### Use with Unsupported Languages
Unlike the Oniguruma engine, the JavaScript engine is strict by default. It will throw an error if it encounters an invalid Oniguruma pattern or a pattern that it cannot convert. If you want best-effort results for unsupported grammars, you can enable the `forgiving` option to suppress any conversion errors:
```ts
const jsEngine = createJavaScriptRegexEngine({ forgiving: true })
// ...use the engine
```
This can result in highlighting mismatches, so check your results.
### JavaScript Runtime Target
For best results, the JavaScript engine uses the [RegExp `v` flag](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/unicodeSets), which is available in Node.js v20+ and ES2024 ([browser compatibility](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/unicodeSets#browser_compatibility)). For older environments, it automatically uses the `u` flag instead, but this results in a few less grammars being supported.
By default, the runtime target is automatically detected. You can override this behavior by setting the `target` option:
```ts
const jsEngine = createJavaScriptRegexEngine({
target: 'ES2018', // or 'auto' (default), 'ES2024', 'ES2025'
})
```
### Pre-compiled Languages
Instead of compiling regular expressions on-the-fly, we also provide pre-compiled languages for the JavaScript engine to further reduce startup time.
::: warning
Pre-compiled languages are not yet supported, due to a [known issue](https://github.com/shikijs/shiki/issues/918) that affects many languages. Please use with caution.
:::
::: info
Pre-compiled languages require support for RegExp UnicodeSets (the `v` flag), which requires ES2024 or Node.js 20+, and may not work in older environments. [Can I use](https://caniuse.com/mdn-javascript_builtins_regexp_unicodesets).
:::
You can install them with `@shikijs/langs-precompiled`, and change your `@shikijs/langs` imports to `@shikijs/langs-precompiled`:
```ts
import { createHighlighterCore } from 'shiki/core'
import { createJavaScriptRawEngine } from 'shiki/engine/javascript'
const highlighter = await createHighlighterCore({
langs: [
import('@shikijs/langs/javascript'), // [!code --]
import('@shikijs/langs/typescript'), // [!code --]
import('@shikijs/langs-precompiled/javascript'), // [!code ++]
import('@shikijs/langs-precompiled/typescript'), // [!code ++]
// ...
],
themes: [
import('@shikijs/themes/nord'),
],
engine: createJavaScriptRegexEngine(), // [!code --]
engine: createJavaScriptRawEngine(), // [!code ++]
})
```
If you are not using custom grammars that require transpilation, you can use `createJavaScriptRawEngine` to skip the transpilation step, further reducing bundle size.
If you are using [`shiki-codegen`](/packages/codegen), you can generate pre-compiled languages with the `--precompiled` and `--engine=javascript-raw` flags.
---
### Guide Shorthands (`docs/guide/shorthands.md`)
# Shorthands
The easier way to get started with `shiki` is to use the provided shorthand functions. These will load the necessary themes and languages on demand, and automatically cache them in memory. Different from `createHighlighter` and `createHighlighterCore`, the operations are asynchronous.
```
/* Detailed source-code truncated for AI context efficiency. */
```
## Create Shorthands with Fine-Grained Bundles
You can create your own shorthands with fine-grained bundles. Here is an example of creating shorthands with fine-grained bundles:
```ts
import { createBundledHighlighter, createSingletonShorthands } from 'shiki/core'
import { createJavaScriptRegexEngine } from 'shiki/engine/javascript'
const BundledLanguage = {
typescript: () => import('@shikijs/langs/typescript'),
javascript: () => import('@shikijs/langs/javascript'),
vue: () => import('@shikijs/langs/vue'),
}
const BundledTheme = {
'light-plus': () => import('@shikijs/themes/light-plus'),
'dark-plus': () => import('@shikijs/themes/dark-plus'),
}
// This creates your custom 'createHighlighter' function with fine-grained bundles
export const createHighlighter = /* @__PURE__ */ createBundledHighlighter<
BundledLanguage,
BundledTheme
>({
langs: bundledLanguages,
themes: bundledThemes,
engine: () => createJavaScriptRegexEngine(),
})
// This creates the shorthands for you
export const {
codeToHtml,
codeToHast,
codeToTokensBase,
codeToTokens,
codeToTokensWithThemes,
getSingletonHighlighter,
getLastGrammarState,
} = /* @__PURE__ */ createSingletonShorthands(
createHighlighter,
)
```
You can also use [`shiki-codegen`](/packages/codegen) to generate the fine-grained bundles for you.
---
### Guide Sync Usage (`docs/guide/sync-usage.md`)
# Synchronous Usage
The `await createHighlighter()` and `highlighter.codeToHtml()` are already the effort to do the separations of asynchronism and synchronism. For most of the cases, you should be able to resolve the async part in the initialization phase and use the highlighter synchronously later.
In some extreme cases that you need to run Shiki completely synchronously, since v1.16, we provide a synchronous version of the core API. You can use `createHighlighterCoreSync` to create a highlighter instance synchronously.
```ts
import js from '@shikijs/langs/javascript'
import nord from '@shikijs/themes/nord'
import { createHighlighterCoreSync } from 'shiki/core'
import { createJavaScriptRegexEngine } from 'shiki/engine/javascript'
const shiki = createHighlighterCoreSync({
themes: [nord],
langs: [js],
engine: createJavaScriptRegexEngine()
})
const html = shiki.highlight('console.log(1)', { lang: 'js', theme: 'nord' })
```
When doing so, it requires all `themes` and `langs` to be provide as plain objects. Also an explicit `engine` is required to be provided. With the new [JavaScript RegExp engine](/guide/regex-engines#javascript-regexp-engine) you are able to create an engine instance synchronously as well.
The [Oniguruma Engine](/guide/regex-engines#oniguruma-engine) can only be created asynchronously, so you need to resolve the engine promise before creating the sync highlighter.
```ts
import js from '@shikijs/langs/javascript'
import nord from '@shikijs/themes/nord'
import { createHighlighterCoreSync } from 'shiki/core'
import { createOnigurumaEngine } from 'shiki/engine/oniguruma'
// Load this somewhere beforehand
const engine = await createOnigurumaEngine(import('shiki/wasm'))
const shiki = createHighlighterCoreSync({
themes: [nord],
langs: [js],
engine, // if a resolved engine passed in, the rest can still be synced.
})
const html = shiki.highlight('console.log(1)', { lang: 'js', theme: 'nord' })
```
---
### Guide Theme Colors (`docs/guide/theme-colors.md`)
# Theme Colors Manipulation
## Arbitrary Color Values
Usually, TextMate themes expect the color values of each token to be a valid hex color value. This limitation is inherited from [`vscode-textmate`](https://github.com/microsoft/vscode-textmate). However, in Shiki v0.9.15 we introduced an automatic workaround by replacing non-hex color values with a placeholder and replacing them back on tokenization. This would allows you to use themes with arbitrary color values for rendering without worrying about the technical details:
```
/* Detailed source-code truncated for AI context efficiency. */
```
::: info Notice
Use this carefully as this will diverge from TextMate theme compatibility.
This may make the theme incompatible with non-web usage such as [`shiki-cli`](/packages/cli) and [`shiki-monaco`](/packages/monaco).
:::
Learn more about how to [load themes](./load-theme).
## Color Replacements
You can also use the `colorReplacements` option to replace the color values of the theme. This is useful when you want to use a theme with a different color palette. It can be provided on both the theme object and the `codeToHast` `codeToHtml` options.
The `colorReplacements` object should follow a color-to-color format, where the keys represent the color to be replaced and the value represents the new color:
```js
const html = await codeToHtml(
code,
{
lang: 'js',
theme: 'min-dark',
colorReplacements: {
'#ff79c6': '#189eff'
}
}
)
```
In addition, `colorReplacements` may contain scoped replacements. This is useful when you provide multiple themes and want to replace the colors of a specific theme:
```js
const html = await codeToHtml(
code,
{
lang: 'js',
themes: { dark: 'min-dark', light: 'min-light' },
colorReplacements: {
'min-dark': {
'#ff79c6': '#189eff'
},
'min-light': {
'#ff79c6': '#defdef'
}
}
}
)
```
This is only allowed for the `colorReplacements` option and not for the theme object.
## CSS Variables Theme
Shiki provides a factory function helper `createCssVariablesTheme` for creating a theme that uses CSS variables easier. Note that this theme is a lot less granular than most of the other themes and requires to define the CSS variables in your app. This is provided for easier migration from Shiki's [`css-variables theme`](https://github.com/shikijs/shiki/blob/main/docs/themes.md#theming-with-css-variables). For better highlighting result, we recommend construct the theme manually with [Arbitrary Color Values](#arbitrary-color-values) or use [Color Replacements](#color-replacements) to override an existing theme.
This theme is **not included by default** and must be registered explicitly:
```
/* Detailed source-code truncated for AI context efficiency. */
```
CSS variables example:
```
/* Detailed source-code truncated for AI context efficiency. */
```
If you are migrating from Shiki v0, some variables are renamed:
| Shiki v0 | Shiki v1.0 |
| -------------------------- | -------------------- |
| `--shiki-color-text` | `--shiki-foreground` |
| `--shiki-color-background` | `--shiki-background` |
| `--shiki-color-ansi-*` | `--shiki-ansi-*` |
---
### Guide Transformers (`docs/guide/transformers.md`)
# Transformers
Shiki uses [`hast`](https://github.com/syntax-tree/hast), a AST format for HTML, to process the result and generate the HTML.
You can provide your own `transformers` to customize the generated HTML by manipulating the hast tree. You can pass custom functions to modify the tree for different types of nodes. For example:
```
/* Detailed source-code truncated for AI context efficiency. */
```
We also provide some common transformers for you to use, see [`@shikijs/transformers`](/packages/transformers) and [`@shikijs/colorized-brackets`](/packages/colorized-brackets) for more details.
## Transformer Hooks
```mermaid
flowchart LR
preprocess --> tokens
tokens --> span
span --> span
span --> line
line --> span
line --> code
code --> pre
pre --> root
root --> postprocess
```
- `preprocess` - Called before the code is tokenized. You can use this to modify the code before it is tokenized.
- `tokens` - Called after the code is tokenized. You can use this to modify the tokens.
- `span` - Called for each `` tag, for each token.
- `line` - Called for each line `` tag.
- `code` - Called for each `` tag, wraps all the lines.
- `pre` - Called for each `` tag, wraps the `` tag.
- `root` - The root of HAST tree. Usually with only one child `` tag.
- `postprocess` - Called after the HTML is generated, get a chance to modify the final output. Will not be called in `codeToHast`.
## Meta
Transformers can also access markdown 'meta' strings in [supported integrations](/guide/install#integrations).
````markdown
```html foo=bar baz-qux="qu ux"
````
You can access the raw meta using:
```ts
this.options.meta
// => { __raw: 'foo=bar baz-qux="qu ux"' }
```
## Enforcing Transformer Ordering
For compatibility or fine-grained control, it may be necessary to enforce the order of a Shiki transformer. You can control the position of a transformer with the `enforce` modifier:
- `pre`: invoked before normal transformers
- default: invoked as a normal transformers
- `post`: invoked after normal transformers
Example:
```ts twoslash
// @twoslash-cache: {"v":1,"hash":"8d7b272af17166c83782bdb0d9e41de0f75c878526f69245c6e6021e1a4bfa45","data":"N4Igdg9gJgpgziAXAbVAFwJ4AcZJACwgDcYAnEAGhDRgA808AKAQwBsBLZuASgAJ2wNUgDNmAYxi8AyvnYBrdgBVSzMHGERSAWzIAdMOy1ZNaabIXLV6zTvJU4aZqQaIAjABYqrGGADmafCRXADYqR1JfGBcQGXklFTUNbTJKEA4wXEQABioxfCdxISD3AF8KdGxMgmIUsLposQg1UzEAVwcILUtEmzJEMzju62S7EAcnFwBWAGYvH39AtwB2MKdIhva0TqGk21T0zIAmXPyVMSLEYLKKnDxCElGaeiY2Th5+QTJRCQGLBOHbPpDMZnL94lZdrUxuEXEtjml5gEgqFqGsonhYn8Ib1RgckPC8gVzilEIdJtdqJU7jVHvUmFhSBAcM4MHxMeCeiMAHRgZg6AD8/QcpAEvl4AB9eK0wLBhAIYFBUlAIGIEIgQAA5PmSCDCXgBSRof6Q0bjZxIACckzmfiRiE8qIi6PVvJ0+3lSFmIEJZwuhwpmFu6vuUKe0UYDKZZEwbPMHIBZC5PiSEkFvF0IAZMAzEvTmYgDhzkulsvliqoytVeAAomAU5IsKxWr4BB8iCrmGh2E19ewyLw4IZ2KwnPqILwAO4wABGWHEcl4rAgzFgpDgXN4AAkIBA5HBeJpV6KgfuHMPWAPWtOAFYwc5j/X4SQAA0PZGfvEjzMwH0fkkIu4Hjed5oFy+j6AACk2LZgG2HZdj2b6kIg+gALS8M+yaaBI/QAORZrhH6Ns2AhwGhvCQNobCftBpHkZhdbYTAeHGA4hE0SRajkXAcafgWpjETBCD2DCQSHK4NoLEgKyOuseBYaQEjuhkSAOj6hQkv65SUkG1QPKkYb0oy36smCOw4lyjSwGmjCMAE7BwP07LmSMADCTRhhQvD5A4/TVt4OiCHwAC8AB8vD+TAgWmJK7bsFAfDFjKMByhk5YgJWaogC5Wh/hhAA8VkwKFH4wAFPigbwABKUStKQsHMBRMATrwGrQJIE7nrwpAwI24iGk+B4ijB1FNDAXKpGaLiuNMFqSXaDrhHJ6pFcpmTWt6pwaeQpIBlSwY0gZdLqhGBQ6EIfCQLAfnlYIk2iW47gOt4tqLItaLRFduBeB6iAbepxI7UsJQALq5O1eDAiY+qVLwwBmcaOK8CUvDCIyuW4TxcS4eBYCNM0vBtB0XSIyMTlxjl/bBXD+i8BR2p4VoGCoUa2IjLhFC07wCk4bw+E9RzXNFYwX18MAXN0wA9JLvBcnLXNlPoJSpOdzBIKA9Q+IOTR4GgCAlCUQA==="}
import type { ShikiTransformer } from 'shiki'
const customTransformer: ShikiTransformer = {
name: 'my-transformer',
enforce: 'pre',
code(node) {
// ...
},
}
```
---
### Packages Astro (`docs/packages/astro.md`)
# Astro Integration
You don't need explicit integration in [Astro](https://astro.build/) as Astro already uses Shiki under the hood.
Learn more about the configurations in the [Astro documentation](https://docs.astro.build/en/guides/syntax-highlighting/).
---
### Packages Cli (`docs/packages/cli.md`)
# @shikijs/cli
()
useEffect(() => {
async function initializeHighlighter() {
const h = await createHighlighter({
themes: ['nord'],
langs: ['javascript', 'typescript'],
})
setHighlighter(h)
}
initializeHighlighter()
}, [])
function animate() {
setCode(`let hi = 'hello'`)
}
return (
{highlighter && (
<>
{h => (
<>
)
}
```
### Svelte
Import `@shikijs/magic-move/svelte` and pass the highlighter instance to the `ShikiMagicMove` component.
```svelte
{#await highlighter then highlighter}
` as the outermost wrappers of code block html. If you use a custom Shiki [transformer](/guide/transformers), this behavior may be undesirable. For example, if the transformer produces
```html
โฆ
```
the result after `markdown-it` processing will be
```html
โฆ
```
Work around this by adding [olets/markdown-it-wrapperless-fence-rule](https://github.com/olets/markdown-it-wrapperless-fence-rule) to your `markdown-it` configuration, or by writing your own `markdown-it` fence rule (see [markdown-it#269](https://github.com/markdown-it/markdown-it/issues/269)).
---
### Packages Monaco (`docs/packages/monaco.md`)
# Monaco Editor Integration
Shiki uses the same TextMate grammar and themes as VS Code, so it can be used to highlight Monaco Editor. Shiki provides an official integration for Monaco Editor. You can also use [modern-monaco](https://github.com/esm-dev/modern-monaco) that includes built-in Shiki integration.
## @shikijs/monaco
{[
'console.log("Hello")',
'console.log("World")',
].join('\n')}
)
}
interface Props {
children: string
lang: BundledLanguage
}
async function CodeBlock(props: Props) {
const out = await codeToHtml(props.children, {
lang: props.lang,
theme: 'github-dark'
})
return
}
```
### Custom Components
You can also call `codeToHast` to get the HTML abstract syntax tree, and render it using [`hast-util-to-jsx-runtime`](https://github.com/syntax-tree/hast-util-to-jsx-runtime). With this method, you can render your own `pre` and `code` components.
```tsx
import type { JSX } from 'react'
import type { BundledLanguage } from 'shiki'
import { toJsxRuntime } from 'hast-util-to-jsx-runtime'
import { Fragment } from 'react'
import { jsx, jsxs } from 'react/jsx-runtime'
import { codeToHast } from 'shiki'
export default function Page() {
return (
{[
'console.log("Hello")',
'console.log("World")',
].join('\n')}
)
}
interface Props {
children: string
lang: BundledLanguage
}
async function CodeBlock(props: Props) {
const out = await codeToHast(props.children, {
lang: props.lang,
theme: 'github-dark'
})
return toJsxRuntime(out, {
Fragment,
jsx,
jsxs,
components: {
// your custom `pre` element
pre: props =>
},
}) as JSX.Element
}
```
## React Client Component
For client components, they are pre-rendered on server and hydrated/rendered on client.
We can start by creating a client `CodeBlock` component.
Create a `shared.ts` for highlighter:
```ts
import type { JSX } from 'react'
import type { BundledLanguage } from 'shiki/bundle/web'
import { toJsxRuntime } from 'hast-util-to-jsx-runtime'
import { Fragment } from 'react'
import { jsx, jsxs } from 'react/jsx-runtime'
import { codeToHast } from 'shiki/bundle/web'
export async function highlight(code: string, lang: BundledLanguage) {
const out = await codeToHast(code, {
lang,
theme: 'github-dark'
})
return toJsxRuntime(out, {
Fragment,
jsx,
jsxs,
}) as JSX.Element
}
```
In your `codeblock.tsx`:
```tsx
'use client'
import { JSX, useLayoutEffect, useState } from 'react'
import { highlight } from './shared'
export function CodeBlock({ initial }: { initial?: JSX.Element }) {
const [nodes, setNodes] = useState(initial)
useLayoutEffect(() => {
void highlight('console.log("Rendered on client")', 'ts').then(setNodes)
}, [])
return nodes ?? Loading...
}
```
The `initial` prop can be passed from a server component to pre-render the code block on server.
In your `page.tsx`:
```tsx
import { CodeBlock } from './codeblock'
import { highlight } from './shared'
export default async function Page() {
// `initial` is optional.
return (
)
}
```
::: info
The above example uses the `shiki/bundle/web` bundle. You can change it to [Fine-grained Bundle](/guide/bundles#fine-grained-bundle) to fully control the bundled languages/themes.
:::
### Performance
Shiki lazy loads the requested languages and themes, the Next.js bundler can handle lazy imports automatically.
Importing `shiki` or its web bundle is efficient enough for most Next.js applications, Fine-grained Bundle won't significantly impact the bundle size.
In addition, you can use the `createHighlighter` API to preload specific languages and themes.
Please refer to [Highlighter Usage](/guide/install#highlighter-usage) for further details.
### Highlighter Instance
If you define a highlighter (without `await`) as a global variable, you can reference it directly from server and client components.
```ts
import { createHighlighter } from 'shiki'
const highlighter = createHighlighter({
themes: ['nord'],
langs: ['javascript'],
})
// Inside an async server component, or client side `useEffect`
const html = (await highlighter).codeToHtml('const a = 1', {
lang: 'javascript',
theme: 'nord'
})
```
---
### Packages Nuxt (`docs/packages/nuxt.md`)
# Nuxt
[Nuxt](https://nuxt.com) is a general-purpose meta-framework that gives you full control over your application. You can install Shiki along with integrations like ([markdown-it](/packages/markdown-it), [rehype](/packages/rehype)) or import manually as you needed.
On top of that, Nuxt also provide some module integrations for Shiki allowing you use it easier:
- [`nuxt-shiki`](https://github.com/pi0/nuxt-shiki) - Shiki integration for client and server sides, with component usage.
- [`@nuxt/content`](https://github.com/nuxt/content) - Nuxt Content has Shiki built-in for markdown files. [You can enable it with the `highlight` option](https://content.nuxt.com/docs/getting-started/configuration#highlight).
- [`@nuxtjs/mdc`](https://github.com/nuxt-modules/mdc) - The underlying module of `@nuxt/content` that provides Markdown Component (MDC) syntax as well as Shiki for syntax highlighting.
## TwoSlash Integration
- [`nuxt-content-twoslash`](https://github.com/antfu/nuxt-content-twoslash) - A Nuxt module that adds Twoslash support to Nuxt Content. Twoslash information are evaluated at build time.
---
### Packages Rehype (`docs/packages/rehype.md`)
---
outline: deep
---
# @shikijs/rehype
you want to highlight
const textStream = getTextStreamFromSomewhere()
// Pipe the text stream through the token stream
const tokensStream = textStream
.pipeThrough(new CodeToTokenTransformStream({
highlighter,
lang: 'javascript',
theme: 'nord',
allowRecalls: true, // see explanation below
}))
```
### `allowRecalls`
Due to the fact that highlighting may change based on the context of the code, themed tokens can be re-evaluated as the stream progresses. Because streams are one-directional, `@shikijs/stream` emits a special **recall** token that tells the receiver to discard the last N tokens that changed.
By default, `CodeToTokenTransformStream` only emits **stable** tokens โ no recalls. The trade-off is coarser granularity, usually one line at a time.
For stream consumers that can handle recalls (e.g. the bundled Vue, React, Solid, and Svelte components), set `allowRecalls: true` to get finer-grained tokens.
Typically recalls should be handled like:
```ts
import type { RecallToken } from '@shikijs/stream'
import type { ThemedToken } from 'shiki'
const receivedTokens: ThemedToken[] = []
tokensStream.pipeTo(new WritableStream({
async write(token) {
if ('recall' in token) {
// discard the last `token.recall` tokens
receivedTokens.length -= token.recall
}
else {
receivedTokens.push(token)
}
},
}))
```
## Consume the Token Stream
### Manually
```ts
tokensStream.pipeTo(new WritableStream({
async write(token) {
console.log(token)
},
}))
```
Or in Node.js:
```ts
for await (const token of tokensStream) {
console.log(token)
}
```
### Vue
```vue
` tag is modified: ``
::: details HTML Output
```html
function(){
console.log('hewwo')
console.log('hello')
}
```
:::
---
### `transformerNotationHighlight`
Use `[!code highlight]` to highlight a line.
````md
```ts
console.log('Not highlighted')
console.log('Highlighted') // [\!code highlight]
console.log('Not highlighted')
```
````
Renders (with custom CSS rules):
```ts
console.log('Not highlighted')
console.log('Highlighted') // [!code highlight]
console.log('Not highlighted')
```
- `// [!code highlight]` outputs: ``
- The outer `` tag is modified: ``
You can also highlight multiple lines with a single comment:
````md
```ts
// [\!code highlight:3]
console.log('Highlighted')
console.log('Highlighted')
console.log('Highlighted')
console.log('Not highlighted')
```
```ts
console.log('Not highlighted')
// [\!code highlight:1]
console.log('Highlighted')
console.log('Not highlighted')
```
````
Renders:
```ts
// [!code highlight:3]
console.log('Highlighted')
console.log('Highlighted')
console.log('Highlighted')
console.log('Not highlighted')
```
```ts
console.log('Not highlighted')
// [!code highlight:1]
console.log('Highlighted')
console.log('Not highlighted')
```
---
### `transformerNotationWordHighlight`
Use `[!code word:Hello]` to highlight the word `Hello` in any subsequent code.
````md
```ts
// [\!code word:Hello]
const message = 'Hello World'
console.log(message) // prints Hello World
```
````
Renders (with custom CSS rules):
```ts
// [!code word:Hello]
const message = 'Hello World'
console.log(message) // prints Hello World
```
Outputs: `Hello` 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.
````md
```ts
// [\!code word:Hello:1]
const message = 'Hello World'
console.log(message) // prints Hello World
```
````
Renders:
```ts
// [!code word:Hello:1]
const message = 'Hello World'
console.log(message) // prints Hello World
```
---
### `transformerNotationFocus`
Use `[!code focus]` to focus a line.
````md
```ts
console.log('Not focused');
console.log('Focused') // [\!code focus]
console.log('Not focused');
```
````
Renders (with custom CSS rules):
```ts
console.log('Not focused')
console.log('Focused') // [!code focus]
console.log('Not focused')
```
- Outputs: ``
- The outer `` tag is modified: ``
You can also focus multiple lines with a single comment:
````md
```ts
// [\!code focus:3]
console.log('Focused')
console.log('Focused')
console.log('Focused')
console.log('Not focused')
```
````
Renders:
```ts
// [!code focus:3]
console.log('Focused')
console.log('Focused')
console.log('Focused')
console.log('Not focused')
```
---
### `transformerNotationErrorLevel`
Use `[!code error]`, `[!code warning]`, and `[!code info]` to mark a line with an error, warning, or info levels.
````md
```ts
console.log('No errors or warnings')
console.error('Error') // [\!code error]
console.warn('Warning') // [\!code warning]
console.log('Info') // [\!code info]
```
````
- Outputs: `` for errors
- Outputs: `` for warnings
- Outputs: `` for info
- The outer `` tag is modified: ``
With some additional CSS rules, you can make it look like this:
```ts
console.log('No errors or warnings')
console.error('Error') // [!code error]
console.warn('Warning') // [!code warning]
console.log('Info') // [!code info]
```
---
### `transformerRenderWhitespace`
Render whitespaces (tabs and spaces) as individual spans, with classes `tab` and `space`.
Options:
- `position`: `'all' | 'boundary' | 'trailing' | 'leading'`. Default `'all'`.
With some additional CSS rules, you can make it look like this:
jsfunction block( ) {
space( )
tab( )
}
::: details Example CSS
```css
pre.shiki .tab,
pre.shiki .space {
position: relative;
}
pre.shiki .tab::before {
content: 'โฅ';
position: absolute;
opacity: 0.3;
}
pre.shiki .space::before {
content: 'ยท';
position: absolute;
opacity: 0.3;
}
```
:::
---
### `transformerRenderIndentGuides`
Render indentations as individual spans, with class `indent`.
With some additional CSS rules, you can make it look like this:
jsfunction func() {
console.log(1);
for (const i of []) {
console.log(2);
}
}
::: details Example CSS
```css
pre.shiki .indent {
display: inline-block;
position: relative;
left: var(--indent-offset);
}
pre.shiki .indent:empty {
height: 1lh;
vertical-align: bottom;
}
pre.shiki .indent::before {
content: '';
position: absolute;
opacity: 0.15;
width: 1px;
height: 100%;
background-color: currentColor;
}
```
:::
---
### `transformerRenderLineNumber`
Render line numbers as individual spans, with class `line-number`.
```ts
import { transformerRenderLineNumber } from '@shikijs/transformers'
const html = await codeToHtml(code, {
transformers: [
transformerRenderLineNumber(),
],
})
```
Options:
- `start`: Start number. Default `1`.
- `classLineNumber`: Class for line number. Default `'line-number'`.
With some additional CSS rules, you can make it look like this:
```css
pre.shiki .line-number {
user-select: none;
opacity: 0.5;
margin-right: 1em;
}
```
---
### `transformerMetaHighlight`
Highlight lines based on the [meta string](/guide/transformers#meta) provided on the code snippet.
````md
```js {1,3-4}
console.log('1')
console.log('2')
console.log('3')
console.log('4')
```
````
Renders (with custom CSS rules):
```js {1,3-4}
console.log('1')
console.log('2')
console.log('3')
console.log('4')
```
- Outputs: `` for included lines.
### `transformerMetaWordHighlight`
Highlight words based on the meta string provided on the code snippet.
````md
```js /Hello/
const msg = 'Hello World'
console.log(msg)
console.log(msg) // prints Hello World
```
````
Renders (with custom CSS rules):
```js /Hello/
const msg = 'Hello World'
console.log(msg) // prints Hello World
```
Outputs: `Hello` for matched words.
---
### `transformerCompactLineOptions`
Support for `shiki`'s `lineOptions` that is removed in `shiki`.
---
### `transformerRemoveLineBreak`
Remove line breaks between ``. Useful when you set `display: block` to `.line` in CSS.
---
### `transformerRemoveNotationEscape`
Transform `// [\!code ...]` to `// [!code ...]`.
Avoid rendering the escaped notation syntax as it is.
---
### `transformerStyleToClass`
Convert Shiki's inline styles to unique classes.
Class names are generated based on the hash value of the style object with the prefix/suffix you provide. You can put this transformer in multiple highlights passes and then get the CSS at the end to reuse the exact same styles. As Shiki doesn't handle CSS, it's on your integration to decide how to extract and apply/bundle the CSS.
For example:
```ts
import { transformerStyleToClass } from '@shikijs/transformers'
import { codeToHtml } from 'shiki'
const toClass = transformerStyleToClass({ // [!code highlight:3]
classPrefix: '__shiki_',
})
const code = `console.log('hello')`
const html = await codeToHtml(code, {
lang: 'ts',
themes: {
dark: 'vitesse-dark',
light: 'vitesse-light',
},
defaultColor: false,
transformers: [toClass], // [!code highlight]
})
// The transformer instance exposes some methods to get the CSS
const css = toClass.getCSS() // [!code highlight]
// use `html` and `css` in your app
```
HTML output:
```html
console
.
log
(
'
hello
'
)
```
CSS output:
```css
.__shiki_14cn0u {
--shiki-dark: #bd976a;
--shiki-light: #b07d48;
}
.__shiki_ps5uht {
--shiki-dark: #666666;
--shiki-light: #999999;
}
.__shiki_1zrdwt {
--shiki-dark: #80a665;
--shiki-light: #59873a;
}
.__shiki_236mh3 {
--shiki-dark: #c98a7d77;
--shiki-light: #b5695977;
}
.__shiki_1g4r39 {
--shiki-dark: #c98a7d;
--shiki-light: #b56959;
}
.__shiki_9knfln {
--shiki-dark: #dbd7caee;
--shiki-light: #393a34;
--shiki-dark-bg: #121212;
--shiki-light-bg: #ffffff;
}
```
### `transformerRemoveComments`
Remove comments from the code. It works by checking the internal grammar token metadata to determine if the token is a comment.
This transformer requires `includeExplanation: true` to work.
```ts
import { transformerRemoveComments } from '@shikijs/transformers'
const html = await codeToHtml(code, {
lang: 'ts',
includeExplanation: true, // [!code highlight]
transformers: [
transformerRemoveComments(), // [!code highlight]
],
})
```
Options:
- `removeEmptyLines`: Remove lines that become empty after removing comments. Default `true`.
For example:
````md
```js
// This is a comment
const x = 1 // Inline comment
/* Block comment */
const y = 2
// Another comment
```
````
Will renders:
```js
const x = 1
const y = 2
```
---
### Packages Twoslash (`docs/packages/twoslash.md`)
---
outline: deep
---
# @shikijs/twoslash