From 64ecf2af34101eae56ad3cbc11cccd864fd46077 Mon Sep 17 00:00:00 2001 From: Mister-Hope Date: Thu, 5 Jun 2025 14:22:37 +0800 Subject: [PATCH 1/3] refactor(plugin-prismjs): add jsdoc and improve docs --- .github/copilot-instructions.md | 6 +- docs/plugins/markdown/prismjs.md | 64 +++++++++---------- docs/zh/plugins/markdown/prismjs.md | 60 +++++++++-------- .../plugin-prismjs/src/node/loadLanguages.ts | 11 ++++ .../src/node/markdown/highlightPlugin.ts | 39 ++++++++++- .../src/node/markdown/preWrapperPlugin.ts | 20 ++++++ .../plugin-prismjs/src/node/options.ts | 2 + .../src/node/parser/createNotationRule.ts | 16 +++++ .../src/node/parser/getCodeParser.ts | 18 ++++++ .../src/node/parser/highlightLines.ts | 32 ++++++++++ .../src/node/parser/highlightWord.ts | 22 ++++++- .../src/node/parser/notation.ts | 21 +++++- .../src/node/parser/whitespace.ts | 34 +++++++++- .../plugin-prismjs/src/node/prismjsPlugin.ts | 21 ++++++ .../src/node/resolveHighlighter.ts | 12 ++++ .../markdown/plugin-prismjs/src/node/types.ts | 8 +++ .../src/node/utils/escapeRegExp.ts | 15 +++++ .../src/node/utils/resolveLanguage.ts | 12 ++++ 18 files changed, 340 insertions(+), 73 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 4da3c8c2ff..0f4fac5aef 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -50,13 +50,13 @@ ### Format Requirements +- **Exported Content**: Only contents that are exported from the package. - **Bilingual**: English + Chinese for all exported content -- **@default**: - - User-visible things: Always include if exists (including `@default false`) - - Others: Only when not clearly visible in function parameters +- **@default**: Always include if exists for all properties (including `@default false`) - **@example**: Only for exported functions - **@description**: Optional, only if necessary to explain more - **@param**: Required for all parameters, should be bilingual, separate with `/` for English and Chinese +- **@returns**: Required for all return values expect `void` and `Promise`, should be bilingual, separate with `/` for English and Chinese ````typescript /** diff --git a/docs/plugins/markdown/prismjs.md b/docs/plugins/markdown/prismjs.md index bd110d5542..4885ecc331 100644 --- a/docs/plugins/markdown/prismjs.md +++ b/docs/plugins/markdown/prismjs.md @@ -6,12 +6,10 @@ icon: pyramid -This plugin will enable syntax highlighting for markdown code fence with [Prism.js](https://prismjs.com/). +This plugin enables syntax highlighting for markdown code fences with [Prism.js](https://prismjs.com/). This plugin has been integrated into the default theme. -Notice that this plugin would only tokenize the code fence without adding styles. When using it with a custom theme, you may need to choose and import Prism.js style theme yourself. - ## Usage ```bash @@ -38,7 +36,7 @@ export default { - Default: `'nord'` -- Details: Theme of Prismjs, will be applied to code blocks. +- Details: Prism.js theme that will be applied to code blocks. ### themes @@ -46,9 +44,9 @@ export default { - Details: - Apply Light / Dark Dual themes. + Apply light/dark dual themes. - Note: To use this, your theme must set `data-theme="dark"` attribute on the `` tag when dark mode is enabled. + Note: To use this feature, your theme must set the `data-theme="dark"` attribute on the `` tag when dark mode is enabled. ::: tip Available Prism.js Light themes @@ -103,13 +101,13 @@ export default { - Details: - - `number`: the minimum number of lines to enable line numbers. + - `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. - - `true`: enable line numbers globally. - - `false`: disable line numbers globally. - - `'disable'`: Completely disable line numbers, `:line-numbers` will not take effect. + - `true`: Enable line numbers globally. + - `false`: Disable line numbers globally. + - `'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 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`. ::: preview @@ -126,7 +124,7 @@ const line3 = 'This is line 3' ``` ```ts :line-numbers=2 -// line-numbers is enabled and start from 2 +// line-numbers is enabled and starts from 2 const line3 = 'This is line 3' const line4 = 'This is line 4' ``` @@ -141,7 +139,7 @@ const line4 = 'This is line 4' - 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: + Whether to enable code line highlighting. You can highlight specified lines of your code blocks by adding line range markers in your fenced code blocks: - Line ranges: `{5-8}` - Multiple single lines: `{4,7,9}` @@ -172,12 +170,12 @@ export default defineUserConfig({ - 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. + - `number`: Collapse the code block starting from line `number` by default. For example, `12` means collapsing the code block starting from line 12. - `true`: Equivalent to `15`, collapsing the code block starting from line 15 by default. - - `false`: Add support for code block collapsing, but disable it globally - - `'disable'`: Completely disable code block collapsing, `:collapsed-lines` will not take effect. + - `false`: Add support for code block collapsing, but disable it globally. + - `'disable'`: Completely disable code block collapsing; `:collapsed-lines` will not take effect. - To override global settings, you can add the `:collapsed-lines` / `:no-collapsed-lines` marker to the code block. You can also add `=` after `:collapsed-lines` to customize the starting line number being collapsed, for example, `:collapsed-lines=12` means collapsing the code block starting from line 12. + To override global settings, you can add the `:collapsed-lines` / `:no-collapsed-lines` markers to the code block. You can also add `=` after `:collapsed-lines` to customize the starting line number being collapsed. For example, `:collapsed-lines=12` means collapsing the code block starting from line 12. ::: preview @@ -318,7 +316,7 @@ In the new version, some functionalities similar to [shiki](https://shiki.style/ - Default: `false` -- Details: Whether enable notation diff. +- Details: Whether to enable notation diff. - Example: @@ -354,7 +352,7 @@ In the new version, some functionalities similar to [shiki](https://shiki.style/ - Default: `false` -- Details: Whether enable notation focus. +- Details: Whether to enable notation focus. - Example: @@ -390,7 +388,7 @@ In the new version, some functionalities similar to [shiki](https://shiki.style/ - Default: `false` -- Details: Whether enable notation highlight. +- Details: Whether to enable notation highlight. - Example: @@ -426,7 +424,7 @@ In the new version, some functionalities similar to [shiki](https://shiki.style/ - Default: `false` -- Details: Whether enable notation error level. +- Details: Whether to enable notation error level. - Example: @@ -462,7 +460,7 @@ In the new version, some functionalities similar to [shiki](https://shiki.style/ - Default: `false` -- Details: Whether enable notation word highlight. +- Details: Whether to enable notation word highlight. Word highlight must be written on a separate line. @@ -514,15 +512,15 @@ In the new version, some functionalities similar to [shiki](https://shiki.style/ - Default: `false` -- Details: Whether enable whitespace characters (Space and Tab). +- Details: Whether to enable whitespace characters (Space and Tab). - - `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, but not render any whitespace by default. + - `false`: Completely disable whitespace rendering; `: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. - 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 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. - Example: @@ -566,7 +564,7 @@ In the new version, some functionalities similar to [shiki](https://shiki.style/ ::: -- Also see： +- Also see: - [Shiki > Render Whitespace](https://shiki.style/packages/transformers#transformerrenderwhitespace) ### preloadLanguages @@ -591,12 +589,12 @@ In the new version, some functionalities similar to [shiki](https://shiki.style/ - Details: - Adds extra wrapper outside `
` tag or not.
+  Whether to add an extra wrapper outside the `
` tag.
 
-  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.
+  The wrapper is required by `lineNumbers` and `collapsedLines`. This means if you disable `preWrapper`, the line numbers and collapsed lines will also be disabled.
 
   ::: tip
 
-  You can disable it if you want to implement them in client side. For example, [Prismjs Line Highlight](https://prismjs.com/plugins/line-highlight/) or [Prismjs Line Numbers](https://prismjs.com/plugins/line-numbers/).
+  You can disable it if you want to implement them on the client side. For example, [Prismjs Line Highlight](https://prismjs.com/plugins/line-highlight/) or [Prismjs Line Numbers](https://prismjs.com/plugins/line-numbers/).
 
   :::
diff --git a/docs/zh/plugins/markdown/prismjs.md b/docs/zh/plugins/markdown/prismjs.md
index 6cf0cac8a5..6f0f041488 100644
--- a/docs/zh/plugins/markdown/prismjs.md
+++ b/docs/zh/plugins/markdown/prismjs.md
@@ -10,8 +10,6 @@ icon: pyramid
 
 该插件已经集成到默认主题中。
 
-需要注意的是，该插件仅会给代码块添加 HTML 标记，而不会添加样式。当你在一个自定义主题中使用它时，可能需要自己选择并引入 Prism.js 样式主题。
-
 ## 使用方法
 
 ```bash
