vitepress-tuck 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pengzhanbo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,115 @@
+vitepress-tuck
+
+Enhance vitepress configuration and provide plugin development capabilities.
+
+> [!NOTE]
+> vitepress itself does not provide complete plugin development capabilities. Some existing slightly complex plugins often need to be configured in both the `markdown` and `vite` sections of the configuration file. The process of integrating plugins in vitepress for users is scattered and difficult to maintain.
+>
+> `tuck` provides vitepress with simple, flexible, and low-barrier plugin development capabilities:
+>
+> - Developers can directly develop plugins using `definePlugin`;
+> - Users only need to add plugins in the `plugins` configuration.
+
+Install
+
+```bash
+npm
+npm install vitepress vitepress-tuck
+
+pnpm
+pnpm add vitepress vitepress-tuck
+
+yarn
+yarn add vitepress vitepress-tuck
+```
+
+Using tuck in vitepress
+
+Replace `defineConfig` from `vitepress` with `defineConfig` from `vitepress-tuck`
+
+```ts
+// .vitepress/config.ts
+import { defineConfig } from 'vitepress-tuck'
+
+export default defineConfig({
+  plugins: [
+    // Add plugins here
+  ],
+  // Other vitepress configuration items
+})
+```
+
+In the client configuration file, import `virtual:enhance-app` to automatically inject the plugin's client code:
+
+```ts
+// .vitepress/theme/index.ts
+import type { Theme } from 'vitepress'
+import enhanceApp from 'virtual:enhance-app'
+import DefaultTheme from 'vitepress/theme'
+
+export default {
+  extends: DefaultTheme,
+  enhanceApp(ctx) {
+    enhanceApp(ctx)
+  },
+} satisfies Theme
+```
+
+Plugin Development
+
+Develop plugins using `definePlugin`.
+
+```ts
+// Plugin development
+import { definePlugin } from 'vitepress-tuck'
+
+export default definePlugin((options?: MyPluginOptions) => ({
+  name: 'vitepress-plugin-my-plugin',
+  // Client configuration of the plugin, used to inject into the client config file
+  client: {
+    imports: [], // Modules that the client needs to import, e.g., style files
+    enhance: 'enhanceAppWithMyPlugin', // Named export of the client enhancement function
+  },
+  markdown: {
+    config: (md) => {
+      // Configure markdown plugin here
+      md.use(myMarkdownPlugin, options?.markdownOptions)
+    }
+  },
+  vite: {
+    // Configure vite here
+    plugins: [myVitePlugin(options?.viteOptions)]
+  },
+  // Other vitepress related hooks
+  buildEnd: () => {},
+  transformHead: () => {},
+  transformHtml: () => {},
+  transformPageData: () => {},
+  postRender: () => {},
+}))
+```
+
+When a plugin needs to provide components or other client code:
+
+Use the `client` field in the `exports` of `package.json` to export client code:
+
+```json
+{
+  "exports": {
+    ".": "./node/index.js",
+    "client": "./client/index.js"
+  }
+}
+```
+
+In `./client/index.js`, export a named function with the same name as `client.enhance`:
+
+```ts
+// client/index.js
+export function enhanceAppWithMyPlugin({ app }: EnhanceAppContext) {
+  // Add plugin's client code here
+  app.component('MyComponent', MyComponent)
+}
+```
+
+`vitepress-tuck` will check the `client` configuration and automatically inject the code into `virtual:enhance-app`.

package/README.zh-CN.md

