Skip to content

refactor(plugin-shiki): add jsdoc and improve docs #529

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 1 commit into from
Jun 5, 2025
Merged

refactor(plugin-shiki): add jsdoc and improve docs #529

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
135 changes: 52 additions & 83 deletions docs/plugins/markdown/shiki.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,11 +6,11 @@ icon: highlighter

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

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.

:::

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

:::

Expand All @@ -55,32 +52,26 @@ 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)

### 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)

### 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
<span style="--shiki-light:lightColor;--shiki-dark:darkColor;">code</span>
Expand All @@ -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'
```
Expand All @@ -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}`
Expand All @@ -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.
Expand Down Expand Up @@ -288,7 +271,7 @@ body > div {

- Details: Whether to enable code block title rendering. Add `title="Title"` after the code block <code>\`\`\`</code> to set the title.

Pass `CodeBlockTitleRender` to customize the title rendering.
Pass a `CodeBlockTitleRender` function to customize title rendering.

- Example:

Expand All @@ -306,7 +289,7 @@ body > div {

- Default: `false`

- Details: Whether enable notation diff.
- Details: Whether to enable notation diff.

- Example:

Expand Down Expand Up @@ -342,7 +325,7 @@ body > div {

- Default: `false`

- Details: Whether enable notation focus.
- Details: Whether to enable notation focus.

- Example:

Expand Down Expand Up @@ -378,7 +361,7 @@ body > div {

- Default: `false`

- Details: Whether enable notation highlight.
- Details: Whether to enable notation highlight.

- Example:

Expand Down Expand Up @@ -414,7 +397,7 @@ body > div {

- Default: `false`

- Details: Whether enable notation error level.
- Details: Whether to enable notation error level.

- Example:

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

Expand Down Expand Up @@ -481,7 +464,7 @@ body > div {
</template>
</VPPreview>

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

Expand All @@ -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:

Expand All @@ -526,7 +509,7 @@ body > div {
```

```md :whitespace=boundary
<!-- render leading and trailing whitespace of the line -->
<!-- render leading and trailing whitespace on each line -->

A text
with trailing spaces
Expand All @@ -535,7 +518,7 @@ body > div {
```

```md :whitespace=trailing
<!-- render trailing whitespace of the line -->
<!-- render trailing whitespace on each line -->

A text
with trailing spaces
Expand All @@ -544,7 +527,7 @@ body > div {
```

```md :no-whitespace
<!-- disable render whitespace -->
<!-- disable whitespace rendering -->

A text
with trailing spaces
Expand All @@ -554,7 +537,7 @@ body > div {

:::

- Also see：
- Also see:
- [Shiki > Render Whitespace](https://shiki.style/packages/transformers#transformerrenderwhitespace)

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

:::

Expand All @@ -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.

:::

Expand All @@ -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 `<pre>` tag.

- Details:

Adds extra wrapper outside `<pre>` 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<void>`

- 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)
Loading
Loading