diff --git a/docs/plugins/markdown/shiki.md b/docs/plugins/markdown/shiki.md
index 60a48125e5..fb44fa8320 100644
--- a/docs/plugins/markdown/shiki.md
+++ b/docs/plugins/markdown/shiki.md
@@ -6,11 +6,11 @@ icon: highlighter
-This plugin will enable syntax highlighting for markdown code fence with [Shiki](https://shiki.style/).
+This plugin enables syntax highlighting for markdown code fence with [Shiki](https://shiki.style/).
::: tip
-[Shiki](https://shiki.style/) is the syntax highlighter being used by VSCode. It has higher fidelity, but it could be slower than [Prism.js](https://prismjs.com/), especially when you have a lot of code blocks.
+[Shiki](https://shiki.style/) is the syntax highlighter used by VSCode. It provides higher fidelity highlighting but may be slower than [Prism.js](https://prismjs.com/), especially when processing many code blocks.
:::
@@ -38,14 +38,11 @@ export default {
### langs
- Type: `ShikiLang[]`
-
-- Details:
-
- Additional languages to be parsed by Shiki.
+- Details: Additional languages to be parsed by Shiki.
::: tip
- The plugin now automatically loads the languages used in your markdown files, so you don't need to specify them manually.
+ The plugin automatically loads languages used in your markdown files, so manual specification is not required.
:::
@@ -55,8 +52,7 @@ export default {
### langAlias
- Type: `{ [lang: string]: string }`
-
-- Details: Customize language aliases for Shiki.
+- Details: Custom language aliases for Shiki.
- Also see:
- [Shiki > Custom Language Aliases](https://shiki.style/guide/load-lang#custom-language-aliases)
@@ -64,10 +60,8 @@ export default {
### theme
- Type: `ShikiTheme`
-
- Default: `'nord'`
-
-- Details: Theme of Shiki, will be applied to code blocks.
+- Details: Shiki theme to be applied to code blocks.
- Also see:
- [Shiki > Themes](https://shiki.style/themes)
@@ -75,12 +69,9 @@ export default {
### themes
- Type: `{ light: ShikiTheme; dark: ShikiTheme }`
+- Details: Dark/light dual themes for Shiki.
-- Details:
-
- Dark / Light Dual themes of Shiki.
-
- The styles of the 2 themes will be injected as `--shiki-light` and `--shiki-dark` to code blocks:
+ The styles of both themes will be injected as `--shiki-light` and `--shiki-dark` CSS variables to code blocks:
```html
code
@@ -92,35 +83,33 @@ export default {
### lineNumbers
- Type: `boolean | number | 'disable'`
-
- Default: `true`
+- Details: Controls the display of line numbers.
-- Details:
-
- - `number`: the minimum number of lines to enable line numbers.
- For example, if you set it to 4, line numbers will only be enabled when your code block has at least 4 lines of code.
+ - `number`: minimum number of lines required to enable line numbers.
+ For example, setting it to 4 will only enable line numbers when your code block has at least 4 lines.
- `true`: enable line numbers globally.
- `false`: disable line numbers globally.
- - `'disable'`: Completely disable line numbers, `:line-numbers` will not take effect.
+ - `'disable'`: completely disable line numbers; `:line-numbers` will not take effect.
- You can add `:line-numbers` / `:no-line-numbers` mark in your fenced code blocks to override the value set in config, and customize the beginning number by adding `=` after `:line-numbers`. For example, `:line-numbers=2` means the line numbers in code blocks will start from `2`.
+ You can add `:line-numbers` / `:no-line-numbers` markers to your fenced code blocks to override the config setting, and customize the starting number by adding `=` after `:line-numbers`. For example, `:line-numbers=2` will start line numbers from `2`.
::: preview
```ts:line-numbers
-// line-numbers is enabled
+// line-numbers are enabled
const line2 = 'This is line 2'
const line3 = 'This is line 3'
```
```ts :no-line-numbers
-// line-numbers is disabled
+// line-numbers are disabled
const line2 = 'This is line 2'
const line3 = 'This is line 3'
```
```ts :line-numbers=2
-// line-numbers is enabled and start from 2
+// line-numbers are enabled and start from 2
const line3 = 'This is line 3'
const line4 = 'This is line 4'
```
@@ -130,12 +119,8 @@ const line4 = 'This is line 4'
### highlightLines
- Type: `boolean`
-
- Default: `true`
-
-- Details:
-
- Whether enable code line highlighting. You can highlight specified lines of your code blocks by adding line ranges mark in your fenced code blocks:
+- Details: Whether to enable code line highlighting. You can highlight specified lines by adding line range markers to your fenced code blocks:
- Line ranges: `{5-8}`
- Multiple single lines: `{4,7,9}`
@@ -161,9 +146,7 @@ export default defineUserConfig({
### collapsedLines
- Type: `boolean | number | 'disable'`
-
- Default: `'disable'`
-
- Details: Default behavior of code block collapsing.
- `number`: collapse the code block starting from line `number` by default, for example, `12` means collapsing the code block starting from line 12.
@@ -288,7 +271,7 @@ body > div {
- Details: Whether to enable code block title rendering. Add `title="Title"` after the code block \`\`\` to set the title.
- Pass `CodeBlockTitleRender` to customize the title rendering.
+ Pass a `CodeBlockTitleRender` function to customize title rendering.
- Example:
@@ -306,7 +289,7 @@ body > div {
- Default: `false`
-- Details: Whether enable notation diff.
+- Details: Whether to enable notation diff.
- Example:
@@ -342,7 +325,7 @@ body > div {
- Default: `false`
-- Details: Whether enable notation focus.
+- Details: Whether to enable notation focus.
- Example:
@@ -378,7 +361,7 @@ body > div {
- Default: `false`
-- Details: Whether enable notation highlight.
+- Details: Whether to enable notation highlight.
- Example:
@@ -414,7 +397,7 @@ body > div {
- Default: `false`
-- Details: Whether enable notation error level.
+- Details: Whether to enable notation error level.
- Example:
@@ -450,9 +433,9 @@ body > div {
- Default: `false`
-- Details: Whether enable notation word highlight.
+- Details: Whether to enable notation word highlight.
- Word highlight must be written on a separate line.
+ Word highlights must be written on separate lines.
- Example:
@@ -481,7 +464,7 @@ body > div {
- Highlight words based on the meta string provided on the code snippet
+ Highlight words based on the meta string provided in the code snippet
::: preview
@@ -502,15 +485,15 @@ body > div {
- Default: `false`
-- Details: Whether enable whitespace characters (Space and Tab).
+- Details: Whether to enable whitespace characters (spaces and tabs).
- - `true`: enable whitespace, but not render any whitespace by default
- - `false`: completely disable render whitespace, `:whitespace` will not take effect.
- - `'all'`: render all whitespace
- - `'boundary'`: render leading and trailing whitespace of the line
- - `'trailing'`: render trailing whitespace of the line
+ - `true`: enable whitespace rendering but don't render any whitespace by default
+ - `false`: completely disable whitespace rendering; `:whitespace` will not take effect
+ - `'all'`: render all whitespace characters
+ - `'boundary'`: render leading and trailing whitespace on each line
+ - `'trailing'`: render trailing whitespace on each line
- You can add `:whitespace / :no-whitespace` mark in your fenced code blocks to override the value set in config, and customize the render type by adding `=` after `:whitespace`. For example `:whitespace=boundary` will render leading and trailing whitespace of the line.
+ You can add `:whitespace` / `:no-whitespace` markers to your fenced code blocks to override the config setting, and customize the render type by adding `=` after `:whitespace`. For example, `:whitespace=boundary` will render leading and trailing whitespace on each line.
- Example:
@@ -526,7 +509,7 @@ body > div {
```
```md :whitespace=boundary
-
+
A text
with trailing spaces
@@ -535,7 +518,7 @@ body > div {
```
```md :whitespace=trailing
-
+
A text
with trailing spaces
@@ -544,7 +527,7 @@ body > div {
```
```md :no-whitespace
-
+
A text
with trailing spaces
@@ -554,7 +537,7 @@ body > div {
:::
-- Also see：
+- Also see:
- [Shiki > Render Whitespace](https://shiki.style/packages/transformers#transformerrenderwhitespace)
### twoslash
@@ -585,11 +568,11 @@ body > div {
- Default: `false`
-- Details: Whether enable [twoslash](https://github.com/twoslashes/twoslash).
+- Details: Whether to enable [twoslash](https://github.com/twoslashes/twoslash).
::: tip
- For size reasons, the plugin does not include the `@vuepress/shiki-twoslash` package by default. If you want to use it, you need to install it manually.
+ For size optimization, the plugin doesn't include the `@vuepress/shiki-twoslash` package by default. You need to install it manually to use this feature.
:::
@@ -614,11 +597,11 @@ body > div {
::: warning
- For code blocks that have `twoslash` enabled:
+ For code blocks with `twoslash` enabled:
- - Do not add the `:v-pre` marker in the code block, as this will cause `twoslash` to fail to run properly.
+ - Don't add the `:v-pre` marker to code blocks, as this will prevent `twoslash` from running properly.
- - To avoid layout conflicts, code blocks will no longer display line numbers.
+ - To avoid layout conflicts, line numbers will not be displayed for these code blocks.
:::
@@ -627,52 +610,38 @@ body > div {
### defaultLang
- Type: `string`
-
-- Default: `''`
-
-- Details: Fallback language when the specified language is not available.
+- Default: `'plain'`
+- Details: Fallback language to use when the specified language is not available.
### logLevel
- Type: `'warn' | 'debug' | 'silent'`
-
- Default: `'warn'`
+- Details: Log level for Shiki language detection.
-- Details:
-
- Log level of Shiki language detection.
-
- - `warn`: warn each unknown lang one time (default)
- - `debug`: log every unknown code block with its file path. (default when `--debug` flag is set)
- - `silent`: no warning
+ - `warn`: warn about each unknown language once (default)
+ - `debug`: log every unknown code block with its file path (default when `--debug` flag is set)
+ - `silent`: no warnings
### preWrapper
- Type: `boolean`
-
- Default: `true`
+- Details: Whether to add an extra wrapper outside the `` tag.
-- Details:
-
- Adds extra wrapper outside `` tag or not.
-
- The wrapper is required by the `lineNumbers` and `collapsedLines`. That means, if you disable `preWrapper`, the line line numbers and collapsed lines will also be disabled.
+ This wrapper is required for `lineNumbers` and `collapsedLines` features. If you disable `preWrapper`, line numbers and collapsed lines will also be disabled.
### shikiSetup
- Type: `(shiki: Highlighter) => void | Promise`
-
-- Details: A function hook to customize Shiki highlighter instance.
+- Details: A hook function to customize the Shiki highlighter instance.
### transformers
- Type: `ShikiTransformer[]`
+- Details: Shiki transformers.
-- Details:
-
- Transformers of Shiki.
-
- This option will be forwarded to `codeToHtml()` method of Shiki.
+ This option will be passed to the `codeToHtml()` method of Shiki.
- Also see:
- [Shiki > Transformers](https://shiki.style/guide/transformers)
diff --git a/docs/zh/plugins/markdown/shiki.md b/docs/zh/plugins/markdown/shiki.md
index 768c94398b..dbbc8601e4 100644
--- a/docs/zh/plugins/markdown/shiki.md
+++ b/docs/zh/plugins/markdown/shiki.md
@@ -6,11 +6,11 @@ icon: highlighter
-该插件使用 [Shiki](https://shiki.tmrs.site/) 来为 Markdown 代码块启用代码高亮。
+该插件使用 [Shiki](https://shiki.tmrs.site/) 为 Markdown 代码块启用语法高亮。
::: tip
-[Shiki](https://shiki.tmrs.site/) 是 VSCode 正在使用的代码高亮器。它具有更高的保真度，但可能会比 [Prism.js](https://prismjs.com/) 要慢一些，特别是在有大量代码块需要处理的时候。
+[Shiki](https://shiki.tmrs.site/) 是 VSCode 使用的语法高亮器。它提供更高保真度的高亮效果，但在处理大量代码块时可能比 [Prism.js](https://prismjs.com/) 慢一些。
:::
@@ -45,7 +45,7 @@ export default {
::: tip
- 插件现在会自动加载你的 markdown 文件中使用的语言，所以你不需要手动指定它们。
+ 插件会自动加载你的 Markdown 文件中使用的语言，无需手动指定。
:::
@@ -55,11 +55,8 @@ export default {
### langAlias
- 类型：`{ [lang: string]: string }`
-
- 详情：自定义 Shiki 语言别名。
- 自定义 Shiki 语言别名。
-
- 参考：
- [Shiki > 自定义语言别名](https://shiki.tmrs.site/guide/load-lang#custom-language-aliases)
@@ -69,7 +66,7 @@ export default {
- 默认值：`'nord'`
-- 详情：Shiki 的主题。该主题会应用到代码块上。
+- 详情：Shiki 主题，应用于代码块。
- 参考：
- [Shiki > 主题](https://shiki.tmrs.site/themes)
@@ -82,7 +79,7 @@ export default {
Shiki 的暗黑和明亮模式双主题。
- 两个主题的样式会分别通过 `--shiki-light` 和 `--shiki-dark` 注入到代码块上：
+ 两个主题的样式会分别通过 `--shiki-light` 和 `--shiki-dark` CSS 变量注入到代码块：
```html
code
@@ -94,18 +91,16 @@ export default {
### lineNumbers
- 类型：`boolean | number | 'disable'`
-
- 默认值：`true`
-
-- 详情：
+- 详情：控制行号的显示。
- `number`：显示行号所需的最少行数。
- 例如，如果你将它设置为 4 ，那么只有在你的代码块包含至少 4 行代码时才会启用行号。
- - `true`：全局启用代码行号
- - `false`：全局禁用代码行号。
- - `'disable'`: 完全禁用行号，`:line-numbers` 标记不会生效。
+ 例如，设置为 4 时，只有代码块包含至少 4 行代码才会启用行号。
+ - `true`：全局启用行号
+ - `false`：全局禁用行号
+ - `'disable'`：完全禁用行号，`:line-numbers` 标记不生效。
- 你可以在代码块添加 `:line-numbers` / `:no-line-numbers` 标记来覆盖配置项中的设置，还可以在 `:line-numbers` 之后添加 `=` 来自定义起始行号，例如 `:line-numbers=2` 表示代码块中的行号从 `2` 开始。
+ 你可以在代码块添加 `:line-numbers` / `:no-line-numbers` 标记来覆盖配置项设置，还可以在 `:line-numbers` 之后添加 `=` 来自定义起始行号，例如 `:line-numbers=2` 表示代码块行号从 `2` 开始。
::: preview
@@ -132,12 +127,8 @@ const line4 = 'This is line 4'
### highlightLines
- 类型：`boolean`
-
- 默认值：`true`
-
-- 详情：
-
- 是否启用行高亮。启用后，可在代码块的信息描述中添加行数标记来高亮指定的行：
+- 详情：是否启用行高亮。启用后，可在代码块信息描述中添加行数标记来高亮指定行：
- 行数范围：`{5-8}`
- 多个单行：`{4,7,9}`
@@ -165,17 +156,15 @@ export default defineUserConfig({
### collapsedLines
- 类型：`boolean | number | 'disable'`
-
- 默认值：`'disable'`
-
- 详情：代码块折叠的默认行为。
- - `number`: 从第 `number` 行开始折叠代码块，例如，`12` 表示从第 12 行开始折叠代码块。
- - `true`: 等同于 `15`, 从第 15 行开始折叠代码块。
- - `false`: 添加代码块折叠支持，但全局禁用此功能
- - `'disable'`: 完全禁用代码块折叠， `:collapsed-lines` 标记不会生效。
+ - `number`：从第 `number` 行开始折叠代码块，例如 `12` 表示从第 12 行开始折叠。
+ - `true`：等同于 `15`，从第 15 行开始折叠。
+ - `false`：添加代码块折叠支持，但全局禁用此功能
+ - `'disable'`：完全禁用代码块折叠，`:collapsed-lines` 标记不生效。
- 你可以在代码块添加 `:collapsed-lines` / `:no-collapsed-lines` 标记来覆盖配置项中的设置。还可以在 `:collapsed-lines` 之后添加 `=` 来自定义起始折叠行号，例如 `:collapsed-lines=12` 表示代码块从第 12 行开始折叠。
+ 你可以在代码块添加 `:collapsed-lines` / `:no-collapsed-lines` 标记来覆盖配置项设置。还可以在 `:collapsed-lines` 之后添加 `=` 来自定义起始折叠行号，例如 `:collapsed-lines=12` 表示代码块从第 12 行开始折叠。
::: preview
@@ -289,7 +278,6 @@ body > div {
```
- 默认值：`true`
-
- 详情：是否启用代码块标题渲染。在代码块 \`\`\` 后面添加 `title="标题"` 来设置标题。
传入 `CodeBlockTitleRender` 以自定义标题渲染。
@@ -307,9 +295,7 @@ body > div {
### notationDiff
- 类型：`boolean`
-
- 默认值：`false`
-
- 详情：是否启用差异标记。
- 示例：
@@ -343,9 +329,7 @@ body > div {
### notationFocus
- 类型：`boolean`
-
- 默认值：`false`
-
- 详情：是否启用聚焦标记。
- 示例：
@@ -379,9 +363,7 @@ body > div {
### notationHighlight
- 类型：`boolean`
-
- 默认值：`false`
-
- 详情：是否启用高亮标记。
- 示例：
@@ -415,9 +397,7 @@ body > div {
### notationErrorLevel
- 类型：`boolean`
-
- 默认值：`false`
-
- 详情：是否启用错误级别标记。
- 示例：
@@ -451,16 +431,14 @@ body > div {
### notationWordHighlight
- 类型：`boolean`
-
- 默认值：`false`
-
- 详情：是否启用词高亮标记。
- 词高亮标记 必须单独写在一行。
+ 词高亮标记必须单独写在一行。
- 示例：
- 根据注释中提供的字符串，高亮显示词。
+ 根据注释中提供的字符串高亮显示词。
@@ -485,7 +463,7 @@ body > div {
- 根据代码片段中提供的元字符串，高亮显示词
+ 根据代码片段中提供的元字符串高亮显示词
::: preview
@@ -503,18 +481,16 @@ body > div {
### whitespace
- 类型：`boolean | 'all' | 'boundary' | 'trailing'`
-
- 默认值：`false`
+- 详情：是否启用空白符（空格和 Tab）渲染。
-- 详情：是否启用空白符（空格 和 Tab）渲染。
+ - `true`：启用空白符渲染，但默认不渲染任何空白符
+ - `false`：完全禁用空白符渲染，`:whitespace` 标记不生效
+ - `'all'`：渲染所有空白符
+ - `'boundary'`：仅渲染行首行尾的空白符
+ - `'trailing'`：仅渲染行尾的空白符
- - `true`: 启用空白符渲染，但默认不渲染任何空白符
- - `false`: 完全禁用空白符渲染，`:whitespace` 标记不会生效。
- - `'all'`: 渲染所有空白符
- - `'boundary'`: 仅渲染行首行尾的空白符
- - `'trailing'`: 仅渲染行尾的空白符
-
- 你可以在代码块中添加 `:whitespace / :no-whitespace` 标记来覆盖配置项中的设置。还可以在 `:whitespace` 之后添加 `=` 来定义渲染空白符的方式。比如 `:whitespace=boundary` 将渲染行首行尾的空白符。
+ 你可以在代码块中添加 `:whitespace / :no-whitespace` 标记来覆盖配置项设置。还可以在 `:whitespace` 之后添加 `=` 来定义渲染空白符的方式，例如 `:whitespace=boundary` 将渲染行首行尾的空白符。
- 示例：
@@ -588,12 +564,11 @@ body > div {
```
- 默认值： `false`
-
-- 详情： 是否启用 [twoslash](https://github.com/twoslashes/twoslash).
+- 详情：是否启用 [twoslash](https://github.com/twoslashes/twoslash)。
::: tip
- 出于体积考虑，该插件默认不包含`@vuepress/shiki-twoslash`包。如需使用，需手动安装。
+ 出于体积考虑，该插件默认不包含 `@vuepress/shiki-twoslash` 包。如需使用，需手动安装。
:::
@@ -620,8 +595,8 @@ body > div {
对于启用了 `twoslash` 的代码块：
- - 不要在代码块中添加 `:v-pre` 标记, 这会导致 `twoslash` 无法正常运行。
- - 为避免布局上的冲突，代码块不再显示 **行数** 。
+ - 不要在代码块中添加 `:v-pre` 标记，这会导致 `twoslash` 无法正常运行
+ - 为避免布局冲突，代码块不再显示**行号**
:::
@@ -630,52 +605,38 @@ body > div {
### defaultLang
- 类型：`string`
-
-- 默认值：`''`
-
-- 详情：指定的语言不可用时所使用的备选语言。
+- 默认值：`'plain'`
+- 详情：指定语言不可用时所使用的备选语言。
### logLevel
- 类型：`'warn' | 'debug' | 'silent'`
-
- 默认值：`'warn'`
+- 详情：Shiki 语言检测的日志级别。
-- 详情：
-
- Shiki 语言检测的日志级别。
-
- - `warn`: 每次检测到未知语言时发出警告（默认）
- - `debug`: 每次检测到未知代码块时记录其文件路径（设置 `--debug` 标记时默认）
- - `silent`: 不发出警告
+ - `warn`：每次检测到未知语言时发出警告（默认）
+ - `debug`：每次检测到未知代码块时记录其文件路径（设置 `--debug` 标记时默认）
+ - `silent`：不发出警告
### preWrapper
- 类型：`boolean`
-
- 默认值：`true`
+- 详情：是否在 `` 标签外添加包裹容器。
-- 详情：
-
- 是否在 `` 标签外添加包裹容器。
-
- `lineNumbers` 和 `collapsedLines` 依赖于这个额外的包裹层。这换句话说，如果你禁用了 `preWrapper` ，那么行号和折叠代码块也会被同时禁用。
+ `lineNumbers` 和 `collapsedLines` 依赖于这个额外的包裹层。换句话说，如果你禁用了 `preWrapper`，那么行号和折叠代码块也会被同时禁用。
### shikiSetup
- 类型：`(shiki: Highlighter) => void | Promise`
-
-- 详情： 一个用于自定义 Shiki 高亮器的钩子函数。
+- 详情：用于自定义 Shiki 高亮器的钩子函数。
### transformers
- 类型：`ShikiTransformer[]`
+- 详情：添加 Shiki 转换器。
-- 详情：
-
- 添加 Shiki 转换器。
-
- 该配置项会被传递到 Shiki 的 `codeToHtml()` 方法中。
+ 该配置项会被传递到 Shiki 的 `codeToHtml()` 方法。
- 参考：
- [Shiki > 转换器](https://shiki.tmrs.site/guide/transformers)
diff --git a/plugins/markdown/plugin-shiki/src/node/markdown/highlighter/createMarkdownFilePathGetter.ts b/plugins/markdown/plugin-shiki/src/node/markdown/highlighter/createMarkdownFilePathGetter.ts
index 1de0a9a8a0..c4f66aed85 100644
--- a/plugins/markdown/plugin-shiki/src/node/markdown/highlighter/createMarkdownFilePathGetter.ts
+++ b/plugins/markdown/plugin-shiki/src/node/markdown/highlighter/createMarkdownFilePathGetter.ts
@@ -1,8 +1,22 @@
import type MarkdownIt from 'markdown-it'
import type { MarkdownEnv } from 'vuepress/markdown'
+/**
+ * Markdown file path getter function type
+ *
+ * Markdown 文件路径获取器函数类型
+ */
export type MarkdownFilePathGetter = () => string
+/**
+ * Create a function to get current markdown file path
+ *
+ * 创建获取当前 markdown 文件路径的函数
+ *
+ * @param md - MarkdownIt instance / MarkdownIt 实例
+ *
+ * @returns Function to get current markdown file path / 获取当前 markdown 文件路径的函数
+ */
export const createMarkdownFilePathGetter = (
md: MarkdownIt,
): MarkdownFilePathGetter => {
diff --git a/plugins/markdown/plugin-shiki/src/node/markdown/highlighter/createShikiHighlighter.ts b/plugins/markdown/plugin-shiki/src/node/markdown/highlighter/createShikiHighlighter.ts
index 4e85ad1fb1..a2c27d6396 100644
--- a/plugins/markdown/plugin-shiki/src/node/markdown/highlighter/createShikiHighlighter.ts
+++ b/plugins/markdown/plugin-shiki/src/node/markdown/highlighter/createShikiHighlighter.ts
@@ -20,8 +20,26 @@ const resolveLangSync = createSyncFn(
require.resolve('@vuepress/plugin-shiki/resolveLang'),
)
+/**
+ * Load language function type
+ *
+ * 加载语言函数类型
+ */
export type ShikiLoadLang = (lang: string) => boolean
+/**
+ * Create Shiki highlighter with additional features
+ *
+ * 创建带有额外功能的 Shiki 高亮器
+ *
+ * @param app - VuePress app instance / VuePress 应用实例
+ * @param options - Plugin options / 插件选项
+ * @param enableVPre - Whether to enable v-pre transformer / 是否启用 v-pre 转换器
+ *
+ * @default enableVPre: true
+ *
+ * @returns Object containing highlighter, loadLang function and extra transformers / 包含高亮器、loadLang 函数和额外转换器的对象
+ */
export const createShikiHighlighter = async (
app: App,
{
diff --git a/plugins/markdown/plugin-shiki/src/node/markdown/highlighter/getHighLightFunction.ts b/plugins/markdown/plugin-shiki/src/node/markdown/highlighter/getHighLightFunction.ts
index b62747ba40..0d8585c4e7 100644
--- a/plugins/markdown/plugin-shiki/src/node/markdown/highlighter/getHighLightFunction.ts
+++ b/plugins/markdown/plugin-shiki/src/node/markdown/highlighter/getHighLightFunction.ts
@@ -22,6 +22,19 @@ type MarkdownItHighlight = (
attrs: string,
) => string
+/**
+ * Get highlight function for markdown-it
+ *
+ * 获取 markdown-it 的高亮函数
+ *
+ * @param highlighter - Shiki highlighter instance / Shiki 高亮器实例
+ * @param options - Highlight options / 高亮选项
+ * @param extraTransformers - Extra transformers / 额外转换器
+ * @param loadLang - Language loader function / 语言加载函数
+ * @param markdownFilePathGetter - Markdown file path getter / Markdown 文件路径获取器
+ *
+ * @returns Highlight function for markdown-it / markdown-it 的高亮函数
+ */
export const getHighLightFunction = (
highlighter: HighlighterGeneric,
options: ShikiHighlightOptions,
diff --git a/plugins/markdown/plugin-shiki/src/node/markdown/preWrapperPlugin.ts b/plugins/markdown/plugin-shiki/src/node/markdown/preWrapperPlugin.ts
index 7511a123a2..ccf8a76170 100644
--- a/plugins/markdown/plugin-shiki/src/node/markdown/preWrapperPlugin.ts
+++ b/plugins/markdown/plugin-shiki/src/node/markdown/preWrapperPlugin.ts
@@ -15,6 +15,16 @@ export interface MarkdownItPreWrapperOptions {
preWrapper?: boolean
}
+/**
+ * A markdown-it plugin for wrapping `` tag with an extra ``
+ *
+ * 一个用于为 `
` 标签添加额外 `` 包装的 markdown-it 插件
+ *
+ * @param md - MarkdownIt instance / MarkdownIt 实例
+ * @param options - Plugin options / 插件选项
+ *
+ * @default { preWrapper: true }
+ */
export const preWrapperPlugin = (
md: Markdown,
{ preWrapper = true }: MarkdownItPreWrapperOptions = {},
diff --git a/plugins/markdown/plugin-shiki/src/node/options.ts b/plugins/markdown/plugin-shiki/src/node/options.ts
index c20cfca25a..2cc50a05f2 100644
--- a/plugins/markdown/plugin-shiki/src/node/options.ts
+++ b/plugins/markdown/plugin-shiki/src/node/options.ts
@@ -9,6 +9,8 @@ import type { ShikiHighlightOptions } from './types.js'
/**
* Options of @vuepress/plugin-shiki
+ *
+ * @vuepress/plugin-shiki 的选项
*/
export type ShikiPluginOptions = MarkdownItCodeBlockTitleOptions &
MarkdownItLineNumbersOptions &
@@ -18,8 +20,12 @@ export type ShikiPluginOptions = MarkdownItCodeBlockTitleOptions &
/**
* Enable twoslash
*
+ * 启用 twoslash
+ *
* @description You should install `@shikijs/twoslash` manually.
*
+ * 你需要手动安装 `@shikijs/twoslash`。
+ *
* @default false
*/
twoslash?:
@@ -27,6 +33,9 @@ export type ShikiPluginOptions = MarkdownItCodeBlockTitleOptions &
| (ShikiTwoslashOptions & {
/**
* The options for caching resolved types
+ *
+ * 缓存解析类型的选项
+ *
* @default true
*/
typesCache?: ShikiTwoslashOptions['typesCache'] | true
diff --git a/plugins/markdown/plugin-shiki/src/node/shikiPlugin.ts b/plugins/markdown/plugin-shiki/src/node/shikiPlugin.ts
index ccced3ebea..59099a0f1e 100644
--- a/plugins/markdown/plugin-shiki/src/node/shikiPlugin.ts
+++ b/plugins/markdown/plugin-shiki/src/node/shikiPlugin.ts
@@ -23,30 +23,54 @@ import type { ShikiPluginOptions } from './options.js'
import { prepareClientConfigFile } from './prepareClientConfigFile.js'
import { TWOSLASH_RE, logger } from './utils.js'
-export const shikiPlugin = (_options: ShikiPluginOptions = {}): Plugin => {
+/**
+ * Shiki plugin for VuePress
+ *
+ * VuePress 的 Shiki 插件
+ *
+ * @param options - Plugin options / 插件选项
+ *
+ * @returns VuePress plugin / VuePress 插件
+ *
+ * @example
+ * ```ts
+ * import { shikiPlugin } from '@vuepress/plugin-shiki'
+ *
+ * export default {
+ * plugins: [
+ * shikiPlugin({
+ * langs: ['ts', 'json', 'vue', 'md', 'bash', 'diff'],
+ * theme: 'nord',
+ * lineNumbers: true,
+ * }),
+ * ],
+ * }
+ * ```
+ */
+export const shikiPlugin = (options: ShikiPluginOptions = {}): Plugin => {
return (app) => {
// FIXME: Remove in stable version
// eslint-disable-next-line @typescript-eslint/no-deprecated
const { code } = app.options.markdown
- const options = {
+ const shikiOptions = {
...(isPlainObject(code) ? code : {}),
- ..._options,
+ ...options,
}
- options.logLevel ??= app.env.isDebug ? 'debug' : 'warn'
- options.preWrapper ??= true
- options.lineNumbers ??= true
- options.collapsedLines ??= 'disable'
- options.codeBlockTitle ??= true
+ shikiOptions.logLevel ??= app.env.isDebug ? 'debug' : 'warn'
+ shikiOptions.preWrapper ??= true
+ shikiOptions.lineNumbers ??= true
+ shikiOptions.collapsedLines ??= 'disable'
+ shikiOptions.codeBlockTitle ??= true
if (
- options.twoslash &&
+ shikiOptions.twoslash &&
!isModuleAvailable('@vuepress/shiki-twoslash', import.meta)
) {
logger.error(
`${colors.cyan('twoslash')} is enabled, but ${colors.magenta('@vuepress/shiki-twoslash')} is not installed, please install it manually`,
)
- options.twoslash = false
+ shikiOptions.twoslash = false
}
/**
@@ -75,15 +99,15 @@ export const shikiPlugin = (_options: ShikiPluginOptions = {}): Plugin => {
extendsMarkdown: async (md) => {
const { preWrapper, lineNumbers, collapsedLines, codeBlockTitle } =
- options
+ shikiOptions
const markdownFilePathGetter = createMarkdownFilePathGetter(md)
const { highlighter, loadLang, extraTransformers } =
- await createShikiHighlighter(app, options, enableVPre)
+ await createShikiHighlighter(app, shikiOptions, enableVPre)
md.options.highlight = getHighLightFunction(
highlighter,
- options,
+ shikiOptions,
extraTransformers,
loadLang,
markdownFilePathGetter,
@@ -94,7 +118,7 @@ export const shikiPlugin = (_options: ShikiPluginOptions = {}): Plugin => {
md.use(lineNumbersPlugin, {
lineNumbers,
resolveLineNumbers(info) {
- return options.twoslash && TWOSLASH_RE.test(info)
+ return shikiOptions.twoslash && TWOSLASH_RE.test(info)
? false
: undefined
},
@@ -108,7 +132,7 @@ export const shikiPlugin = (_options: ShikiPluginOptions = {}): Plugin => {
}
},
- clientConfigFile: () => prepareClientConfigFile(app, options),
+ clientConfigFile: () => prepareClientConfigFile(app, shikiOptions),
}
}
}
diff --git a/plugins/markdown/plugin-shiki/src/node/types.ts b/plugins/markdown/plugin-shiki/src/node/types.ts
index d850f576f6..ccc5595ec4 100644
--- a/plugins/markdown/plugin-shiki/src/node/types.ts
+++ b/plugins/markdown/plugin-shiki/src/node/types.ts
@@ -10,13 +10,28 @@ import type {
ThemeRegistrationAny,
} from 'shiki'
+/**
+ * Shiki language type
+ *
+ * Shiki 语言类型
+ */
export type ShikiLang =
| LanguageInput
| SpecialLanguage
| StringLiteralUnion
+/**
+ * Shiki theme type
+ *
+ * Shiki 主题类型
+ */
export type ShikiTheme = StringLiteralUnion | ThemeRegistrationAny
+/**
+ * Single theme options for Shiki
+ *
+ * Shiki 单主题配置
+ */
export interface ShikiSingleThemeOptions {
/**
* The single theme to use
@@ -28,6 +43,11 @@ export interface ShikiSingleThemeOptions {
theme?: ShikiTheme
}
+/**
+ * Dual theme options for Shiki
+ *
+ * Shiki 双主题配置
+ */
export interface ShikiDualThemeOptions {
/**
* The dark and light themes to use
@@ -40,8 +60,18 @@ export interface ShikiDualThemeOptions {
}
}
+/**
+ * Shiki theme options
+ *
+ * Shiki 主题配置选项
+ */
export type ShikiThemeOptions = ShikiDualThemeOptions | ShikiSingleThemeOptions
+/**
+ * Shiki highlight options
+ *
+ * Shiki 高亮配置选项
+ */
export type ShikiHighlightOptions = ShikiThemeOptions & {
/**
* Languages to be loaded.
@@ -49,6 +79,10 @@ export type ShikiHighlightOptions = ShikiThemeOptions & {
* Shiki does not preload any languages to avoid extra overhead. So you need
* to specify the languages you want to use.
*
+ * 要加载的语言。
+ *
+ * Shiki 不会预加载任何语言以避免额外开销。所以你需要指定要使用的语言。
+ *
* @see https://shiki.style/languages
*/
langs?: ShikiLang[]
@@ -56,6 +90,8 @@ export type ShikiHighlightOptions = ShikiThemeOptions & {
/**
* Language alias
*
+ * 语言别名
+ *
* @see https://shiki.style/guide/load-lang#custom-language-aliases
*/
langAlias?: Record>
@@ -63,23 +99,31 @@ export type ShikiHighlightOptions = ShikiThemeOptions & {
/**
* Fallback language when the specified language is not available.
*
+ * 指定语言不可用时的备选语言。
+ *
* @default 'plain'
*/
defaultLang?: string
/**
* Function to customize Shiki highlighter instance.
+ *
+ * 自定义 Shiki 高亮器实例的函数。
*/
shikiSetup?: (shiki: Highlighter) => Promise | void
/**
* Shiki transformers
+ *
+ * Shiki 转换器
*/
transformers?: ShikiTransformer[]
/**
* Enable highlight lines or not
*
+ * 是否启用行高亮
+ *
* @default true
*/
highlightLines?: boolean
@@ -87,6 +131,8 @@ export type ShikiHighlightOptions = ShikiThemeOptions & {
/**
* Enable notation diff transformer
*
+ * 是否启用差异标记转换器
+ *
* @default false
*
* @see https://shiki.style/packages/transformers#transformernotationdiff
@@ -96,6 +142,8 @@ export type ShikiHighlightOptions = ShikiThemeOptions & {
/**
* Enable notation focus transformer
*
+ * 是否启用聚焦标记转换器
+ *
* @default false
*
* @see https://shiki.style/packages/transformers#transformernotationfocus
@@ -105,6 +153,8 @@ export type ShikiHighlightOptions = ShikiThemeOptions & {
/**
* Enable notation highlight transformer
*
+ * 是否启用高亮标记转换器
+ *
* @default false
*
* @see https://shiki.style/packages/transformers#transformernotationhighlight
@@ -114,6 +164,8 @@ export type ShikiHighlightOptions = ShikiThemeOptions & {
/**
* Enable notation error level transformer
*
+ * 是否启用错误级别标记转换器
+ *
* @default false
*
* @see https://shiki.style/packages/transformers#transformernotationerrorlevel
@@ -123,6 +175,8 @@ export type ShikiHighlightOptions = ShikiThemeOptions & {
/**
* Enable notation word highlight transformer
*
+ * 是否启用单词高亮标记转换器
+ *
* @default false
*
* @see https://shiki.style/packages/transformers#transformernotationwordhighlight
@@ -137,9 +191,16 @@ export type ShikiHighlightOptions = ShikiThemeOptions & {
* - 'boundary': render leading and trailing whitespace of each line.
* - 'trailing': render trailing whitespace of each line
*
- * you are able to use `:whitespace` or `:no-whitespace` or `:whitespace=position` to set single code block
+ * you are able to use `:whitespace` or `:no-whitespace` or `:whitespace=all|boundary|trailing` to set single code block
*
- * position: 'all' | 'boundary' | 'trailing'
+ * 启用空白字符显示
+ * - true: 启用空白字符，但默认不渲染任何空白字符
+ * - false: 完全禁用空白字符
+ * - 'all': 渲染所有空白字符
+ * - 'boundary': 渲染每行的前导和尾随空白字符
+ * - 'trailing': 渲染每行的尾随空白字符
+ *
+ * 你可以使用 `:whitespace` 或 `:no-whitespace` 或 `:whitespace=all|boundary|trailing` 来设置单个代码块
*
* @default false
*
@@ -150,8 +211,12 @@ export type ShikiHighlightOptions = ShikiThemeOptions & {
/**
* Log level Highlighter language detecter
*
+ * 高亮器语言检测器的日志级别
+ *
* @description defaults to `'debug'` when `--debug` flag is enabled
*
+ * 当启用 `--debug` 标志时默认为 `'debug'`
+ *
* @default 'warn'
*/
logLevel?: 'debug' | 'silent' | 'warn'
diff --git a/plugins/markdown/plugin-shiki/src/node/utils.ts b/plugins/markdown/plugin-shiki/src/node/utils.ts
index 454a2f0921..067fd3220b 100644
--- a/plugins/markdown/plugin-shiki/src/node/utils.ts
+++ b/plugins/markdown/plugin-shiki/src/node/utils.ts
@@ -12,6 +12,15 @@ export const logger = new Logger(PLUGIN_NAME)
export const nanoid = customAlphabet('abcdefghijklmnopqrstuvwxyz', 10)
+/**
+ * Resolve language from code fence info string
+ *
+ * 从代码围栏信息字符串中解析语言
+ *
+ * @param info - Code fence info string / 代码围栏信息字符串
+ *
+ * @returns Resolved language / 解析的语言
+ */
export const resolveLanguage = (info: string): string =>
info
.match(/^([^ :[{]+)/)?.[1]
@@ -19,12 +28,23 @@ export const resolveLanguage = (info: string): string =>
.toLowerCase() ?? ''
/**
- * 2 steps:
+ * Convert attributes to line options
*
+ * 将属性转换为行选项
+ *
+ * @description 2 steps:
* 1. convert attrs into line numbers:
* {4,7-13,16,23-27,40} -> [4,7,8,9,10,11,12,13,16,23,24,25,26,27,40]
* 2. convert line numbers into line options:
* [{ line: number, classes: string[] }]
+ *
+ * 转换分为两步：
+ * 1. 将属性转换为行号数组
+ * 2. 将行号数组转换为行选项
+ *
+ * @param attrs - Attributes string / 属性字符串
+ *
+ * @returns Line options array / 行选项数组
*/
export const attrsToLines = (attrs: string): TransformerCompactLineOption[] => {
const attrsContent = attrs