@@ -0,0 +1,113 @@
+# vitepress-tuck
+
+增强 vitepress 配置，并提供插件开发能力。
+
+> [!NOTE]
+> vitepress 本身并没有提供完备的插件开发能力，现有的一些稍微复杂的插件往往需要同时在配置文件的 `markdown` 和 `vite` 中进行配置，用户在 vitepress 中接入插件的过程比较散乱，难以维护。
+>
+> `tuck` 为 vitepress 提供了简单灵活，低门槛的插件开发能力：
+>
+> - 开发者可直接通过 `definePlugin` 开发插件；
+> - 用户仅需要在 `plugins` 配置中添加插件。
+
+## Install
+
+```bash
+# npm
+npm install vitepress vitepress-tuck
+# pnpm
+pnpm add vitepress vitepress-tuck
+# yarn
+yarn add vitepress vitepress-tuck
+```
+
+## 在 vitepress 中使用 tuck
+
+使用 `vitepress-tuck` 的 `defineConfig` 代替 `vitepress` 的 `defineConfig`
+
+```ts
+// .vitepress/config.ts
+import { defineConfig } from 'vitepress-tuck'
+
+export default defineConfig({
+  plugins: [
+    // 在这里添加插件
+  ],
+  // 其他 vitepress 配置项
+})
+```
+
+在 客户端配置文件中，引入 `virtual:enhance-app` 自动注入插件的客户端代码：
+
+```ts
+// .vitepress/theme/index.ts
+import type { Theme } from 'vitepress'
+import enhanceApp from 'virtual:enhance-app'
+import DefaultTheme from 'vitepress/theme'
+
+export default {
+  extends: DefaultTheme,
+  enhanceApp(ctx) {
+    enhanceApp(ctx)
+  },
+} satisfies Theme
+```
+
+## 插件开发
+
+使用 `definePlugin` 开发插件。
+
+```ts
+// 插件开发
+import { definePlugin } from 'vitepress-tuck'
+
+export default definePlugin((options?: MyPluginOptions) => ({
+  name: 'vitepress-plugin-my-plugin',
+  // 插件的客户端配置，用于注入到客户端配置文件中
+  client: {
+    imports: [], // 客户端需要导入的模块，比如 样式文件
+    enhance: 'enhanceAppWithMyPlugin', // 客户端增强函数的具名导出
+  },
+  markdown: {
+    config: (md) => {
+      // 在这里配置 markdown 插件
+      md.use(myMarkdownPlugin, options?.markdownOptions)
+    }
+  },
+  vite: {
+    // 在这里配置 vite
+    plugins: [myVitePlugin(options?.viteOptions)]
+  },
+  // 其他 vitepress 的相关钩子
+  buildEnd: () => {},
+  transformHead: () => {},
+  transformHtml: () => {},
+  transformPageData: () => {},
+  postRender: () => {},
+}))
+```
+
+当插件需要提供组件或其他客户端代码时：
+
+在 `package.json` 的 `exports` 中使用 `client` 字段导出客户端代码：
+
+```json
+{
+  "exports": {
+    ".": "./node/index.js",
+    "client": "./client/index.js"
+  }
+}
+```
+
+在 `./client/index.js` 中，导出一个与 `client.enhance` 同名的具名函数：
+
+```ts
+// client/index.js
+export function enhanceAppWithMyPlugin({ app }: EnhanceAppContext) {
+  // 在这里添加插件的客户端代码
+  app.component('MyComponent', MyComponent)
+}
+```
+
+`vitepress-tuck` 会检查 `client` 配置，将代码自动注入到 `virtual:enhance-app` 中。

package/client-types.d.ts

@@ -0,0 +1,7 @@
+declare module 'virtual:enhance-app' {
+
+  import type { EnhanceAppContext } from 'vitepress/client'
+
+  const enhanceApp: (ctx: EnhanceAppContext) => void
+  export default enhanceApp
+}

package/dist/index.d.ts

