feat!(plugin-shiki): bump shiki to v3, migrate to official transformers (#1672)

Co-authored-by: SoonIter <[email protected]>

Author: JounQin

e2e/fixtures/plugin-shiki/package.json

@@ -9,6 +9,7 @@
   },
   "dependencies": {
     "@rspress/plugin-shiki": "workspace:*",
+    "@shikijs/transformers": "^3.1.0",
     "rspress": "workspace:*"
   },
   "devDependencies": {

e2e/fixtures/plugin-shiki/rspress.config.ts

@@ -1,24 +1,26 @@
 import path from 'node:path';
 import {
-  createTransformerDiff,
-  createTransformerErrorLevel,
-  createTransformerFocus,
-  createTransformerHighlight,
   createTransformerLineNumber,
   pluginShiki,
 } from '@rspress/plugin-shiki';
+import {
+  transformerNotationDiff,
+  transformerNotationErrorLevel,
+  transformerNotationFocus,
+  transformerNotationHighlight,
+} from '@shikijs/transformers';
 import { defineConfig } from 'rspress/config';
 
 export default defineConfig({
   root: path.join(__dirname, 'doc'),
   plugins: [
     pluginShiki({
       transformers: [
-        createTransformerDiff(),
+        transformerNotationDiff(),
+        transformerNotationErrorLevel(),
+        transformerNotationHighlight(),
+        transformerNotationFocus(),
         createTransformerLineNumber(),
-        createTransformerErrorLevel(),
-        createTransformerHighlight(),
-        createTransformerFocus(),
       ],
     }),
   ],

packages/document/docs/en/plugin/official-plugins/shiki.mdx

@@ -36,19 +36,26 @@ export default defineConfig({
 This plugin supports passing in an object configuration. The properties of this object configuration are as follows:
 
 ```ts
-interface PluginShikiOptions {
+import type {
+  BuiltinLanguage,
+  BuiltinTheme,
+  ShikiTransformer,
+  SpecialLanguage,
+} from 'shiki';
+
+export interface PluginShikiOptions {
   /**
-   * Code highlighting theme
+   * Code highlighting theme, @see https://shiki.style/themes
    */
-  theme: string;
+  theme: BuiltinTheme | 'css-variables';
   /**
-   * Code highlighting language
+   * Code highlighting language, @see https://shiki.style/languages
    */
-  langs: string[];
+  langs: Array<BuiltinLanguage | SpecialLanguage>;
   /**
-   * Add custom transformer
+   * Custom shiki transformer, @see https://shiki.style/guide/transformers
    */
-  transformers: Transformer[];
+  transformers: ShikiTransformer[];
 }
 ```
 
@@ -64,81 +71,34 @@ Transformer is a concept in this plugin, its function is to transform specific s
 
 A few Transformers are built into this plugin, including:
 
-- `createTransformerDiff`: Implementation of the diff highlighting effect of the code block.
 - `createTransformerLineNumber`: Implement the display of the line number of the code block.
-- `createTransformerErrorLevel`: Implement the display of the error level of the corresponding line of the code block, including `error` and `warning`.
-- `createTransformerHighlight`: Implement line highlighting display of the code block.
-- `createTransformerFocus`: Implement line focus display of the code block.
 
 You can enable these Transformers by configuring the `transformers` attribute, such as:
 
 ```ts title="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: [
         // Add as needed
-        createTransformerDiff(),
-        // createTransformerLineNumber(),
-        // createTransformerErrorLevel(),
-        // createTransformerHighlight(),
-        // createTransformerFocus(),
+        createTransformerLineNumber(),
+        // transformerNotationDiff(),
+        // transformerNotationErrorLevel(),
+        // transformerNotationHighlight(),
+        // transformerNotationFocus(),
       ],
     }),
   ],
 });
 ```
 
-Then let us introduce how to use the syntax corresponding to these Transformers.
-
-#### Diff highlighting
-
-Use the `diff` syntax in the markdown code block, such as:
-
-```ts
-export function foo() {
-  console.log('Diff remove'); // [!code --]
-  console.log('Diff add'); // [!code ++]
-}
-```
-
-This will automatically apply the diff highlighting effect to the corresponding line of code.
-
-#### Line number display
-
-Use the `hl` syntax in the markdown code block, such as:
-
-```ts
-export function foo() {
-  console.log('Line number'); // [!code hl]
-}
-```
-
-This will automatically display the line number for the corresponding line of code.
-
-#### Error level display
-
-Use the `error` or `warning` syntax in the markdown code block, such as:
-
-```ts
-export function foo() {
-  console.log('Error level'); // [!code error]
-}
-```
-
-This will automatically display the error level for the corresponding line of code.
-
-#### Line focus display
-
-Use the `focus` syntax in the markdown code block, such as:
-
-```ts
-export function foo() {
-  console.log('Focus'); // [!code focus]
-}
-```
-
-This will automatically display the focus effect for the corresponding line of code.
+Please view [Shiki Transformers documentation](https://shiki.style/guide/transformers) for more information.

packages/document/docs/zh/plugin/official-plugins/shiki.mdx

@@ -36,19 +36,26 @@ export default defineConfig({
 该插件支持传入一个对象配置，该对象配置的属性如下：
 
 ```ts
-interface PluginShikiOptions {
+import type {
+  BuiltinLanguage,
+  BuiltinTheme,
+  ShikiTransformer,
+  SpecialLanguage,
+} from 'shiki';
+
+export interface PluginShikiOptions {
   /**
-   * 代码高亮主题
+   * 代码高亮主题，@see https://shiki.style/themes
    */
-  theme: string;
+  theme: BuiltinTheme | 'css-variables';
   /**
-   * 代码高亮的语言
+   * 代码高亮的语言，@see https://shiki.style/languages
    */
-  langs: string[];
+  langs: Array<BuiltinLanguage | SpecialLanguage>;
   /**
-   * 添加自定义 transformer
+   * 自定义 shiki transformer，@see https://shiki.style/guide/transformers
    */
-  transformers: Transformer[];
+  transformers: ShikiTransformer[];
 }
 ```
 
@@ -64,81 +71,34 @@ Transformer 是本插件中的一个概念，它的作用是对代码块的特
 
 本插件中内置了一些 Transformer，包括：
 
-- `createTransformerDiff`：实现代码块的 diff 高亮效果。
 - `createTransformerLineNumber`：实现代码块的行号显示。
-- `createTransformerErrorLevel`：实现代码块对应行的错误等级显示，包括 `error` 和 `warning`。
-- `createTransformerHighlight`：实现代码块的行高亮显示。
-- `createTransformerFocus`： 实现代码块的行聚焦显示。
 
 你可以通过配置 `transformers` 属性来启用这些 Transformer，比如：
 
 ```ts title="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: [
         // 按需加入即可
-        createTransformerDiff(),
-        // createTransformerLineNumber(),
-        // createTransformerErrorLevel(),
-        // createTransformerHighlight(),
-        // createTransformerFocus(),
+        createTransformerLineNumber(),
+        // transformerNotationDiff(),
+        // transformerNotationErrorLevel(),
+        // transformerNotationHighlight(),
+        // transformerNotationFocus(),
       ],
     }),
   ],
 });
 ```
 
-接着我们来介绍一下如何使用这些 Transformer 对应的语法。
-
-#### diff 高亮
-
-在 markdown 的代码块中使用 `diff` 语法，比如：
-
-```ts
-export function foo() {
-  console.log('Diff remove'); // [!code --]
-  console.log('Diff add'); // [!code ++]
-}
-```
-
-这样会自动对相应行的代码应用 diff 高亮效果。
-
-#### 行号显示
-
-在 markdown 的代码块中使用 `hl` 语法，比如：
-
-```ts
-export function foo() {
-  console.log('Line number'); // [!code hl]
-}
-```
-
-这样会自动对相应行的代码显示行号。
-
-#### 错误等级显示
-
-在 markdown 的代码块中使用 `error` 或 `warning` 语法，比如：
-
-```ts
-export function foo() {
-  console.log('Error level'); // [!code error]
-}
-```
-
-这样会自动对相应行的代码显示错误等级。
-
-#### 行聚焦显示
-
-在 markdown 的代码块中使用 `focus` 语法，比如：
-
-```ts
-export function foo() {
-  console.log('Focus'); // [!code focus]
-}
-```
-
-这样会自动对相应行的代码显示聚焦效果。
+请查看 [Shiki Transformers 文档](https://shiki.style/guide/transformers) 获取更多信息。

packages/plugin-shiki/package.json

@@ -31,7 +31,7 @@
   "dependencies": {
     "@rspress/shared": "workspace:*",
     "hast-util-from-html": "^1.0.2",
-    "shiki": "^0.14.7",
+    "shiki": "^3.1.0",
     "unist-util-visit": "^4.1.2"
   },
   "devDependencies": {

packages/plugin-shiki/shiki.css

@@ -4,8 +4,8 @@
  * -------------------------------------------------------------------------- */
 
 :root {
-  --shiki-color-text: #414141;
-  --shiki-color-background: transparent;
+  --shiki-foreground: #414141;
+  --shiki-background: transparent;
   --shiki-token-constant: #1976d2;
   --shiki-token-string: #31a94d;
   --shiki-token-comment: rgb(182, 180, 180);
@@ -18,7 +18,7 @@
 }
 
 .dark {
-  --shiki-color-text: #cac7c7;
+  --shiki-foreground: #cac7c7;
   --shiki-token-constant: #6fb0fa;
   --shiki-token-string: #f9a86e;
   --shiki-token-comment: #6a727b;
@@ -37,9 +37,8 @@
 .diff,
 .code-line-highlighted {
   transition: background-color 0.5s;
-  margin: 0 -20px;
   padding: 0 20px;
-  width: calc(100% + 40px);
+  width: 100%;
   display: inline-block;
   position: relative;
 }

packages/plugin-shiki/src/rehypePlugin.ts

@@ -1,17 +1,17 @@
 import type { Element, ElementContent, Root, Text } from 'hast';
 import { fromHtml } from 'hast-util-from-html';
-import type shiki from 'shiki';
+import type { BuiltinTheme, Highlighter } from 'shiki';
 import type { Plugin } from 'unified';
 import { visit } from 'unist-util-visit';
 
 interface Options {
-  highlighter: shiki.Highlighter;
+  highlighter: Highlighter;
+  theme: BuiltinTheme;
 }
 
-export const rehypePluginShiki: Plugin<[Options], Root> = function ({
-  highlighter,
-}) {
-  return (tree: Root) => {
+export const rehypePluginShiki: Plugin<[Options], Root> =
+  ({ highlighter, theme }) =>
+  (tree: Root) => {
     visit(tree, 'element', (node, index, parent) => {
       // <pre><code>...</code></pre>
       if (
@@ -32,7 +32,7 @@ export const rehypePluginShiki: Plugin<[Options], Root> = function ({
           highlightLines = highlightMatch
             ?.replace(/[{}]/g, '')
             .split(',')
-            .map(item => {
+            .flatMap(item => {
               const [start, end] = item.split('-');
               if (end) {
                 return Array.from(
@@ -41,15 +41,17 @@ export const rehypePluginShiki: Plugin<[Options], Root> = function ({
                 );
               }
               return Number(start);
-            })
-            .flat();
+            });
         }
         // for example: language-js {1,2,3-5}
         const lang = codeClassName.split(' ')[0].split('-')[1];
         if (!lang) {
           return;
         }
-        const highlightedCode = highlighter.codeToHtml(codeContent, { lang });
+        const highlightedCode = highlighter.codeToHtml(codeContent, {
+          lang,
+          theme,
+        });
         const fragmentAst = fromHtml(highlightedCode, { fragment: true });
         const preElement = fragmentAst.children[0] as Element;
         const codeElement = preElement.children[0] as Element;
@@ -81,4 +83,3 @@ export const rehypePluginShiki: Plugin<[Options], Root> = function ({
       }
     });
   };
-};