vitepress-tuck 0.2.0 → 0.4.0

package/README.md

@@ -13,13 +13,13 @@ Enhance vitepress configuration and provide plugin development capabilities.
 Install
 
 ```bash
-npm
+# npm
 npm install vitepress vitepress-tuck
 
-pnpm
+# pnpm
 pnpm add vitepress vitepress-tuck
 
-yarn
+# yarn
 yarn add vitepress vitepress-tuck
 ```
 

package/dist/index.d.ts

@@ -1,23 +1,58 @@
 import { DefaultTheme, UserConfig } from "vitepress";
 
 //#region src/types.d.ts
+/**
+ * Represents a VitePress plugin in the vitepress-tuck ecosystem.
+ *
+ * A plugin extends a subset of VitePress's `UserConfig` fields (markdown, vite,
+ * vue, and lifecycle hooks) and adds a `name` plus an optional `client`
+ * descriptor for automatic client-side injection via the
+ * `virtual:enhance-app` virtual module.
+ *
+ * 表示 vitepress-tuck 生态中的 VitePress 插件。
+ *
+ * 插件扩展了 VitePress `UserConfig` 的部分字段（markdown、vite、vue 及生命周期
+ * 钩子），并新增 `name` 与可选的 `client` 描述符，用于通过
+ * `virtual:enhance-app` 虚拟模块自动注入客户端代码。
+ *
+ * @example
+ * ```ts
+ * export const myPlugin = definePlugin((options?: MyOptions) => ({
+ *   name: 'vitepress-plugin-my',
+ *   markdown: { config: (md) => md.use(myMarkdownPlugin) },
+ *   client: { enhance: true },
+ * }))
+ * ```
+ */
 interface VitepressPlugin extends Pick<UserConfig, 'markdown' | 'vite' | 'vue' | 'buildEnd' | 'transformHead' | 'transformHtml' | 'transformPageData' | 'postRender'> {
   /**
-   * 插件名称
+   * Unique name of the plugin, also used as the client module specifier.
+   *
+   * 插件的唯一名称，同时用作客户端模块标识符。
    */
   name: string;
   /**
-   * 以 import enhanceApp from 'virtual:enhance-app' 注入到客户端代码中。
+   * Client-side injection descriptor consumed by the `virtual:enhance-app` module.
    *
-   * 在 `.vitepress/theme/index.ts` 中调用 enhanceApp(ctx)，
-   * 完成插件的客户端代码的自动注入，插件使用者无需手动添加。
+   * When set, the built-in virtual plugin generates
+   * `import enhanceApp from 'virtual:enhance-app'` and invokes it inside
+   * `.vitepress/theme/index.ts` via `enhanceApp(ctx)`, so plugin consumers do
+   * not need to wire up client code manually.
+   *
+   * 客户端注入描述符，由 `virtual:enhance-app` 模块消费。
+   *
+   * 设置后，内置虚拟插件会生成 `import enhanceApp from 'virtual:enhance-app'`，
+   * 并在 `.vitepress/theme/index.ts` 中通过 `enhanceApp(ctx)` 调用，
+   * 完成插件客户端代码的自动注入，插件使用者无需手动添加。
    */
   client?: {
     /**
-     * 添加自定义的 import 语句.
+     * Custom import statements injected into the generated client module.
+     *
+     * 向生成的客户端模块注入自定义 import 语句。
      *
      * @example
-     * 导入 css 文件
+     * Import a CSS file / 导入 CSS 文件
      * ```ts
      * {
      *   imports: ['import "vitepress-plugin-xxx/styles/index.css"'],
@@ -26,12 +61,16 @@ interface VitepressPlugin extends Pick<UserConfig, 'markdown' | 'vite' | 'vue' |
      */
     imports?: string[];
     /**
+     * Name of the named `enhanceApp` function exported from
+     * `vitepress-plugin-xxx/client`. This function is invoked as
+     * `enhanceApp(ctx)` inside `vitepress/theme/index.ts`.
+     *
      * 插件包 `vitepress-plugin-xxx/client` 中导出的具名 `enhanceApp` 函数名。
-     * 该函数会在 `vitepress/theme/index.ts` 中 的 `enhanceApp(ctx)` 调用。
+     * 该函数会在 `vitepress/theme/index.ts` 中的 `enhanceApp(ctx)` 调用。
      *
-     * - 未设置时，默认不注入 enhanceApp 函数
-     * - 设置为 `true` 时，默认函数名为 `enhanceApp`
-     * - 设置为字符串时，函数名为该字符串
+     * - When unset, no `enhanceApp` function is injected / 未设置时，默认不注入 enhanceApp 函数
+     * - When `true`, the function name defaults to `enhanceApp` / 设置为 `true` 时，默认函数名为 `enhanceApp`
+     * - When a string, that string is used as the function name / 设置为字符串时，函数名为该字符串
      *
      * @example
      * ```ts
@@ -43,20 +82,93 @@ interface VitepressPlugin extends Pick<UserConfig, 'markdown' | 'vite' | 'vue' |
     enhance?: string | boolean;
   };
 }
+/**
+ * User configuration extension that adds a `plugins` field to VitePress's
+ * `UserConfig`.
+ *
+ * 用户配置扩展，为 VitePress 的 `UserConfig` 新增 `plugins` 字段。
+ */
 interface PluginsConfig {
   /**
-   * vitepress 插件
+   * List of vitepress-tuck plugins to be processed by `defineConfig`.
+   *
+   * 由 `defineConfig` 处理的 vitepress-tuck 插件列表。
    */
   plugins?: VitepressPlugin[];
 }
 //#endregion
 //#region src/define-config.d.ts
+/**
+ * Defines a VitePress configuration with plugin lifecycle management.
+ *
+ * This is the core function of vitepress-tuck. It accepts a standard VitePress
+ * `UserConfig` extended with a `plugins` field, then iterates over every plugin
+ * to extract client config, lifecycle hooks, and VitePress config fragments.
+ *
+ * Hook merging strategy:
+ * - **Parallel/concurrent**: `markdown.config`, `buildEnd`, `transformHead` run
+ *   via `Promise.all`; `transformHead` results are concatenated.
+ * - **Sequential/chained**: `transformHtml`, `transformPageData`, `postRender`
+ *   run in order, with each hook receiving the previous hook's result.
+ *
+ * User-provided hooks (from `userConfig`) are appended as the final step of
+ * each chain so they always run after plugin hooks. The returned config is a
+ * standard VitePress `UserConfig`, fully compatible with native VitePress.
+ *
+ * 定义带插件生命周期管理的 VitePress 配置。
+ *
+ * 这是 vitepress-tuck 的核心函数。它接收一个扩展了 `plugins` 字段的标准
+ * VitePress `UserConfig`，然后遍历所有插件，提取 client 配置、生命周期钩子和
+ * VitePress 配置片段。
+ *
+ * 钩子合并策略：
+ * - **并发类**：`markdown.config`、`buildEnd`、`transformHead` 通过 `Promise.all`
+ *   并发执行；`transformHead` 的结果会被拼接合并。
+ * - **顺序链式类**：`transformHtml`、`transformPageData`、`postRender` 按顺序执行，
+ *   每个钩子接收上一个钩子的结果。
+ *
+ * 用户提供的钩子（来自 `userConfig`）作为每条链的最后一步追加，确保始终在
+ * 插件钩子之后执行。返回值为标准 VitePress `UserConfig`，完全兼容原生 VitePress。
+ *
+ * @param config - VitePress user config with an optional `plugins` field / 带可选 `plugins` 字段的 VitePress 用户配置
+ * @returns A standard VitePress `UserConfig` with plugin hooks merged in / 合并了插件钩子的标准 VitePress `UserConfig`
+ * @example
+ * ```ts
+ * import { defineConfig } from 'vitepress-tuck'
+ * import { qrcode } from 'vitepress-plugin-qrcode'
+ *
+ * export default defineConfig({
+ *   plugins: [qrcode()],
+ *   title: 'My Site',
+ *   // standard VitePress options...
+ * })
+ * ```
+ */
 declare function defineConfig<ThemeConfig = DefaultTheme.Config>(config: UserConfig<NoInfer<ThemeConfig>> & PluginsConfig): UserConfig<NoInfer<ThemeConfig>>;
 //#endregion
 //#region src/define-plugin.d.ts
 /**
- * 提供一种 vitepress 插件的定义方式，简化用户配置的复杂度，将复杂度转移到 vitepress 插件中
+ * Defines a VitePress plugin with type inference.
+ *
+ * This is an identity function that preserves the plugin factory type while
+ * enabling TypeScript to infer the options type `T` from the factory signature.
+ * It simplifies user configuration by moving complexity into the plugin itself.
+ *
+ * 定义 VitePress 插件，提供类型推断。
+ *
+ * 这是一个恒等函数，保留插件工厂类型，同时让 TypeScript 从工厂签名推断选项
+ * 类型 `T`。它将复杂度转移到插件内部，从而简化用户配置。
+ *
+ * @param plugin - Plugin factory function returning a `VitepressPlugin` / 返回 `VitepressPlugin` 的插件工厂函数
+ * @returns The same plugin factory function / 相同的插件工厂函数
+ * @example
+ * ```ts
+ * export const myPlugin = definePlugin((options?: MyOptions) => ({
+ *   name: 'vitepress-plugin-my',
+ *   markdown: { config: (md) => md.use(myMarkdownPlugin) },
+ * }))
+ * ```
  */
-declare function definePlugin<T>(plugin: (option?: T) => VitepressPlugin): (option?: T) => VitepressPlugin;
+declare function definePlugin<T>(plugin: (options?: T) => VitepressPlugin): (options?: T) => VitepressPlugin;
 //#endregion
 export { PluginsConfig, VitepressPlugin, defineConfig, definePlugin };

package/dist/index.js

@@ -2,7 +2,26 @@ import { isString, toTruthy } from "@pengzhanbo/utils";
 import { mergeConfig } from "vitepress";
 //#region src/define-plugin.ts
 /**
-* 提供一种 vitepress 插件的定义方式，简化用户配置的复杂度，将复杂度转移到 vitepress 插件中
+* Defines a VitePress plugin with type inference.
+*
+* This is an identity function that preserves the plugin factory type while
+* enabling TypeScript to infer the options type `T` from the factory signature.
+* It simplifies user configuration by moving complexity into the plugin itself.
+*
+* 定义 VitePress 插件，提供类型推断。
+*
+* 这是一个恒等函数，保留插件工厂类型，同时让 TypeScript 从工厂签名推断选项
+* 类型 `T`。它将复杂度转移到插件内部，从而简化用户配置。
+*
+* @param plugin - Plugin factory function returning a `VitepressPlugin` / 返回 `VitepressPlugin` 的插件工厂函数
+* @returns The same plugin factory function / 相同的插件工厂函数
+* @example
+* ```ts
+* export const myPlugin = definePlugin((options?: MyOptions) => ({
+*   name: 'vitepress-plugin-my',
+*   markdown: { config: (md) => md.use(myMarkdownPlugin) },
+* }))
+* ```
 */
 function definePlugin(plugin) {
 	return plugin;
@@ -10,6 +29,32 @@ function definePlugin(plugin) {
 //#endregion
 //#region src/builtin-plugins/virtual-enhance-app.ts
 let uuid = 0;
+/**
+* Creates a Vite virtual module plugin that generates the
+* `virtual:enhance-app` module on the fly.
+*
+* The generated module imports every plugin's client entry and chains their
+* `enhanceApp(ctx)` calls inside a single default export. Users import this
+* module once in `.vitepress/theme/index.ts` to activate all plugin client
+* side effects.
+*
+* 创建 Vite 虚拟模块插件，动态生成 `virtual:enhance-app` 模块。
+*
+* 生成的模块导入每个插件的客户端入口，并在单个默认导出中链式调用它们的
+* `enhanceApp(ctx)`。用户在 `.vitepress/theme/index.ts` 中导入该模块一次，
+* 即可激活所有插件的客户端副作用。
+*
+* @param options - Options describing imports and enhance functions / 描述导入与 enhance 函数的选项
+* @returns A Vite `Plugin` instance / Vite `Plugin` 实例
+* @example
+* `Generated module (conceptual)`:
+* ```ts
+* import { enhanceApp as enhanceApp$0 } from 'vitepress-plugin-foo/client'
+* export default function enhanceApp(ctx) {
+*  enhanceApp$0(ctx)
+* }
+* ```
+*/
 function virtualEnhanceApp(options) {
 	const moduleId = "virtual:enhance-app";
 	const resolveId = `\0${moduleId}`;
@@ -36,12 +81,35 @@ ${enhanceCode.join("\n")}
 		}
 	};
 }
+/**
+* Plugin factory wrapping `virtualEnhanceApp` as a vitepress-tuck plugin.
+*
+* 将 `virtualEnhanceApp` 包装为 vitepress-tuck 插件的工厂函数。
+*
+* @param options - Options forwarded to `virtualEnhanceApp` / 转发给 `virtualEnhanceApp` 的选项
+* @returns A `VitepressPlugin` that registers the virtual module / 注册虚拟模块的 `VitepressPlugin`
+*/
 const virtualEnhanceAppPlugin = definePlugin((options) => ({
 	name: "virtual-enhance-app",
 	vite: { plugins: [virtualEnhanceApp(options || {})] }
 }));
 //#endregion
 //#region src/builtin-plugins/index.ts
+/**
+* Returns the list of built-in plugins shipped with vitepress-tuck.
+*
+* Currently includes the `virtual:enhance-app` Vite plugin (for client code
+* injection) and a `vitepress-tuck:deps` plugin that marks
+* `vitepress-plugin-toolkit` as SSR non-external.
+*
+* 返回 vitepress-tuck 自带的内置插件列表。
+*
+* 当前包含用于客户端代码注入的 `virtual:enhance-app` Vite 插件，以及将
+* `vitepress-plugin-toolkit` 标记为 SSR 非外部依赖的 `vitepress-tuck:deps` 插件。
+*
+* @param options - Options for built-in plugin construction / 内置插件构建选项
+* @returns Array of built-in `VitepressPlugin` instances / 内置 `VitepressPlugin` 实例数组
+*/
 function builtinPlugins(options) {
 	return [virtualEnhanceAppPlugin(options.enhanceApp), () => ({
 		name: "vitepress-tuck:deps",
@@ -50,6 +118,52 @@ function builtinPlugins(options) {
 }
 //#endregion
 //#region src/define-config.ts
+/**
+* Defines a VitePress configuration with plugin lifecycle management.
+*
+* This is the core function of vitepress-tuck. It accepts a standard VitePress
+* `UserConfig` extended with a `plugins` field, then iterates over every plugin
+* to extract client config, lifecycle hooks, and VitePress config fragments.
+*
+* Hook merging strategy:
+* - **Parallel/concurrent**: `markdown.config`, `buildEnd`, `transformHead` run
+*   via `Promise.all`; `transformHead` results are concatenated.
+* - **Sequential/chained**: `transformHtml`, `transformPageData`, `postRender`
+*   run in order, with each hook receiving the previous hook's result.
+*
+* User-provided hooks (from `userConfig`) are appended as the final step of
+* each chain so they always run after plugin hooks. The returned config is a
+* standard VitePress `UserConfig`, fully compatible with native VitePress.
+*
+* 定义带插件生命周期管理的 VitePress 配置。
+*
+* 这是 vitepress-tuck 的核心函数。它接收一个扩展了 `plugins` 字段的标准
+* VitePress `UserConfig`，然后遍历所有插件，提取 client 配置、生命周期钩子和
+* VitePress 配置片段。
+*
+* 钩子合并策略：
+* - **并发类**：`markdown.config`、`buildEnd`、`transformHead` 通过 `Promise.all`
+*   并发执行；`transformHead` 的结果会被拼接合并。
+* - **顺序链式类**：`transformHtml`、`transformPageData`、`postRender` 按顺序执行，
+*   每个钩子接收上一个钩子的结果。
+*
+* 用户提供的钩子（来自 `userConfig`）作为每条链的最后一步追加，确保始终在
+* 插件钩子之后执行。返回值为标准 VitePress `UserConfig`，完全兼容原生 VitePress。
+*
+* @param config - VitePress user config with an optional `plugins` field / 带可选 `plugins` 字段的 VitePress 用户配置
+* @returns A standard VitePress `UserConfig` with plugin hooks merged in / 合并了插件钩子的标准 VitePress `UserConfig`
+* @example
+* ```ts
+* import { defineConfig } from 'vitepress-tuck'
+* import { qrcode } from 'vitepress-plugin-qrcode'
+*
+* export default defineConfig({
+*   plugins: [qrcode()],
+*   title: 'My Site',
+*   // standard VitePress options...
+* })
+* ```
+*/
 function defineConfig(config) {
 	const hooks = {
 		buildEnd: [],
@@ -65,6 +179,16 @@ function defineConfig(config) {
 		imports: [],
 		enhances: []
 	};
+	/**
+	* Iterates a list of plugins, extracting client config, lifecycle hooks, and
+	* VitePress config fragments into the shared accumulators (`hooks`,
+	* `enhanceApp`, `mergedConfig`).
+	*
+	* 遍历插件列表，将 client 配置、生命周期钩子和 VitePress 配置片段提取到
+	* 共享累加器（`hooks`、`enhanceApp`、`mergedConfig`）中。
+	*
+	* @param plugins - Plugins to process / 待处理的插件列表
+	*/
 	const processPlugins = (plugins) => {
 		plugins.forEach((plugin) => {
 			const { name, client, buildEnd, transformHead, transformHtml, transformPageData, postRender, ...customConfig } = plugin;

package/package.json

@@ -1,15 +1,19 @@
 {
   "name": "vitepress-tuck",
   "type": "module",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Enhance vitepress configuration, provide plugins capability.",
   "author": "pengzhanbo <q942450674@outlook.com> (https://github.com/pengzhanbo/)",
   "license": "MIT",
+  "homepage": "https://tuck.pengzhanbo.cn/",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pengzhanbo/vitepress-tuck.git",
     "directory": "packages/vitepress-tuck"
   },
+  "bugs": {
+    "url": "https://github.com/pengzhanbo/vitepress-tuck/issues"
+  },
   "keywords": [
     "vitepress",
     "vitepress-plugin"