feat: improve types

plugins/plugin-prismjs/src/node/markdown/highlightPlugin.ts

@@ -8,7 +8,7 @@ import {
   notationFocus,
   notationHighlight,
 } from '../parser/index.js'
-import type { PreWrapperOptions } from '../types.js'
+import type { HighlightOptions } from '../types.js'
 import { resolveLanguage } from '../utils/index.js'
 
 export const highlightPlugin = (
@@ -19,7 +19,7 @@ export const highlightPlugin = (
     notationErrorLevel: enabledErrorLevel,
     notationFocus: enabledFocus,
     notationHighlight: enabledHighlight,
-  }: PreWrapperOptions = {},
+  }: HighlightOptions = {},
 ): void => {
   const rawFence = md.renderer.rules.fence!
 

plugins/plugin-prismjs/src/node/markdown/lineNumbersPlugin.ts

@@ -1,10 +1,10 @@
 import type { Markdown } from 'vuepress/markdown'
-import type { PreWrapperOptions } from '../types.js'
+import type { LineNumbersOptions } from '../types.js'
 import { resolveLineNumbers } from '../utils/index.js'
 
 export const lineNumbersPlugin = (
   md: Markdown,
-  lineNumbers: PreWrapperOptions['lineNumbers'] = true,
+  { lineNumbers = true }: LineNumbersOptions = {},
 ): void => {
   const rawFence = md.renderer.rules.fence!
 

plugins/plugin-prismjs/src/node/prismjsPlugin.ts

@@ -6,12 +6,19 @@ import {
   preWrapperPlugin,
 } from './markdown/index.js'
 import { resolveHighlighter } from './resolveHighlighter.js'
-import type { PreWrapperOptions } from './types.js'
+import type {
+  HighlightOptions,
+  LineNumbersOptions,
+  PreWrapperOptions,
+} from './types.js'
 
 /**
  * Options of @vuepress/plugin-prismjs
  */
-export interface PrismjsPluginOptions extends PreWrapperOptions {
+export interface PrismjsPluginOptions
+  extends PreWrapperOptions,
+    LineNumbersOptions,
+    HighlightOptions {
   /**
    * Languages to preload
    *
@@ -25,6 +32,8 @@ export interface PrismjsPluginOptions extends PreWrapperOptions {
 
 export const prismjsPlugin = ({
   preloadLanguages = ['markdown', 'jsdoc', 'yaml'],
+  preWrapper = true,
+  lineNumbers = true,
   ...options
 }: PrismjsPluginOptions = {}): Plugin => ({
   name: '@vuepress/plugin-prismjs',
@@ -39,10 +48,10 @@ export const prismjsPlugin = ({
       return highlighter?.(code) || ''
     }
 
-    md.use(highlightPlugin, options)
-    md.use(preWrapperPlugin, options)
-    if (options.preWrapper ?? true) {
-      md.use(lineNumbersPlugin, options.lineNumbers)
+    md.use<HighlightOptions>(highlightPlugin, options)
+    md.use<PreWrapperOptions>(preWrapperPlugin, { preWrapper })
+    if (preWrapper) {
+      md.use<LineNumbersOptions>(lineNumbersPlugin, { lineNumbers })
     }
   },
 })

plugins/plugin-prismjs/src/node/types.ts

@@ -7,7 +7,9 @@ export interface PreWrapperOptions {
    * - Required for title display of default theme
    */
   preWrapper?: boolean
+}
 
+export interface LineNumbersOptions {
   /**
    * Enable line numbers or not
    *
@@ -17,7 +19,9 @@ export interface PreWrapperOptions {
    * @default true
    */
   lineNumbers?: boolean | number
+}
 
+export interface HighlightOptions {
   /**
    * Enable highlight lines or not
    *

plugins/plugin-prismjs/tests/prismjs-preWrapper.spec.ts

@@ -1,6 +1,11 @@
 import MarkdownIt from 'markdown-it'
 import { describe, expect, it, vi } from 'vitest'
-import type { PrismjsPluginOptions } from '../src/node/index.js'
+import type {
+  HighlightOptions,
+  LineNumbersOptions,
+  PreWrapperOptions,
+  PrismjsPluginOptions,
+} from '../src/node/index.js'
 import {
   highlightPlugin,
   lineNumbersPlugin,
@@ -10,17 +15,21 @@ import { resolveHighlighter } from '../src/node/resolveHighlighter.js'
 
 const codeFence = '```'
 
-const createMarkdown = (options: PrismjsPluginOptions = {}): MarkdownIt => {
+const createMarkdown = ({
+  preWrapper = true,
+  lineNumbers = true,
+  ...options
+}: PrismjsPluginOptions = {}): MarkdownIt => {
   const md = MarkdownIt()
 
   md.options.highlight = (code, lang) => {
     const highlighter = resolveHighlighter(lang)
     return highlighter?.(code) || ''
   }
-  md.use(highlightPlugin, options)
-  md.use(preWrapperPlugin, options)
-  if (options.preWrapper ?? true) {
-    md.use(lineNumbersPlugin, options.lineNumbers)
+  md.use<HighlightOptions>(highlightPlugin, options)
+  md.use<PreWrapperOptions>(preWrapperPlugin, { preWrapper })
+  if (preWrapper) {
+    md.use<LineNumbersOptions>(lineNumbersPlugin, { lineNumbers })
   }
   return md
 }

plugins/plugin-shiki/src/node/index.ts

@@ -1,5 +1,6 @@
 import { shikiPlugin } from './shikiPlugin.js'
 
 export * from './shikiPlugin.js'
+export * from './types.js'
 /** @deprecated Use named export instead */
 export default shikiPlugin

plugins/plugin-shiki/src/node/markdown/lineNumberPlugin.ts

@@ -2,13 +2,14 @@
 // It depends on preWrapper plugin.
 
 import type { Markdown } from 'vuepress/markdown'
+import type { LineNumberOptions } from '../types.js'
 
 const LINE_NUMBERS_REGEXP = /:line-numbers\b/
 const NO_LINE_NUMBERS_REGEXP = /:no-line-numbers\b/
 
 export const lineNumberPlugin = (
   md: Markdown,
-  enable: boolean | number = true,
+  { lineNumbers = true }: LineNumberOptions = {},
 ): void => {
   const rawFence = md.renderer.rules.fence!
 
@@ -20,7 +21,10 @@ export const lineNumberPlugin = (
     const enableLineNumbers = LINE_NUMBERS_REGEXP.test(info)
     const disableLineNumbers = NO_LINE_NUMBERS_REGEXP.test(info)
 
-    if ((!enable && !enableLineNumbers) || (enable && disableLineNumbers)) {
+    if (
+      (!lineNumbers && !enableLineNumbers) ||
+      (lineNumbers && disableLineNumbers)
+    ) {
       return rawCode
     }
 
@@ -32,8 +36,8 @@ export const lineNumberPlugin = (
     const lines = code.split('\n')
 
     if (
-      typeof enable === 'number' &&
-      lines.length < enable &&
+      typeof lineNumbers === 'number' &&
+      lines.length < lineNumbers &&
       !enableLineNumbers
     ) {
       return rawCode

plugins/plugin-shiki/src/node/markdown/preWrapperPlugin.ts

@@ -1,12 +1,12 @@
 // markdown-it plugin for generating line numbers.
 // v-pre block logic is in `../highlight.ts`
 import type { Markdown } from 'vuepress/markdown'
-import type { ShikiPluginOptions } from '../types.js'
+import type { PreWrapperOptions } from '../types.js'
 import { resolveAttr, resolveLanguage } from '../utils.js'
 
 export const preWrapperPlugin = (
   md: Markdown,
-  { preWrapper = true }: ShikiPluginOptions = {},
+  { preWrapper = true }: PreWrapperOptions = {},
 ): void => {
   const rawFence = md.renderer.rules.fence!
 

plugins/plugin-shiki/src/node/resolveHighlight.ts

@@ -7,7 +7,7 @@ import {
 } from 'shiki'
 import { colors, logger } from 'vuepress/utils'
 import { getTransformers } from './transformers/getTransformers.js'
-import type { ShikiPluginOptions } from './types.js'
+import type { ShikiHighlightOptions } from './types.js'
 import { attrsToLines, nanoid, resolveLanguage } from './utils.js'
 
 const DEFAULT_LANGS = Object.keys(bundledLanguages)
@@ -21,7 +21,7 @@ export const resolveHighlight = async ({
   defaultHighlightLang = '',
   transformers: userTransformers = [],
   ...options
-}: ShikiPluginOptions = {}): Promise<
+}: ShikiHighlightOptions = {}): Promise<
   (str: string, lang: string, attrs: string) => string
 > => {
   const highlighter = await getHighlighter({
@@ -74,7 +74,13 @@ export const resolveHighlight = async ({
 
     const highlighted = highlighter.codeToHtml(str, {
       lang,
-      meta: { __raw: attrs },
+      meta: {
+        /**
+         * Custom `transformers` passed by users may require `attrs`.
+         * e.g. [transformerNotationWordHighlight](https://shiki.style/packages/transformers#transformernotationwordhighlight)
+         */
+        __raw: attrs,
+      },
       transformers: [
         ...transformers,
         ...(options.highlightLines ?? true

plugins/plugin-shiki/src/node/shikiPlugin.ts

@@ -6,9 +6,24 @@ import {
   preWrapperPlugin,
 } from './markdown/index.js'
 import { resolveHighlight } from './resolveHighlight.js'
-import type { ShikiPluginOptions } from './types.js'
+import type {
+  LineNumberOptions,
+  PreWrapperOptions,
+  ShikiHighlightOptions,
+} from './types.js'
 
-export const shikiPlugin = (options: ShikiPluginOptions = {}): Plugin => ({
+/**
+ * Options of @vuepress/plugin-shiki
+ */
+export type ShikiPluginOptions = ShikiHighlightOptions &
+  PreWrapperOptions &
+  LineNumberOptions
+
+export const shikiPlugin = ({
+  preWrapper = true,
+  lineNumbers = true,
+  ...options
+}: ShikiPluginOptions = {}): Plugin => ({
   name: '@vuepress/plugin-shiki',
 
   extendsMarkdown: async (md, app) => {
@@ -20,9 +35,9 @@ export const shikiPlugin = (options: ShikiPluginOptions = {}): Plugin => ({
     })
 
     md.use(highlightLinesPlugin)
-    md.use(preWrapperPlugin, options)
-    if (options.preWrapper ?? true) {
-      md.use(lineNumberPlugin, options.lineNumbers)
+    md.use<PreWrapperOptions>(preWrapperPlugin, { preWrapper })
+    if (preWrapper) {
+      md.use<LineNumberOptions>(lineNumberPlugin, { lineNumbers })
     }
   },
 })

plugins/plugin-shiki/src/node/transformers/getTransformers.ts

@@ -5,15 +5,15 @@ import {
   transformerNotationHighlight,
 } from '@shikijs/transformers'
 import type { ShikiTransformer } from 'shiki'
-import type { ShikiPluginOptions } from '../types.js'
+import type { ShikiHighlightOptions } from '../types.js'
 import {
   addClassTransformer,
   emptyLineTransformer,
   removeEscapeTransformer,
 } from './vuepressTransformers.js'
 
 export const getTransformers = (
-  options: ShikiPluginOptions,
+  options: ShikiHighlightOptions,
 ): ShikiTransformer[] => {
   const transformers: ShikiTransformer[] = []
 

plugins/plugin-shiki/src/node/transformers/vuepressTransformers.ts

@@ -9,6 +9,13 @@ export const addClassTransformer: ShikiTransformer = {
   },
 }
 
+/**
+ * This `transformer` is primarily for the usage instructions of themes.
+ * When developers need to provide an example like `// [!code xxx]`,
+ * they can use `// [\!code xxx]` to avoid being processed by `shiki`.
+ * After `shiki` completes the processing,
+ * replace `[\!code` back with `[!code` to display the correct text.
+ */
 export const removeEscapeTransformer: ShikiTransformer = {
   name: 'vuepress:remove-escape',
   postprocess(code) {

plugins/plugin-shiki/src/node/types.ts

@@ -20,10 +20,7 @@ export type ShikiTheme =
   | ThemeRegistrationRaw
   | StringLiteralUnion<BundledTheme>
 
-/**
- * Options of @vuepress/plugin-shiki
- */
-export interface ShikiPluginOptions {
+export interface ShikiHighlightOptions {
   /**
    * Languages to be loaded.
    *
@@ -69,28 +66,13 @@ export interface ShikiPluginOptions {
    */
   defaultColor?: false | StringLiteralUnion<'light' | 'dark'>
 
-  /**
-   * Show line numbers in code blocks
-   * @default true
-   */
-  lineNumbers?: boolean | number
-
   /**
    * Enable highlight lines or not
    *
    * @default true
    */
   highlightLines?: boolean
 
-  /**
-   * Wrap the `<pre>` tag with an extra `<div>` or not. Do not disable it unless you
-   * understand what's it for
-   *
-   * - Required for `lineNumbers`
-   * - Required for title display of default theme
-   */
-  preWrapper?: boolean
-
   /**
    * Enable notation diff transformer
    *
@@ -127,3 +109,22 @@ export interface ShikiPluginOptions {
    */
   notationErrorLevel?: boolean
 }
+
+export interface LineNumberOptions {
+  /**
+   * Show line numbers in code blocks
+   * @default true
+   */
+  lineNumbers?: boolean | number
+}
+
+export interface PreWrapperOptions {
+  /**
+   * Wrap the `<pre>` tag with an extra `<div>` or not. Do not disable it unless you
+   * understand what's it for
+   *
+   * - Required for `lineNumbers`
+   * - Required for title display of default theme
+   */
+  preWrapper?: boolean
+}