@@ -38,7 +36,7 @@ export default {
 
 - 默认值：`'nord'`
 
-- 详情：Prismjs 的主题。该主题会应用到代码块上。
+- 详情：Prismjs 的主题，会应用到代码块上。
 
 ### themes
 
@@ -46,9 +44,9 @@ export default {
 
 - 详情：
 
-  使用暗黑和明亮模式双主题。
+  使用亮暗双主题。
 
-  注意：想使用这个功能，你的主题必须在夜间模式下在 `` 标签上 `data-theme="dark"` 属性。
+  注意：想使用此功能，你的主题必须在夜间模式下在 `` 标签上设置 `data-theme="dark"` 属性。
 
 ::: tip 可用的 Prism.js 浅色主题
 
@@ -104,10 +102,10 @@ export default {
 - 详情：
 
   - `number`：显示行号所需的最少行数。
-    例如，如果你将它设置为 4 ，那么只有在你的代码块包含至少 4 行代码时才会启用行号。
-  - `true`：全局启用代码行号
+    例如，如果你将它设置为 4，那么只有在你的代码块包含至少 4 行代码时才会启用行号。
+  - `true`：全局启用代码行号。
   - `false`：全局禁用代码行号。
-  - `'disable'`: 完全禁用行号，`:line-numbers` 标记不会生效。
+  - `'disable'`：完全禁用行号，`:line-numbers` 标记不会生效。
 
   你可以在代码块添加 `:line-numbers` / `:no-line-numbers` 标记来覆盖配置项中的设置，还可以在 `:line-numbers` 之后添加 `=` 来自定义起始行号，例如 `:line-numbers=2` 表示代码块中的行号从 `2` 开始。
 
@@ -172,10 +170,10 @@ export default defineUserConfig({
 
 - 详情：代码块折叠的默认行为。
 
-  - `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 行开始折叠。
 
@@ -465,7 +463,7 @@ body > div {
 
 - 详情：是否启用词高亮标记。
 
-  词高亮标记 必须单独写在一行。
+  词高亮标记必须单独写在一行。
 
 - 示例：
 
@@ -515,15 +513,15 @@ body > div {
 
 - 默认值：`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` 将渲染行首行尾的空白符。
 
 - 示例：
 
@@ -557,12 +555,12 @@ body > div {
   ```
 
   ```md :no-whitespace
-  
+  
 
-  A text
-  with line break
+  具有尾随空格  
+  的文字
 
-      code block
+      缩进文字
   ```
 
   :::
@@ -572,9 +570,9 @@ body > div {
 
 ### preloadLanguages
 
-- 类型： `string[]`
+- 类型：`string[]`
 
-- 默认值： `['markdown', 'jsdoc', 'yaml']`
+- 默认值：`['markdown', 'jsdoc', 'yaml']`
 
 - 详情：
 
@@ -582,22 +580,22 @@ body > div {
 
   默认情况下，语言会在解析 Markdown 文件时按需加载。
 
-  然而， Prism.js 在动态加载语言时可能会遇到 [一些潜在的问题](https://github.com/PrismJS/prism/issues/2716) 。为了避免这些问题，你可以使用该配置项来预加载一些语言。
+  然而，Prism.js 在动态加载语言时可能会遇到[一些潜在的问题](https://github.com/PrismJS/prism/issues/2716)。为了避免这些问题，你可以使用该配置项来预加载一些语言。
 
 ### preWrapper
 
-- 类型： `boolean`
+- 类型：`boolean`
 
-- 默认值： `true`
+- 默认值：`true`
 
 - 详情：
 
   是否在 `
` 标签外添加包裹容器。
 
-  `lineNumbers` 和 `collapsedLines` 依赖于这个额外的包裹层。这换句话说，如果你禁用了 `preWrapper` ，那么行号和折叠代码块也会被同时禁用。
+  `lineNumbers` 和 `collapsedLines` 依赖于这个额外的包裹层。换句话说，如果你禁用了 `preWrapper`，那么行号和折叠代码块也会被同时禁用。
 
   ::: tip
 
-  如果你想要在客户端来实现这些功能时，可以禁用该配置项。比如使用 [Prismjs Line Highlight](https://prismjs.com/plugins/line-highlight/) 或者 [Prismjs Line Numbers](https://prismjs.com/plugins/line-numbers/)。
+  如果你想要在客户端来实现这些功能，可以禁用该配置项。比如使用 [Prismjs Line Highlight](https://prismjs.com/plugins/line-highlight/) 或 [Prismjs Line Numbers](https://prismjs.com/plugins/line-numbers/)。
 
   :::
diff --git a/plugins/markdown/plugin-prismjs/src/node/loadLanguages.ts b/plugins/markdown/plugin-prismjs/src/node/loadLanguages.ts
index 8d3f3a71a7..5f89579399 100644
--- a/plugins/markdown/plugin-prismjs/src/node/loadLanguages.ts
+++ b/plugins/markdown/plugin-prismjs/src/node/loadLanguages.ts
@@ -4,6 +4,17 @@ import rawLoadLanguages from 'prismjs/components/index.js'
 // prevent warning messages
 rawLoadLanguages.silent = true
 
+/**
+ * Load prism languages
+ *
+ * 加载 prism 语言
+ *
+ * @param languages - Languages to load / 要加载的语言
+ * @example
+ * ```ts
+ * loadLanguages(['javascript', 'typescript', 'python'])
+ * ```
+ */
 export const loadLanguages = (languages: string[]): void => {
   const langsToLoad = languages.filter((item) => !(item in Prism.languages))
 
diff --git a/plugins/markdown/plugin-prismjs/src/node/markdown/highlightPlugin.ts b/plugins/markdown/plugin-prismjs/src/node/markdown/highlightPlugin.ts
index 81ad3a1b81..7283778660 100644
--- a/plugins/markdown/plugin-prismjs/src/node/markdown/highlightPlugin.ts
+++ b/plugins/markdown/plugin-prismjs/src/node/markdown/highlightPlugin.ts
@@ -18,6 +18,8 @@ export interface MarkdownItPrismjsHighlightOptions {
   /**
    * Enable highlight lines or not
    *
+   * 是否启用行高亮
+   *
    * @default true
    */
   highlightLines?: boolean
@@ -25,6 +27,8 @@ export interface MarkdownItPrismjsHighlightOptions {
   /**
    * Enable notation diff
    *
+   * 是否启用标记差异
+   *
    * @default false
    *
    * @see https://shiki.style/packages/transformers#transformernotationdiff
@@ -34,6 +38,8 @@ export interface MarkdownItPrismjsHighlightOptions {
   /**
    * Enable notation focus
    *
+   * 是否启用标记聚焦
+   *
    * @default false
    *
    * @see https://shiki.style/packages/transformers#transformernotationfocus
@@ -43,6 +49,8 @@ export interface MarkdownItPrismjsHighlightOptions {
   /**
    * Enable notation highlight
    *
+   * 是否启用标记高亮
+   *
    * @default false
    *
    * @see https://shiki.style/packages/transformers#transformernotationhighlight
@@ -52,6 +60,8 @@ export interface MarkdownItPrismjsHighlightOptions {
   /**
    * Enable notation error level
    *
+   * 是否启用标记错误级别
+   *
    * @default false
    *
    * @see https://shiki.style/packages/transformers#transformernotationerrorlevel
@@ -61,6 +71,8 @@ export interface MarkdownItPrismjsHighlightOptions {
   /**
    * Enable notation word highlight
    *
+   * 是否启用标记词汇高亮
+   *
    * @default false
    *
    * @see https://shiki.style/packages/transformers#transformernotationwordhighlight
@@ -75,9 +87,16 @@ export interface MarkdownItPrismjsHighlightOptions {
    * - '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
+   *
+   * 是否启用渲染空格
+   * - true: 启用空格，但默认不渲染任何空格
+   * - false: 完全禁用空格
+   * - 'all': 渲染所有空格
+   * - 'boundary': 渲染每行的前导和尾随空格
+   * - 'trailing': 渲染每行的尾随空格
    *
-   * position: 'all' | 'boundary' | 'trailing'
+   * 你可以使用 `:whitespace` 或 `:no-whitespace` 或 `:whitespace=all|boundary|trailing` 来设置单个代码块
    *
    * @default false
    *
@@ -86,6 +105,22 @@ export interface MarkdownItPrismjsHighlightOptions {
   whitespace?: WhitespacePosition | boolean
 }
 
+/**
+ * Markdown-it plugin for prismjs highlighting
+ *
+ * 用于 prismjs 高亮的 markdown-it 插件
+ *
+ * @param md - Markdown instance / Markdown 实例
+ * @param options - Plugin options / 插件选项
+ * @example
+ * ```ts
+ * import { highlightPlugin } from '@vuepress/plugin-prismjs'
+ * import MarkdownIt from 'markdown-it'
+ *
+ * const md = new MarkdownIt()
+ * md.use(highlightPlugin, { highlightLines: true })
+ * ```
+ */
 export const highlightPlugin = (
   md: Markdown,
   {
diff --git a/plugins/markdown/plugin-prismjs/src/node/markdown/preWrapperPlugin.ts b/plugins/markdown/plugin-prismjs/src/node/markdown/preWrapperPlugin.ts
index 38c0d95143..7d3222235a 100644
--- a/plugins/markdown/plugin-prismjs/src/node/markdown/preWrapperPlugin.ts
+++ b/plugins/markdown/plugin-prismjs/src/node/markdown/preWrapperPlugin.ts
@@ -7,10 +7,30 @@ export interface MarkdownItPreWrapperOptions {
    * understand what's it for
    *
    * - Required for line numbers, title display and code block collapsing
+   *
+   * 是否用额外的 `
` 包装 `
` 标签。除非你了解它的作用，否则不要禁用它
+   *
+   * - 行号、标题显示和代码块折叠所必需
    */
   preWrapper?: boolean
 }
 
+/**
+ * Markdown-it plugin for pre wrapper
+ *
+ * 用于 pre 包装器的 markdown-it 插件
+ *
+ * @param md - Markdown instance / Markdown 实例
+ * @param options - Plugin options / 插件选项
+ * @example
+ * ```ts
+ * import { preWrapperPlugin } from '@vuepress/plugin-prismjs'
+ * import MarkdownIt from 'markdown-it'
+ *
+ * const md = new MarkdownIt()
+ * md.use(preWrapperPlugin, { preWrapper: true })
+ * ```
+ */
 export const preWrapperPlugin = (
   md: Markdown,
   { preWrapper = true }: MarkdownItPreWrapperOptions = {},
diff --git a/plugins/markdown/plugin-prismjs/src/node/options.ts b/plugins/markdown/plugin-prismjs/src/node/options.ts
index a5b75a5a40..b4a0b082ec 100644
--- a/plugins/markdown/plugin-prismjs/src/node/options.ts
+++ b/plugins/markdown/plugin-prismjs/src/node/options.ts
@@ -11,6 +11,8 @@ import type { PrismjsHighlightOptions } from './types.js'
 
 /**
  * Options of @vuepress/plugin-prismjs
+ *
+ * @vuepress/plugin-prismjs 的选项
  */
 export type PrismjsPluginOptions = MarkdownItCodeBlockTitleOptions &
   MarkdownItLineNumbersOptions &
diff --git a/plugins/markdown/plugin-prismjs/src/node/parser/createNotationRule.ts b/plugins/markdown/plugin-prismjs/src/node/parser/createNotationRule.ts
index a5cd7af599..1bbd8deed2 100644
--- a/plugins/markdown/plugin-prismjs/src/node/parser/createNotationRule.ts
+++ b/plugins/markdown/plugin-prismjs/src/node/parser/createNotationRule.ts
@@ -3,6 +3,22 @@ import type { CodeParser, OpenTag } from './getCodeParser.js'
 // prismjs comments
 const COMMENT_EMPTY_TAG = /\s*?<\/span>/
 
+/**
+ * Create notation rule for code parser
+ *
+ * 为代码解析器创建标记规则
+ *
+ * @param parser - Code parser instance / 代码解析器实例
+ * @param pattern - RegExp pattern to match / 用于匹配的正则表达式模式
+ * @param onMatch - Callback function when pattern matches / 模式匹配时的回调函数
+ * @example
+ * ```ts
+ * import { createNotationRule, getCodeParser } from '@vuepress/plugin-prismjs'
+ *
+ * const parser = getCodeParser('
// [!code highlight]
')
+ * createNotationRule(parser, /\/\/ \[!code highlight\]/, () => true)
+ * ```
+ */
 export const createNotationRule = (
   parser: CodeParser,
   pattern: RegExp,
diff --git a/plugins/markdown/plugin-prismjs/src/node/parser/getCodeParser.ts b/plugins/markdown/plugin-prismjs/src/node/parser/getCodeParser.ts
index 8ca03dce43..63889e08f0 100644
--- a/plugins/markdown/plugin-prismjs/src/node/parser/getCodeParser.ts
+++ b/plugins/markdown/plugin-prismjs/src/node/parser/getCodeParser.ts
@@ -94,6 +94,24 @@ const createOpenTag = (
   }
 }
 
+/**
+ * Parse highlighted code and create code parser
+ *
+ * 解析高亮代码并创建代码解析器
+ *
+ * @param html - Highlighted HTML content / 高亮 HTML 内容
+ * @returns Code parser instance / 代码解析器实例
+ * @example
+ * ```ts
+ * import { getCodeParser } from '@vuepress/plugin-prismjs'
+ *
+ * const html = '
console.log("hello")
'
+ * const parser = getCodeParser(html)
+ * parser.line((node, index) => {
+ *   if (index === 1) node.classList.push('highlighted')
+ * })
+ * ```
+ */
 export const getCodeParser = (html: string): CodeParser => {
   let content = html
   const preOpen = html.match(PRE_OPEN_TAG_RE)?.[1] ?? ''
diff --git a/plugins/markdown/plugin-prismjs/src/node/parser/highlightLines.ts b/plugins/markdown/plugin-prismjs/src/node/parser/highlightLines.ts
index 8f9e806b6c..ebbf81e5e3 100644
--- a/plugins/markdown/plugin-prismjs/src/node/parser/highlightLines.ts
+++ b/plugins/markdown/plugin-prismjs/src/node/parser/highlightLines.ts
@@ -4,6 +4,18 @@ export type HighlightLinesRange = [start: number, end: number]
 
 /**
  * Resolve highlight-lines ranges from token info
+ *
+ * 从代码标记信息中解析高亮行范围
+ *
+ * @param info - Token info string / 代码标记信息字符串
+ * @returns Highlight ranges or null / 高亮范围或 null
+ * @example
+ * ```ts
+ * import { getHighlightLinesRange } from '@vuepress/plugin-prismjs'
+ *
+ * const ranges = getHighlightLinesRange('js {1,3-5}')
+ * console.log(ranges) // [[1, 1], [3, 5]]
+ * ```
  */
 export const getHighlightLinesRange = (
   info: string,
@@ -30,6 +42,11 @@ export const getHighlightLinesRange = (
 
 /**
  * Check if a line number is in ranges
+ *
+ * 检查行号是否在范围内
+ *
+ * @param lineNumber - Line number to check / 要检查的行号
+ * @param ranges - Highlight ranges / 高亮范围
  */
 const isLineHighlighted = (
   lineNumber: number,
@@ -37,6 +54,21 @@ const isLineHighlighted = (
 ): boolean =>
   ranges.some(([start, end]) => lineNumber >= start && lineNumber <= end)
 
+/**
+ * Highlight code lines based on ranges
+ *
+ * 根据范围高亮代码行
+ *
+ * @param parser - Code parser instance / 代码解析器实例
+ * @param ranges - Highlight ranges / 高亮范围
+ * @example
+ * ```ts
+ * import { highlightCodeLines, getCodeParser } from '@vuepress/plugin-prismjs'
+ *
+ * const parser = getCodeParser('
line1\nline2\nline3
')
+ * highlightCodeLines(parser, [[1, 1], [3, 3]])
+ * ```
+ */
 export const highlightCodeLines = (
   parser: CodeParser,
   ranges: HighlightLinesRange[] | null,
diff --git a/plugins/markdown/plugin-prismjs/src/node/parser/highlightWord.ts b/plugins/markdown/plugin-prismjs/src/node/parser/highlightWord.ts
index 59c2ac0fd8..b1137ee30b 100644
--- a/plugins/markdown/plugin-prismjs/src/node/parser/highlightWord.ts
+++ b/plugins/markdown/plugin-prismjs/src/node/parser/highlightWord.ts
@@ -6,6 +6,14 @@ const META_WORD_REGEXP = /\/((?:\\.|[^/])+)\//g
 const WORD_BEFORE = ''
 const WORD_AFTER = ''
 
+/**
+ * Highlight specific word in a line
+ *
+ * 在行中高亮特定词汇
+ *
+ * @param node - Line node / 行节点
+ * @param pattern - Pattern to match / 匹配模式
+ */
 export const highlightWordInLine = (
   node: OpenTag,
   pattern: RegExp | string,
@@ -24,6 +32,13 @@ export const highlightWordInLine = (
     .join('')
 }
 
+/**
+ * Parse meta highlight words from meta string
+ *
+ * 从元字符串中解析高亮词汇
+ *
+ * @param meta - Meta string / 元字符串
+ */
 export const parseMetaHighlightWords = (meta: string): string[] => {
   if (!meta) return []
 
@@ -37,7 +52,12 @@ export const parseMetaHighlightWords = (meta: string): string[] => {
 }
 
 /**
- * ```js /Hello|Hi/
+ * `` ```js /Hello|Hi/ ``
+ *
+ * 元词汇高亮
+ *
+ * @param parser - Code parser instance / 代码解析器实例
+ * @param meta - Meta string / 元字符串
  */
 export const metaWordHighlight = (parser: CodeParser, meta: string): void => {
   const words = parseMetaHighlightWords(meta)
diff --git a/plugins/markdown/plugin-prismjs/src/node/parser/notation.ts b/plugins/markdown/plugin-prismjs/src/node/parser/notation.ts
index cde87376d7..c2be4bf616 100644
--- a/plugins/markdown/plugin-prismjs/src/node/parser/notation.ts
+++ b/plugins/markdown/plugin-prismjs/src/node/parser/notation.ts
@@ -58,7 +58,11 @@ const createNotationCommentMarkerRule = (
 /**
  * line highlight
  *
+ * 行高亮
+ *
  * `// [!code highlight]`, or `// [!code hl]`
+ *
+ * @param parser - Code parser instance / 代码解析器实例
  */
 export const notationHighlight = (parser: CodeParser): void => {
   createNotationCommentMarkerRule(parser, {
@@ -73,7 +77,11 @@ export const notationHighlight = (parser: CodeParser): void => {
 /**
  * line focus
  *
+ * 行聚焦
+ *
  * `// [!code focus]`
+ *
+ * @param parser - Code parser instance / 代码解析器实例
  */
 export const notationFocus = (parser: CodeParser): void => {
   createNotationCommentMarkerRule(parser, {
@@ -87,7 +95,11 @@ export const notationFocus = (parser: CodeParser): void => {
 /**
  * line diff
  *
+ * 行差异
+ *
  * `// [!code ++]` and `// [!code --]`
+ *
+ * @param parser - Code parser instance / 代码解析器实例
  */
 export const notationDiff = (parser: CodeParser): void => {
   createNotationCommentMarkerRule(parser, {
@@ -102,7 +114,11 @@ export const notationDiff = (parser: CodeParser): void => {
 /**
  * line error level
  *
+ * 行错误级别
+ *
  * `// [!code warning]` and `// [!code error]`
+ *
+ * @param parser - Code parser instance / 代码解析器实例
  */
 export const notationErrorLevel = (parser: CodeParser): void => {
   createNotationCommentMarkerRule(parser, {
@@ -117,8 +133,11 @@ export const notationErrorLevel = (parser: CodeParser): void => {
 /**
  * highlight word
  *
+ * 词汇高亮
+ *
  * `// [!code word:xxx]`: `xxx` can be any word.
- * @param parser
+ *
+ * @param parser - Code parser instance / 代码解析器实例
  */
 export const notationWordHighlight = (parser: CodeParser): void => {
   createNotationRule(
diff --git a/plugins/markdown/plugin-prismjs/src/node/parser/whitespace.ts b/plugins/markdown/plugin-prismjs/src/node/parser/whitespace.ts
index 6e5bb399ca..e0b148786c 100644
--- a/plugins/markdown/plugin-prismjs/src/node/parser/whitespace.ts
+++ b/plugins/markdown/plugin-prismjs/src/node/parser/whitespace.ts
@@ -18,6 +18,21 @@ const renderSpace = (text: string): string =>
     (space) => `${space}`,
   )
 
+/**
+ * Render whitespace in a line based on position
+ *
+ * 根据位置在行中渲染空白字符
+ *
+ * @param node - Line node / 行节点
+ * @param position - Whitespace position / 空白字符位置
+ *
+ * @example
+ * ```ts
+ * import { renderWhitespaceInLine } from '@vuepress/plugin-prismjs'
+ *
+ * renderWhitespaceInLine(lineNode, 'all')
+ * ```
+ */
 export const renderWhitespaceInLine = (
   node: OpenTag,
   position: WhitespacePosition,
@@ -85,9 +100,24 @@ export const renderWhitespaceInLine = (
 }
 
 /**
- * type: 'all' | 'boundary' | 'trailing'
+ * Handle whitespace rendering based on meta string
+ *
+ * 基于元字符串处理空白字符渲染
+ *
+ * @param parser - Code parser instance / 代码解析器实例
+ * @param meta - Meta string / 元字符串
+ * @param globalOption - Global whitespace option / 全局空白字符选项
+ *
+ * @example
+ * ```js :whitespace[=all|boundary|trailing]
+ * ```
+ *
+ * @example
+ * ```ts
+ * import { metaWhitespace } from '@vuepress/plugin-prismjs'
  *
- * ```js :whitespace[=type]
+ * metaWhitespace(parser, ':whitespace[=all]', true)
+ * ```
  */
 export const metaWhitespace = (
   parser: CodeParser,
diff --git a/plugins/markdown/plugin-prismjs/src/node/prismjsPlugin.ts b/plugins/markdown/plugin-prismjs/src/node/prismjsPlugin.ts
index c2034cf6d0..fcd261cb9c 100644
--- a/plugins/markdown/plugin-prismjs/src/node/prismjsPlugin.ts
+++ b/plugins/markdown/plugin-prismjs/src/node/prismjsPlugin.ts
@@ -10,6 +10,27 @@ import type { PrismjsPluginOptions } from './options.js'
 import { prepareClientConfigFile } from './prepareClientConfigFile.js'
 import { resolveHighlighter } from './resolveHighlighter.js'
 
+/**
+ * VuePress plugin - prismjs
+ *
+ * VuePress 插件 - prismjs
+ *
+ * @param options - Plugin options / 插件选项
+ * @returns VuePress plugin / VuePress 插件
+ * @example
+ * ```ts
+ * import { prismjsPlugin } from '@vuepress/plugin-prismjs'
+ *
+ * export default {
+ *   plugins: [
+ *     prismjsPlugin({
+ *       theme: 'nord',
+ *       lineNumbers: true
+ *     })
+ *   ]
+ * }
+ * ```
+ */
 export const prismjsPlugin = (options: PrismjsPluginOptions = {}): Plugin => {
   const opt: PrismjsPluginOptions = {
     preloadLanguages: ['markdown', 'jsdoc', 'yaml'],
diff --git a/plugins/markdown/plugin-prismjs/src/node/resolveHighlighter.ts b/plugins/markdown/plugin-prismjs/src/node/resolveHighlighter.ts
index b4ce5f79d4..a77330b410 100644
--- a/plugins/markdown/plugin-prismjs/src/node/resolveHighlighter.ts
+++ b/plugins/markdown/plugin-prismjs/src/node/resolveHighlighter.ts
@@ -21,6 +21,18 @@ export type Highlighter = (code: string) => string
 
 /**
  * Resolve syntax highlighter for corresponding language
+ *
+ * 解析对应语言的语法高亮器
+ *
+ * @param language - Language name / 语言名称
+ * @returns Highlighter function or null / 高亮器函数或 null
+ * @example
+ * ```ts
+ * const highlighter = resolveHighlighter('javascript')
+ * if (highlighter) {
+ *   const result = highlighter('console.log("hello")')
+ * }
+ * ```
  */
 export const resolveHighlighter = (language: string): Highlighter | null => {
   const languageInfo = resolveLanguage(language)
diff --git a/plugins/markdown/plugin-prismjs/src/node/types.ts b/plugins/markdown/plugin-prismjs/src/node/types.ts
index 6e7fdf8fbc..ff8a0bb47e 100644
--- a/plugins/markdown/plugin-prismjs/src/node/types.ts
+++ b/plugins/markdown/plugin-prismjs/src/node/types.ts
@@ -43,12 +43,16 @@ export interface PrismjsHighlightOptions {
   /**
    * Single theme
    *
+   * 单一主题
+   *
    * @default 'nord'
    */
   theme?: PrismjsTheme
 
   /**
    * Dual themes
+   *
+   * 双主题
    */
   themes?: {
     light: PrismjsTheme
@@ -60,6 +64,10 @@ export interface PrismjsHighlightOptions {
    *
    * Workaround for prismjs language reloading issue
    *
+   * 要预加载的语言
+   *
+   * 解决 prismjs 语言重新加载问题的方法
+   *
    * @default ['markdown', 'jsdoc', 'yaml']
    * @see https://github.com/PrismJS/prism/issues/2716
    */
diff --git a/plugins/markdown/plugin-prismjs/src/node/utils/escapeRegExp.ts b/plugins/markdown/plugin-prismjs/src/node/utils/escapeRegExp.ts
index 270b833074..3d005df437 100644
--- a/plugins/markdown/plugin-prismjs/src/node/utils/escapeRegExp.ts
+++ b/plugins/markdown/plugin-prismjs/src/node/utils/escapeRegExp.ts
@@ -1,2 +1,17 @@
+/**
+ * Escape special characters in a string for use in a regular expression
+ *
+ * 转义字符串中的特殊字符以在正则表达式中使用
+ *
+ * @param str - String to escape / 要转义的字符串
+ * @returns Escaped string / 转义后的字符串
+ * @example
+ * ```ts
+ * import { escapeRegExp } from '@vuepress/plugin-prismjs'
+ *
+ * const escaped = escapeRegExp('Hello (world)')
+ * console.log(escaped) // 'Hello \\(world\\)'
+ * ```
+ */
 export const escapeRegExp = (str: string): string =>
   str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
diff --git a/plugins/markdown/plugin-prismjs/src/node/utils/resolveLanguage.ts b/plugins/markdown/plugin-prismjs/src/node/utils/resolveLanguage.ts
index d982172238..ee2a43cb73 100644
--- a/plugins/markdown/plugin-prismjs/src/node/utils/resolveLanguage.ts
+++ b/plugins/markdown/plugin-prismjs/src/node/utils/resolveLanguage.ts
@@ -28,6 +28,18 @@ const getLanguagesMap = (): LanguagesMap =>
 
 /**
  * Resolve language for highlight from token info
+ *
+ * 从代码标记信息中解析高亮语言
+ *
+ * @param info - Token info string / 代码标记信息字符串
+ * @returns Language information / 语言信息
+ * @example
+ * ```ts
+ * import { resolveLanguage } from '@vuepress/plugin-prismjs'
+ *
+ * const lang = resolveLanguage('js {1,3-5}')
+ * console.log(lang.name) // 'javascript'
+ * ```
  */
 export const resolveLanguage = (info: string): HighlightLanguage => {
   // get user-defined language alias

From f8932507655b9e31e87d344b2e1a010507675368 Mon Sep 17 00:00:00 2001
From: Mister-Hope 
Date: Thu, 5 Jun 2025 14:30:50 +0800
Subject: [PATCH 2/3] chore: tweaks

---
 .../markdown/plugin-prismjs/src/node/parser/whitespace.ts | 8 +++-----
 1 file changed, 3 insertions(+), 5 deletions(-)

diff --git a/plugins/markdown/plugin-prismjs/src/node/parser/whitespace.ts b/plugins/markdown/plugin-prismjs/src/node/parser/whitespace.ts
index e0b148786c..38d8e0cee1 100644
--- a/plugins/markdown/plugin-prismjs/src/node/parser/whitespace.ts
+++ b/plugins/markdown/plugin-prismjs/src/node/parser/whitespace.ts
@@ -104,19 +104,17 @@ export const renderWhitespaceInLine = (
  *
  * 基于元字符串处理空白字符渲染
  *
+ * `` ```js :whitespace[=all|boundary|trailing] ``
+ *
  * @param parser - Code parser instance / 代码解析器实例
  * @param meta - Meta string / 元字符串
  * @param globalOption - Global whitespace option / 全局空白字符选项
  *
  * @example
- * ```js :whitespace[=all|boundary|trailing]
- * ```
- *
- * @example
  * ```ts
  * import { metaWhitespace } from '@vuepress/plugin-prismjs'
  *
- * metaWhitespace(parser, ':whitespace[=all]', true)
+ * metaWhitespace(parser, ':whitespace=all', true)
  * ```
  */
 export const metaWhitespace = (

From 1c081759c7cf8ee554027bae0d51e781210d8e2d Mon Sep 17 00:00:00 2001
From: Mister-Hope 
Date: Thu, 5 Jun 2025 14:31:13 +0800
Subject: [PATCH 3/3] chore: tweaks

---
 .../markdown/plugin-prismjs/src/node/parser/highlightWord.ts    | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/plugins/markdown/plugin-prismjs/src/node/parser/highlightWord.ts b/plugins/markdown/plugin-prismjs/src/node/parser/highlightWord.ts
index b1137ee30b..5dbc8516de 100644
--- a/plugins/markdown/plugin-prismjs/src/node/parser/highlightWord.ts
+++ b/plugins/markdown/plugin-prismjs/src/node/parser/highlightWord.ts
@@ -54,6 +54,8 @@ export const parseMetaHighlightWords = (meta: string): string[] => {
 /**
  * `` ```js /Hello|Hi/ ``
  *
+ * Meta word highlight
+ *
  * 元词汇高亮
  *
  * @param parser - Code parser instance / 代码解析器实例