@rspress/plugin-shiki#

Integrated Shiki code highlighting plugin. By default, Rspress uses Prism.js to achieve syntax highlighting. However, in some cases, when you need to implement code highlighting for more languages, Prism.js may not be sufficient, so you can integrate this plugin to use Shiki to support more languages.

Installation#

npm add @rspress/plugin-shiki -D

Usage#

First, write the following configuration in the configuration file:

import { defineConfig } from 'rspress/config';
import { pluginShiki } from '@rspress/plugin-shiki';

export default defineConfig({
  plugins: [pluginShiki()],
});

Configuration#

This plugin supports passing in an object configuration. The properties of this object configuration are as follows:

import type {
  BuiltinLanguage,
  BuiltinTheme,
  ShikiTransformer,
  SpecialLanguage,
} from 'shiki';

export interface PluginShikiOptions {
  /**
   * Code highlighting theme, @see https://shiki.style/themes
   */
  theme: BuiltinTheme | 'css-variables';
  /**
   * Code highlighting language, @see https://shiki.style/languages
   */
  langs: Array<BuiltinLanguage | SpecialLanguage>;
  /**
   * Custom shiki transformer, @see https://shiki.style/guide/transformers
   */
  transformers: ShikiTransformer[];
}

The code highlighting theme uses css-variables. You can also choose your favorite theme, refer to the Shiki theme list documentation for details.

The default languages supported include js, jsx, ts, tsx, json, css, scss, less, xml, diff, yaml, md, mdx, bash. If you want to support more languages, you can pass the langs attribute in the configuration file. This attribute is an array, each item in the array is an id of a language, refer to the Shiki-supported language list for details.

Transformer concept and usage#

Transformer is a concept in this plugin, its function is to transform specific syntax of code blocks, for example, you can use this feature to implement the diff highlighting effect of code blocks.

Introduction to built-in transformers#

A few Transformers are built into this plugin, including:

• createTransformerLineNumber: Implement the display of the line number of the code block.

You can enable these Transformers by configuring the transformers attribute, such as:

import { defineConfig } from 'rspress/config';
import { pluginShiki, createTransformerDiff } from '@rspress/plugin-shiki';
import {
  transformerNotationDiff,
  transformerNotationErrorLevel,
  transformerNotationFocus,
  transformerNotationHighlight,
} from '@shikijs/transformers';

export default defineConfig({
  plugins: [
    pluginShiki({
      transformers: [
        // Add as needed
        createTransformerLineNumber(),
        // transformerNotationDiff(),
        // transformerNotationErrorLevel(),
        // transformerNotationHighlight(),
        // transformerNotationFocus(),
      ],
    }),
  ],
});

Please view Shiki Transformers documentation for more information.