@@ -0,0 +1,62 @@
+import { DefaultTheme, UserConfig } from "vitepress";
+
+//#region src/types.d.ts
+interface VitepressPlugin extends Pick<UserConfig, 'markdown' | 'vite' | 'vue' | 'buildEnd' | 'transformHead' | 'transformHtml' | 'transformPageData' | 'postRender'> {
+  /**
+   * 插件名称
+   */
+  name: string;
+  /**
+   * 以 import enhanceApp from 'virtual:enhance-app' 注入到客户端代码中。
+   *
+   * 在 `.vitepress/theme/index.ts` 中调用 enhanceApp(ctx)，
+   * 完成插件的客户端代码的自动注入，插件使用者无需手动添加。
+   */
+  client?: {
+    /**
+     * 添加自定义的 import 语句.
+     *
+     * @example
+     * 导入 css 文件
+     * ```ts
+     * {
+     *   imports: ['import "vitepress-plugin-xxx/styles/index.css"'],
+     * }
+     * ```
+     */
+    imports?: string[];
+    /**
+     * 插件包 `vitepress-plugin-xxx/client` 中导出的具名 `enhanceApp` 函数名。
+     * 该函数会在 `vitepress/theme/index.ts` 中 的 `enhanceApp(ctx)` 调用。
+     *
+     * - 未设置时，默认不注入 enhanceApp 函数
+     * - 设置为 `true` 时，默认函数名为 `enhanceApp`
+     * - 设置为字符串时，函数名为该字符串
+     *
+     * @example
+     * ```ts
+     * {
+     *   enhance: 'enhanceAppWithXXX',
+     * }
+     * ```
+     */
+    enhance?: string | boolean;
+  };
+}
+interface PluginsConfig {
+  /**
+   * vitepress 插件
+   */
+  plugins?: VitepressPlugin[];
+}
+//#endregion
+//#region src/define-config.d.ts
+declare function defineConfig<ThemeConfig = DefaultTheme.Config>(config: UserConfig<NoInfer<ThemeConfig>> & PluginsConfig): UserConfig<NoInfer<ThemeConfig>>;
+//#endregion
+//#region src/define-plugin.d.ts
+/**
+ * 提供一种 vitepress 插件的定义方式，简化用户配置的复杂度，将复杂度转移到 vitepress 插件中
+ */
+declare function definePlugin<T>(plugin: (option?: T) => VitepressPlugin): (option?: T) => VitepressPlugin;
+//#endregion
+export { PluginsConfig, VitepressPlugin, defineConfig, definePlugin };

package/dist/index.js

