简体中文

@rspress/plugin-shiki

Source

集成 Shiki 代码高亮插件。在默认情况下，Rspress 会基于 Prism.js 来实现语法高亮。不过在某些情况下，你需要实现更多语言的代码高亮，Prism.js 可能不够用，此时你可以接入该插件，使用 Shiki 支持更多的语言。

注意

不过，引入该 Shiki 插件之后，Rspress 的编译性能会有所下降，所以请根据自己的需求来评估是否需要引入该插件。

安装

npm

yarn

pnpm

bun

npm add @rspress/plugin-shiki -D

使用

首先在配置文件中写入以下的配置：

rspress.config.ts

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

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

配置

该插件支持传入一个对象配置，该对象配置的属性如下：

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

export interface PluginShikiOptions {
  /**
   * 代码高亮主题，@see https://shiki.style/themes
   */
  theme: BuiltinTheme | 'css-variables';
  /**
   * 代码高亮的语言，@see https://shiki.style/languages
   */
  langs: Array<BuiltinLanguage | SpecialLanguage>;
  /**
   * 自定义 shiki transformer，@see https://shiki.style/guide/transformers
   */
  transformers: ShikiTransformer[];
}

其中，代码高亮主题使用的是 css-variables，你也可以选择自己喜欢的主题，具体可以参考 Shiki 主题列表文档。

默认支持的语言包括 js、jsx、ts、tsx、json、css、scss、less、xml、diff、yaml、md、mdx、bash，如果你想支持更多的语言，可以在配置文件中传入 langs 属性，该属性是一个数组，数组中的每一项都是一个语言的 id，具体可以参考 Shiki 支持的语言列表。

Transformer 概念和使用

Transformer 是本插件中的一个概念，它的作用是对代码块的特定语法进行转换，比如你可以使用该功能来实现代码块的 diff 高亮效果。

内置 Transformer 介绍

本插件中内置了一些 Transformer，包括：

createTransformerLineNumber：实现代码块的行号显示。

你可以通过配置 transformers 属性来启用这些 Transformer，比如：

rspress.config.ts

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: [
        // 按需加入即可
        createTransformerLineNumber(),
        // transformerNotationDiff(),
        // transformerNotationErrorLevel(),
        // transformerNotationHighlight(),
        // transformerNotationFocus(),
      ],
    }),
  ],
});

请查看 Shiki Transformers 文档获取更多信息。

ON THIS PAGE

@rspress/plugin-shiki#

安装#

使用#

配置#

Transformer 概念和使用#

内置 Transformer 介绍#

@rspress/plugin-shiki

安装

使用

配置

Transformer 概念和使用

内置 Transformer 介绍