Skip to content

refactor(plugin-prismjs): add jsdoc and improve docs #528

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Jun 5, 2025
Merged

refactor(plugin-prismjs): add jsdoc and improve docs #528

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
64ecf2a
refactor(plugin-prismjs): add jsdoc and improve docs
Mister-Hope Jun 5, 2025
f893250
chore: tweaks
Mister-Hope Jun 5, 2025
1c08175
chore: tweaks
Mister-Hope Jun 5, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions .github/copilot-instructions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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<void>`, should be bilingual, separate with `/` for English and Chinese

````typescript
/**
Expand Down
64 changes: 31 additions & 33 deletions docs/plugins/markdown/prismjs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,12 +6,10 @@ icon: pyramid

<NpmBadge package="@vuepress/plugin-prismjs" />

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
Expand All @@ -38,17 +36,17 @@ 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

- Type: `{ light: PrismjsTheme; dark: PrismjsTheme }`

- 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 `<html>` tag when dark mode is enabled.
Note: To use this feature, your theme must set the `data-theme="dark"` attribute on the `<html>` tag when dark mode is enabled.

::: tip Available Prism.js Light themes

Expand Down Expand Up @@ -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

Expand All @@ -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'
```
Expand All @@ -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}`
Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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:

Expand Down Expand Up @@ -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:

Expand Down Expand Up @@ -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:

Expand Down Expand Up @@ -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:

Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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:

Expand Down Expand Up @@ -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
Expand All @@ -591,12 +589,12 @@ In the new version, some functionalities similar to [shiki](https://shiki.style/

- Details:

Adds extra wrapper outside `<pre>` tag or not.
Whether to add an extra wrapper outside the `<pre>` 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/).

:::
60 changes: 29 additions & 31 deletions docs/zh/plugins/markdown/prismjs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,6 @@ icon: pyramid

该插件已经集成到默认主题中。

需要注意的是，该插件仅会给代码块添加 HTML 标记，而不会添加样式。当你在一个自定义主题中使用它时，可能需要自己选择并引入 Prism.js 样式主题。

## 使用方法

```bash
Expand All @@ -38,17 +36,17 @@ export default {

- 默认值：`'nord'`

- 详情：Prismjs 的主题。该主题会应用到代码块上。
- 详情：Prismjs 的主题，会应用到代码块上。

### themes

- 类型：`{ light: PrismjsTheme; dark: PrismjsTheme }`

- 详情：

使用暗黑和明亮模式双主题。
使用亮暗双主题。

注意：想使用这个功能，你的主题必须在夜间模式下在 `<html>` 标签上 `data-theme="dark"` 属性。
注意：想使用此功能，你的主题必须在夜间模式下在 `<html>` 标签上设置 `data-theme="dark"` 属性。

::: tip 可用的 Prism.js 浅色主题

Expand Down Expand Up @@ -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` 开始。

Expand Down Expand Up @@ -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 行开始折叠。

Expand Down Expand Up @@ -465,7 +463,7 @@ body > div {

- 详情：是否启用词高亮标记。

词高亮标记 必须单独写在一行。
词高亮标记必须单独写在一行。

- 示例：

Expand Down Expand Up @@ -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` 将渲染行首行尾的空白符。

- 示例：

Expand Down Expand Up @@ -557,12 +555,12 @@ body > div {
```

```md :no-whitespace
<!-- 禁用空白符 -->
<!-- 禁用空白符渲染 -->

A text
with line break
具有尾随空格
的文字

code block
缩进文字
```

:::
Expand All @@ -572,32 +570,32 @@ body > div {

### preloadLanguages

- 类型： `string[]`
- 类型：`string[]`

- 默认值： `['markdown', 'jsdoc', 'yaml']`
- 默认值：`['markdown', 'jsdoc', 'yaml']`

- 详情：

需要预加载的语言。

默认情况下，语言会在解析 Markdown 文件时按需加载。

然而， Prism.js 在动态加载语言时可能会遇到 [一些潜在的问题](https://github.com/PrismJS/prism/issues/2716) 。为了避免这些问题，你可以使用该配置项来预加载一些语言。
然而，Prism.js 在动态加载语言时可能会遇到[一些潜在的问题](https://github.com/PrismJS/prism/issues/2716)。为了避免这些问题，你可以使用该配置项来预加载一些语言。

### preWrapper

- 类型： `boolean`
- 类型：`boolean`

- 默认值： `true`
- 默认值：`true`

- 详情：

是否在 `<pre>` 标签外添加包裹容器。

`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/)。

:::
11 changes: 11 additions & 0 deletions plugins/markdown/plugin-prismjs/src/node/loadLanguages.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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))

Expand Down
Loading
Loading