@@ -0,0 +1,139 @@
+import { isString, toTruthy } from "@pengzhanbo/utils";
+import { mergeConfig } from "vitepress";
+//#region src/define-plugin.ts
+/**
+* 提供一种 vitepress 插件的定义方式，简化用户配置的复杂度，将复杂度转移到 vitepress 插件中
+*/
+function definePlugin(plugin) {
+	return plugin;
+}
+//#endregion
+//#region src/builtin-plugins/virtual-enhance-app.ts
+let uuid = 0;
+function virtualEnhanceApp(options) {
+	const moduleId = "virtual:enhance-app";
+	const resolveId = `\0${moduleId}`;
+	return {
+		name: "virtual-enhance-app",
+		resolveId(id) {
+			if (id === moduleId) return resolveId;
+		},
+		load(id) {
+			if (id === resolveId) {
+				const { imports = [], enhances } = options;
+				const enhanceCode = [];
+				enhances?.forEach(({ moduleName, exportName }) => {
+					const alias = `${exportName}$${uuid++}`;
+					imports.push(`import { ${exportName} as ${alias} } from '${moduleName}/client'`);
+					enhanceCode.push(`  ${alias}(ctx)`);
+				});
+				return `${imports.join("\n")}\n
+export default function enhanceApp(ctx) {
+${enhanceCode.join("\n")}
+}
+`;
+			}
+		}
+	};
+}
+const virtualEnhanceAppPlugin = definePlugin((options) => ({
+	name: "virtual-enhance-app",
+	vite: { plugins: [virtualEnhanceApp(options || {})] }
+}));
+//#endregion
+//#region src/builtin-plugins/index.ts
+function builtinPlugins(options) {
+	return [virtualEnhanceAppPlugin(options.enhanceApp), () => ({
+		name: "vitepress-tuck:deps",
+		vite: { ssr: { noExternal: ["vitepress-plugin-toolkit"] } }
+	})];
+}
+//#endregion
+//#region src/define-config.ts
+function defineConfig(config) {
+	const hooks = {
+		buildEnd: [],
+		transformHead: [],
+		transformHtml: [],
+		transformPageData: [],
+		postRender: [],
+		markdownConfig: []
+	};
+	const { plugins = [], ...userConfig } = config;
+	let mergedConfig = {};
+	const enhanceApp = {
+		imports: [],
+		enhances: []
+	};
+	const processPlugins = (plugins) => {
+		plugins.forEach((plugin) => {
+			const { name, client, buildEnd, transformHead, transformHtml, transformPageData, postRender, ...customConfig } = plugin;
+			if (client) {
+				client.imports?.length && enhanceApp.imports.push(...client.imports);
+				client.enhance && enhanceApp.enhances.push({
+					moduleName: name,
+					exportName: isString(client.enhance) ? client.enhance : "enhanceApp"
+				});
+			}
+			if (customConfig.markdown?.config) {
+				hooks.markdownConfig.push(customConfig.markdown.config);
+				delete customConfig.markdown.config;
+			}
+			buildEnd && hooks.buildEnd.push(buildEnd);
+			transformHead && hooks.transformHead.push(transformHead);
+			transformHtml && hooks.transformHtml.push(transformHtml);
+			transformPageData && hooks.transformPageData.push(transformPageData);
+			postRender && hooks.postRender.push(postRender);
+			mergedConfig = mergeConfig(mergedConfig, customConfig);
+		});
+	};
+	processPlugins(plugins);
+	processPlugins(builtinPlugins({ enhanceApp }));
+	mergedConfig = mergeConfig(mergedConfig, userConfig);
+	const useMarkdownConfig = mergedConfig.markdown?.config;
+	if (hooks.markdownConfig.length) {
+		mergedConfig.markdown ??= {};
+		mergedConfig.markdown.config = async (md) => {
+			await Promise.all([...hooks.markdownConfig.map((config) => config(md)), useMarkdownConfig?.(md)].filter(toTruthy));
+		};
+	}
+	if (hooks.buildEnd.length) {
+		const buildEnd = mergedConfig.buildEnd;
+		mergedConfig.buildEnd = async (site) => {
+			await Promise.all([...hooks.buildEnd.map((hook) => hook(site)), buildEnd?.(site)].filter(toTruthy));
+		};
+	}
+	if (hooks.transformHead.length) {
+		const transformHead = mergedConfig.transformHead;
+		mergedConfig.transformHead = async (site) => {
+			const result = await Promise.all([...hooks.transformHead.map((hook) => hook(site)), transformHead?.(site)].filter(toTruthy));
+			const headConfigs = [];
+			for (const item of result) item && headConfigs.push(...item);
+			return headConfigs;
+		};
+	}
+	if (hooks.transformHtml.length) {
+		const transformHtml = mergedConfig.transformHtml;
+		mergedConfig.transformHtml = async (code, id, ctx) => {
+			for (const hook of hooks.transformHtml) code = await hook(code, id, ctx) || code;
+			return await transformHtml?.(code, id, ctx) || code;
+		};
+	}
+	if (hooks.transformPageData.length) {
+		const transformPageData = mergedConfig.transformPageData;
+		mergedConfig.transformPageData = async (pageData, ctx) => {
+			for (const hook of hooks.transformPageData) pageData = await hook(pageData, ctx) || pageData;
+			return await transformPageData?.(pageData, ctx) || pageData;
+		};
+	}
+	if (hooks.postRender.length) {
+		const postRender = mergedConfig.postRender;
+		mergedConfig.postRender = async (context) => {
+			for (const hook of hooks.postRender) context = await hook(context) || context;
+			return await postRender?.(context) || context;
+		};
+	}
+	return mergedConfig;
+}
+//#endregion
+export { defineConfig, definePlugin };

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "vitepress-tuck",
+  "type": "module",
+  "version": "0.1.0",
+  "description": "Enhance vitepress configuration, provide plugins capability.",
+  "author": "pengzhanbo <q942450674@outlook.com> (https://github.com/pengzhanbo/)",
+  "license": "MIT",
+  "keywords": [
+    "vitepress",
+    "vitepress-plugin"
+  ],
+  "exports": {
+    ".": "./dist/index.js",
+    "./types": "./dist/index.d.ts",
+    "./client-types": "./client-types.d.ts"
+  },
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "client-types.d.ts",
+    "dist"
+  ],
+  "peerDependencies": {
+    "vitepress": "^1.6.4 || ^2.0.0-alpha.17"
+  },
+  "dependencies": {
+    "@pengzhanbo/utils": "^3.7.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown --config-loader unrun"
+  }
+}