vitepress-plugin-toolkit 0.3.0 → 0.5.0

package/dist/node/index.js

@@ -1,14 +1,80 @@
 import container from "markdown-it-container";
-import { camelCase, deepMerge, isBoolean, isNull, isNumber, isPrimitive, isString, isUndefined, kebabCase, objectEntries, objectKeys, omit, slash } from "@pengzhanbo/utils";
+import { LRUCache, camelCase, deepMerge, isArray, isBoolean, isNull, isNumber, isPrimitive, isString, isUndefined, kebabCase, objectEntries, objectKeys, omit, slash, toArray, uniq } from "@pengzhanbo/utils";
+import ansis from "ansis";
 import process from "node:process";
+import picomatch from "picomatch";
 import { createHash } from "node:crypto";
-import ansis from "ansis";
 //#region src/shared/link.ts
+/**
+* Regular expression that matches external URLs.
+*
+* Matches URLs that start with a protocol (such as `http:` or `mailto:`) or
+* with `//` (protocol-relative URLs).
+*
+* 匹配外部链接的正则表达式。
+*
+* 匹配以协议（如 `http:` 或 `mailto:`）或 `//`（协议相对链接）开头的 URL。
+*
+* @example
+* EXTERNAL_URL_RE.test('https://example.com') // true
+* EXTERNAL_URL_RE.test('//cdn.example.com/lib.js') // true
+* EXTERNAL_URL_RE.test('/about') // false
+*/
 const EXTERNAL_URL_RE = /^(?:[a-z]+:|\/\/)/i;
+/**
+* Checks whether the given path is an external URL.
+*
+* 判断给定路径是否为外部链接。
+*
+* @param path - The path to check / 要检查的路径
+* @returns `true` if the path is an external URL, otherwise `false` / 若为外部链接返回 `true`，否则返回 `false`
+* @example
+* isExternal('https://example.com') // true
+* isExternal('//cdn.example.com/lib.js') // true
+* isExternal('/about') // false
+* isExternal('mailto:foo@example.com') // true
+*/
 function isExternal(path) {
 	return EXTERNAL_URL_RE.test(path);
 }
+/**
+* Regular expression that matches the protocol scheme of a URL.
+*
+* Matches the leading protocol portion such as `http:`, `https:`, or
+* `mailto:`. Does not match protocol-relative URLs (`//`).
+*
+* 匹配 URL 协议部分的正则表达式。
+*
+* 匹配前导协议部分，如 `http:`、`https:` 或 `mailto:`。
+* 不匹配协议相对链接（`//`）。
+*
+* @example
+* URL_PROTOCOL_RE.test('https://example.com') // true
+* URL_PROTOCOL_RE.test('mailto:foo@example.com') // true
+* URL_PROTOCOL_RE.test('//cdn.example.com/lib.js') // false
+*/
 const URL_PROTOCOL_RE = /^[a-z][a-z0-9+.-]*:/;
+/**
+* Checks whether the given link contains a URL protocol scheme or is a
+* protocol-relative URL.
+*
+* Unlike {@link isExternal}, this function also matches links that start with
+* `//` via an additional check, in addition to those matched by
+* {@link URL_PROTOCOL_RE}.
+*
+* 判断给定链接是否包含 URL 协议部分或为协议相对链接。
+*
+* 与 {@link isExternal} 不同，此函数除了匹配 {@link URL_PROTOCOL_RE} 之外，
+* 还会通过额外检查匹配以 `//` 开头的链接。
+*
+* @param link - The link to check / 要检查的链接
+* @returns `true` if the link has a protocol or starts with `//` / 若链接包含协议或以 `//` 开头则返回 `true`
+* @example
+* isLinkWithProtocol('https://example.com') // true
+* isLinkWithProtocol('mailto:foo@example.com') // true
+* isLinkWithProtocol('//cdn.example.com/lib.js') // true
+* isLinkWithProtocol('/about') // false
+*/
 function isLinkWithProtocol(link) {
 	return URL_PROTOCOL_RE.test(link) || link.startsWith("//");
 }
@@ -28,6 +94,13 @@ const RE_ATTR_VALUE = /(?:^|\s+)(?<attr>[\w-]+)(?:=(?<quote>['"])(?<valueWithQuo
 * @param info - Attribute string / 属性字符串
 * @returns Object with attrs and rawAttrs / 包含 attrs 和 rawAttrs 的对象
 * @typeParam T - Attribute type / 属性类型
+* @example
+* ```ts
+* resolveAttrs('width="100" height="50"')
+* // { width: '100', height: '50' }
+* resolveAttrs('disabled title="Hello"')
+* // { disabled: true, title: 'Hello' }
+* ```
 */
 function resolveAttrs(info) {
 	info = info.trim();
@@ -54,6 +127,11 @@ function resolveAttrs(info) {
 * @param info - Info string / 信息字符串
 * @param key - Attribute key / 属性键
 * @returns Attribute value or undefined / 属性值或 undefined
+* @example
+* ```ts
+* resolveAttr('width="100" height="50"', 'width') // '100'
+* resolveAttr('width="100" height="50"', 'color') // undefined
+* ```
 */
 function resolveAttr(info, key) {
 	const pattern = new RegExp(`(?:^|\\s+)${key}(?:=(?<quote>['"])(?<valueWithQuote>.+?)\\k<quote>|=(?<valueWithoutQuote>\\S+))?(?:\\s+|$)`);
@@ -72,6 +150,13 @@ function resolveAttr(info, key) {
 * @param options - Optional before/after render hooks / 可选的 before/after 渲染钩子
 * @param options.before - Callback for rendering container opening tag / 渲染容器起始标签时的回调函数
 * @param options.after - Callback for rendering container closing tag / 渲染容器结束标签时的回调函数
+* @example
+* ```ts
+* md.use(createContainerPlugin, 'tip', {
+*   before: info => `<div class="tip">${info}`,
+*   after: () => '</div>',
+* })
+* ```
 */
 function createContainerPlugin(md, type, { before, after } = {}) {
 	const render = (tokens, index, options, env) => {
@@ -153,6 +238,7 @@ function createContainerSyntaxPlugin(md, type, render) {
 }
 //#endregion
 //#region src/node/markdown/embed.ts
+const EXISTS_TYPES = /* @__PURE__ */ new WeakMap();
 /**
 * Create embed rule block
 *
@@ -165,48 +251,82 @@ function createContainerSyntaxPlugin(md, type, render) {
 * @param md - Markdown instance / Markdown 实例
 * @param {EmbedRuleBlockOptions} options - Embed rule block options / 嵌入规则块选项
 * @typeParam Meta - Metadata type / 元数据类型
+* @example
+* ```ts
+* createEmbedRuleBlock(md, {
+*   type: 'video',
+*   meta: (info, source) => ({ src: source, title: info }),
+*   content: meta => `<video src="${meta.src}" title="${meta.title}"></video>`,
+* })
+* ```
 */
-function createEmbedRuleBlock(md, { type, name = type, syntaxPattern, beforeName = "code", ruleOptions = { alt: [
-	"paragraph",
-	"reference",
-	"blockquote",
-	"list"
-] }, meta, content }) {
+function createEmbedRuleBlock(md, { type, name = `embed_${type}`, meta, content }) {
+	if (!type) {
+		console.warn(`${ansis.yellow("[markdown-it]")} Embed rule block type is empty`);
+		return;
+	}
+	let exists = EXISTS_TYPES.get(md);
+	!exists && EXISTS_TYPES.set(md, exists = /* @__PURE__ */ new Set());
+	if (exists.has(type)) {
+		console.warn(`${ansis.yellow("[markdown-it]")} Embed rule block type ${ansis.green(type)} already exists`);
+		return;
+	}
+	if (md.renderer.rules[name]) {
+		console.warn(`${ansis.yellow("[markdown-it]")} Embed rule block ${type} (${name}) already exists`);
+		return;
+	}
+	exists.add(type);
 	const MIN_LENGTH = type.length + 5;
 	const START_CODES = [
 		64,
 		91,
 		...type.split("").map((c) => c.charCodeAt(0))
 	];
-	md.block.ruler.before(beforeName, name, (state, startLine, endLine, silent) => {
+	const escapedType = type.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+	const syntaxPattern = new RegExp(`^@\\[${escapedType}(?:\\s+([^\\]]*))?\\]\\(([^)]*)\\)$`);
+	md.block.ruler.before("code", name, (state, startLine, endLine, silent) => {
 		const pos = state.bMarks[startLine] + state.tShift[startLine];
 		const max = state.eMarks[startLine];
 		if (pos + MIN_LENGTH > max) return false;
 		for (let i = 0; i < START_CODES.length; i += 1) if (state.src.charCodeAt(pos + i) !== START_CODES[i]) return false;
-		const content = state.src.slice(pos, max);
+		const content = state.src.slice(pos, max).trim();
 		const match = content.match(syntaxPattern);
 		if (!match) return false;
 		/* istanbul ignore if -- @preserve */
 		if (silent) return true;
 		const token = state.push(name, "", 0);
-		token.meta = meta(match);
+		const [, info = "", source = ""] = match;
+		token.meta = meta(info.trim(), source.trim());
 		token.content = content;
 		token.map = [startLine, startLine + 1];
 		state.line = startLine + 1;
 		return true;
-	}, ruleOptions);
-	md.renderer.rules[name] = (tokens, index, _, env) => {
-		const token = tokens[index];
-		token.content = content(token.meta, token.content, env);
-		return token.content;
-	};
+	}, { alt: [
+		"paragraph",
+		"reference",
+		"blockquote",
+		"list"
+	] });
+	md.renderer.rules[name] = (tokens, index, _, env) => content?.(tokens[index].meta, env) ?? tokens[index].content;
 }
 //#endregion
 //#region src/node/utils/constants.ts
+/**
+* Whether the current process is running in production build mode.
+*
+* 当前进程是否运行在生产构建模式下。
+*/
 const isBuild = process.env.NODE_ENV === "production";
+/**
+* Whether the current process is running in development mode.
+*
+* 当前进程是否运行在开发模式下。
+*/
 const isDev = process.env.NODE_ENV === "development";
 /**
-* 浏览器支持的视频文件名扩展名
+* Browser-supported video file name extensions.
+*
+* 浏览器支持的视频文件名扩展名。
 */
 const EXTENSION_VIDEOS = [
 	"mp4",
@@ -224,7 +344,9 @@ const EXTENSION_VIDEOS = [
 	"ogv"
 ];
 /**
-* 浏览器支持的图片文件名扩展名
+* Browser-supported image file name extensions.
+*
+* 浏览器支持的图片文件名扩展名。
 */
 const EXTENSION_IMAGES = [
 	"jpg",
@@ -244,7 +366,9 @@ const EXTENSION_IMAGES = [
 	"xbm"
 ];
 /**
-* 浏览器支持的音频文件名扩展名
+* Browser-supported audio file name extensions.
+*
+* 浏览器支持的音频文件名扩展名。
 */
 const EXTENSION_AUDIOS = [
 	"mp3",
@@ -257,12 +381,81 @@ const EXTENSION_AUDIOS = [
 ];
 //#endregion
 //#region src/node/utils/hash.ts
+/**
+* Generate a SHA-256 hash from the given data.
+*
+* 根据给定数据生成 SHA-256 哈希值。
+*
+* Primitive values are converted to strings directly, while objects are serialized
+* to JSON before hashing. When `length` is provided, the hash is truncated to the
+* specified length.
+*
+* 基本类型直接转为字符串，对象则序列化为 JSON 后再哈希。提供 `length` 时，
+* 哈希值会被截断到指定长度。
+*
+* @param data - The data to hash, can be any value / 要哈希的数据，可以是任意值
+* @param length - Optional length to truncate the hash / 可选的哈希值截断长度
+* @returns The SHA-256 hash string (truncated if length is given)
+*   / SHA-256 哈希字符串（指定长度时会被截断）
+* @example
+* ```ts
+* genHash('hello') // full sha256 hash
+* genHash({ a: 1 }, 8) // 8-character hash
+* ```
+*/
 function genHash(data, length) {
 	const str = isPrimitive(data) ? String(data) : JSON.stringify(data);
 	const hash = createHash("sha256").update(str).digest("hex");
 	return length ? hash.slice(0, length) : hash;
 }
 //#endregion
+//#region src/node/utils/createMatcher.ts
+const cache = new LRUCache({ maxSize: 100 });
+/**
+* Create a matcher for the given include and exclude patterns.
+*
+* 创建一个用于给定 include 和 exclude 模式的匹配器。
+*
+* @param include - Patterns to include, can be string or array / 要包含的模式，可以是字符串或数组
+* @param exclude - Patterns to exclude, can be string or array / 要排除的模式，可以是字符串或数组
+* @returns Matcher instance / 匹配器实例
+*/
+function createMatcher(include, exclude) {
+	const key = genHash([normalize(include), normalize(exclude)]);
+	if (cache.has(key)) return cache.get(key);
+	const { pattern, ignore } = resolveMatcherPattern(include, exclude);
+	const matcher = picomatch(pattern, { ignore });
+	cache.set(key, matcher);
+	return matcher;
+}
+/**
+* Resolve include and exclude patterns into pattern and ignore arrays.
+* Converts various pattern formats into a standardized format for matching.
+*
+* 将 include 和 exclude 模式解析为 pattern 和 ignore 数组。
+* 将各种模式格式转换为用于匹配的标准化格式。
+*
+* @param include - Patterns to include, can be string or array / 要包含的模式，可以是字符串或数组
+* @param exclude - Patterns to exclude, can be string or array / 要排除的模式，可以是字符串或数组
+* @returns Object containing pattern and ignore arrays / 包含 pattern 和 ignore 数组的对象
+*/
+function resolveMatcherPattern(include, exclude) {
+	const pattern = [];
+	const ignore = uniq(toArray(exclude));
+	toArray(include).forEach((item) => {
+		if (item.startsWith("!")) ignore.push(item.slice(1));
+		else pattern.push(item);
+	});
+	if (pattern.length === 0) pattern.push("*");
+	return {
+		pattern,
+		ignore
+	};
+}
+function normalize(arr) {
+	return isArray(arr) ? arr.sort((a, b) => a.localeCompare(b)) : arr;
+}
+//#endregion
 //#region src/node/utils/logger.ts
 /**
 * Log levels mapping
@@ -284,6 +477,13 @@ const logLevels = {
 * @param prefix - Log prefix / 日志前缀
 * @param defaultLevel - Default log level / 默认日志级别
 * @returns Logger instance / 日志实例
+* @example
+* ```ts
+* const logger = createLogger('my-plugin', 'info')
+* logger.info('Starting build')
+* logger.warn('Deprecated feature used')
+* logger.debug('Verbose details', 'debug')
+* ```
 */
 function createLogger(prefix, defaultLevel = "info") {
 	prefix = `[${prefix}]`;
@@ -326,6 +526,12 @@ function createLogger(prefix, defaultLevel = "info") {
 * @param str - Size string / 尺寸字符串
 * @param unit - Unit to append (default: 'px') / 要添加的单位（默认：'px'）
 * @returns Size string with unit / 带单位的尺寸字符串
+* @example
+* ```ts
+* parseRect('100') // '100px'
+* parseRect('50%') // '50%'
+* parseRect('200', 'rpx') // '200rpx'
+* ```
 */
 function parseRect(str, unit = "px") {
 	if (Number.parseFloat(str) === Number(str)) return `${str}${unit}`;
@@ -337,7 +543,25 @@ const rControl = /[\u0000-\u001F]/g;
 const rSpecial = /[\s~`!@#$%^&*()\-_+=[\]{}|\\;:"'“”‘’<>,.?/]+/g;
 const rCombining = /[\u0300-\u036F]/g;
 /**
-* Default slugification function
+* Default slugification function that normalizes a string into a URL-safe slug.
+*
+* 默认的 slug 化函数，将字符串规范化为 URL 安全的 slug。
+*
+* The function removes accents, control characters, and special characters,
+* replaces separators with hyphens, and ensures the result does not start
+* with a number.
+*
+* 该函数会移除重音符号、控制字符和特殊字符，用连字符替换分隔符，
+* 并确保结果不以数字开头。
+*
+* @param str - The string to slugify / 要 slug 化的字符串
+* @returns The slugified string / slug 化后的字符串
+* @example
+* ```ts
+* slugify('Hello World!') // 'hello-world'
+* slugify('你好 World') // '你好-world'
+* slugify('1st Section') // '_1st-section'
+* ```
 */
 function slugify(str) {
 	return str.normalize("NFKD").replace(rCombining, "").replace(rControl, "").replace(rSpecial, "-").replace(/-{2,}/g, "-").replace(/^-+|-+$/g, "").replace(/^(\d)/, "_$1").toLowerCase();
@@ -354,6 +578,13 @@ function slugify(str) {
 * @param forceStringify - Keys to force stringify / 强制字符串化的键
 * @returns HTML attribute string / HTML 属性字符串
 * @typeParam T - Attribute type / 属性类型
+* @example
+* ```ts
+* stringifyAttrs({ width: 100, disabled: true })
+* // ' :width="100" disabled'
+* stringifyAttrs({ title: 'hello', visible: false })
+* // ' title="hello"'
+* ```
 */
 function stringifyAttrs(attrs, withUndefinedOrNull = false, forceStringify = []) {
 	const result = objectEntries(attrs).map(([key, value]) => {
@@ -375,7 +606,41 @@ function stringifyAttrs(attrs, withUndefinedOrNull = false, forceStringify = [])
 }
 //#endregion
 //#region src/node/utils/treat-as-html.ts
+/**
+* Set of file extensions that should be treated as static assets rather than HTML.
+*
+* 应作为静态资源而非 HTML 处理的文件扩展名集合。
+*
+* Populated lazily on first use, combining a built-in list of known extensions
+* with any extra extensions provided via the `VITE_EXTRA_EXTENSIONS` environment
+* variable.
+*
+* 在首次使用时延迟填充，将内置已知扩展名列表与通过 `VITE_EXTRA_EXTENSIONS`
+* 环境变量提供的额外扩展名合并。
+*/
 const KNOWN_EXTENSIONS = /* @__PURE__ */ new Set();
+/**
+* Determine whether a file should be treated as an HTML route based on its extension.
+*
+* 根据文件扩展名判断该文件是否应作为 HTML 路由处理。
+*
+* Returns `true` when the file has no extension or its extension is not in the
+* known extensions list (meaning it should be served as an HTML page). Returns
+* `false` for known static asset extensions.
+*
+* 当文件没有扩展名或其扩展名不在已知扩展名列表中时返回 `true`（表示应作为
+* HTML 页面提供）。对于已知的静态资源扩展名返回 `false`。
+*
+* @param filename - The filename to check / 要检查的文件名
+* @returns `true` if the file should be treated as HTML, `false` otherwise
+*   / 如果文件应作为 HTML 处理则返回 `true`，否则返回 `false`
+* @example
+* ```ts
+* treatAsHtml('about') // true (no extension)
+* treatAsHtml('logo.png') // false (known image extension)
+* treatAsHtml('custom.xyz') // true (unknown extension)
+* ```
+*/
 function treatAsHtml(filename) {
 	if (KNOWN_EXTENSIONS.size === 0) {
 		const extraExts = typeof process === "object" && process.env?.VITE_EXTRA_EXTENSIONS || import.meta.env?.VITE_EXTRA_EXTENSIONS || "";
@@ -386,15 +651,54 @@ function treatAsHtml(filename) {
 }
 //#endregion
 //#region src/node/vite-plugins/iconPlugin.ts
+/**
+* Vite plugin name for the icons virtual module.
+*
+* 图标虚拟模块的 Vite 插件名称。
+*/
 const name = "vitepress:tuck-icons";
+/**
+* Global list of resolved icons accumulated across plugin invocations.
+*
+* 跨插件调用累积的全局已解析图标列表。
+*/
 const iconList = [];
+/**
+* Whether the virtual module is currently being processed.
+*
+* 虚拟模块是否正在处理中。
+*/
 let isProcessing = false;
+/**
+* Create a Vite plugin that registers SVG icons as CSS custom properties.
+*
+* 创建一个 Vite 插件，将 SVG 图标注册为 CSS 自定义属性。
+*
+* The plugin collects icons into a global list and exposes them through a
+* virtual module `virtual:tuck-icons.css`. Each icon is rendered as a CSS
+* rule that sets the `--icon` custom property on `.vpi-<name>` selectors.
+*
+* 该插件将图标收集到全局列表中，并通过虚拟模块 `virtual:tuck-icons.css`
+* 暴露它们。每个图标被渲染为一条 CSS 规则，在 `.vpi-<name>` 选择器上
+* 设置 `--icon` 自定义属性。
+*
+* @param icons - Array of icon definitions to register / 要注册的图标定义数组
+* @returns A Vite plugin instance / Vite 插件实例
+* @example
+* ```ts
+* import { iconPlugin } from 'vitepress-plugin-toolkit/node'
+* icons: iconPlugin([
+*   { name: 'github', svg: '<svg>...</svg>' },
+*   { name: 'twitter', svg: '<svg>...</svg>' },
+* ])
+* ```
+*/
 function iconPlugin(icons) {
 	for (const icon of icons) {
 		const index = iconList.findIndex((item) => item.name === icon.name);
 		if (index === -1) iconList.push({
 			...omit(icon, ["classname"]),
-			classname: new Set([icon.classname || icon.name])
+			classname: /* @__PURE__ */ new Set([icon.classname || icon.name])
 		});
 		else icon.classname && iconList[index].classname.add(icon.classname);
 	}
@@ -414,8 +718,8 @@ function iconPlugin(icons) {
 			if (!isProcessing) return null;
 			let css = "";
 			for (const icon of iconList) {
-				const classname = Array.from(icon.classname).map((name) => `.vpi-${name}`).join(",\n");
-				css += `${classname} {\n  --icon: ${icon.svg};\n}\n`;
+				const classname = Array.from(icon.classname).map((name) => `.vpi-${name}`).join(",");
+				css += `${classname} { --icon: ${icon.svg}; }\n`;
 			}
 			isProcessing = false;
 			return css;
@@ -424,6 +728,26 @@ function iconPlugin(icons) {
 }
 //#endregion
 //#region src/node/vitepress/get-vitepress-config.ts
+/**
+* Get the current VitePress site configuration from the global context.
+*
+* 从全局上下文获取当前的 VitePress 站点配置。
+*
+* VitePress stores its resolved `SiteConfig` on `globalThis.VITEPRESS_CONFIG`
+* during the build and dev lifecycle. This helper reads that value and throws
+* when it has not been initialized yet.
+*
+* VitePress 在构建和开发生命周期中将解析后的 `SiteConfig` 存储在
+* `globalThis.VITEPRESS_CONFIG` 上。该辅助函数读取该值，未初始化时抛出错误。
+*
+* @returns The current VitePress site config / 当前的 VitePress 站点配置
+* @throws {Error} When VITEPRESS_CONFIG is not initialized / VITEPRESS_CONFIG 未初始化时
+* @example
+* ```ts
+* const config = getVitepressConfig()
+* console.log(config.userConfig.title)
+* ```
+*/
 function getVitepressConfig() {
 	const config = globalThis.VITEPRESS_CONFIG;
 	if (!config) throw new Error("VITEPRESS_CONFIG is not initialized");
@@ -432,10 +756,30 @@ function getVitepressConfig() {
 //#endregion
 //#region src/node/vitepress/createLocales.ts
 /**
-* 创建 locales
-* @param builtinLocales 内置的 locales
-* @param userLocales 用户的 locales
-* @returns locales
+* Create a locales configuration by merging builtin locales with user locales.
+*
+* 通过合并内置语言环境与用户语言环境来创建语言环境配置。
+*
+* The function reads the VitePress locales config, matches each locale key
+* (or its `lang` field) against the builtin locales, and falls back to the
+* first builtin locale for the `root` entry when no match is found. User
+* locales are deep-merged on top of the result.
+*
+* 该函数读取 VitePress 的语言环境配置，将每个语言环境键（或其 `lang` 字段）
+* 与内置语言环境匹配，未匹配到时 `root` 条目回退到第一个内置语言环境。
+* 用户语言环境会深度合并到结果之上。
+*
+* @param builtinLocales - Builtin locale entries / 内置语言环境条目
+* @param userLocales - User-provided locale overrides / 用户提供的语言环境覆盖
+* @returns Merged locales configuration / 合并后的语言环境配置
+* @typeParam LocaleData - Locale data type / 语言环境数据类型
+* @example
+* ```ts
+* const locales = createLocales(
+*   [[['en', 'en-US'], { title: 'English' }], [['zh', 'zh-CN'], { title: '中文' }]],
+*   { zh: { title: '我的站点' } },
+* )
+* ```
 */
 function createLocales(builtinLocales, userLocales = {}) {
 	const locales = {};
@@ -450,6 +794,27 @@ function createLocales(builtinLocales, userLocales = {}) {
 }
 //#endregion
 //#region src/node/vitepress/get-locale-with-path.ts
+/**
+* Resolve the locale and language code for a given path.
+*
+* 解析给定路径对应的语言环境和语言代码。
+*
+* The function inspects the VitePress locales config and finds the locale key
+* that the provided path starts with. When the matched key is `root`, the
+* returned locale is an empty string. Returns empty strings for both fields
+* when no locale matches.
+*
+* 该函数检查 VitePress 的语言环境配置，找到所提供路径以其开头的语言环境键。
+* 当匹配的键为 `root` 时，返回的语言环境为空字符串。无匹配时两个字段均返回空字符串。
+*
+* @param path - The path to resolve / 要解析的路径
+* @returns An object with `lang` and `locale` fields / 包含 `lang` 和 `locale` 字段的对象
+* @example
+* ```ts
+* getLocaleWithPath('/zh/guide/') // { lang: 'zh-CN', locale: '/zh/' }
+* getLocaleWithPath('/guide/') // { lang: 'en', locale: '' } (root locale)
+* ```
+*/
 function getLocaleWithPath(path) {
 	const locales = getVitepressConfig().userConfig?.locales || {};
 	const keys = objectKeys(locales);
@@ -465,7 +830,37 @@ function getLocaleWithPath(path) {
 }
 //#endregion
 //#region src/node/vitepress/resolve-route-link.ts
+/**
+* Regular expression matching `index.md` paths with an optional hash.
+*
+* 匹配带可选哈希的 `index.md` 路径的正则表达式。
+*/
 const indexRE = /(^|.*\/)index.md(.*)$/i;
+/**
+* Resolve a markdown link to its final URL form based on VitePress routing rules.
+*
+* 根据 VitePress 路由规则将 markdown 链接解析为最终 URL 形式。
+*
+* External links are returned as-is. Absolute paths are prefixed with the
+* site base. Hash links are slugified. Relative links to markdown files are
+* transformed according to the `cleanUrls` setting (`.md` becomes `''` or
+* `.html`), and `index.md` is collapsed to its directory.
+*
+* 外部链接原样返回。绝对路径添加站点 base 前缀。哈希链接进行 slug 化。
+* 指向 markdown 文件的相对链接根据 `cleanUrls` 设置转换（`.md` 变为 `''`
+* 或 `.html`），`index.md` 折叠为其所在目录。
+*
+* @param url - The raw URL from markdown content / markdown 内容中的原始 URL
+* @param env - The markdown environment with routing context / 带路由上下文的 markdown 环境
+* @returns The resolved URL / 解析后的 URL
+* @example
+* ```ts
+* resolveRouteLink('./guide.md', { cleanUrls: false } as MarkdownEnv)
+* // './guide.html'
+* resolveRouteLink('/about/', {} as MarkdownEnv)
+* // '/base/about/'
+* ```
+*/
 function resolveRouteLink(url, env) {
 	if (isExternal(url)) return url;
 	const config = getVitepressConfig();
@@ -488,8 +883,16 @@ function resolveRouteLink(url, env) {
 	}
 	return url;
 }
+/**
+* Normalize a hash fragment by slugifying its content.
+*
+* 通过对内容进行 slug 化来规范化哈希片段。
+*
+* @param str - The hash string (with leading `#`) or empty / 哈希字符串（带前导 `#`）或空字符串
+* @returns The encoded hash string or empty / 编码后的哈希字符串或空字符串
+*/
 function normalizeHash(str) {
 	return str ? encodeURI(`#${slugify(decodeURI(str).slice(1))}`) : "";
 }
 //#endregion
-export { EXTENSION_AUDIOS, EXTENSION_IMAGES, EXTENSION_VIDEOS, EXTERNAL_URL_RE, URL_PROTOCOL_RE, createContainerPlugin, createContainerSyntaxPlugin, createEmbedRuleBlock, createLocales, createLogger, genHash, getLocaleWithPath, getVitepressConfig, iconPlugin, isBuild, isDev, isExternal, isLinkWithProtocol, logLevels, parseRect, resolveAttr, resolveAttrs, resolveRouteLink, slugify, stringifyAttrs, treatAsHtml };
+export { EXTENSION_AUDIOS, EXTENSION_IMAGES, EXTENSION_VIDEOS, EXTERNAL_URL_RE, URL_PROTOCOL_RE, createContainerPlugin, createContainerSyntaxPlugin, createEmbedRuleBlock, createLocales, createLogger, createMatcher, genHash, getLocaleWithPath, getVitepressConfig, iconPlugin, isBuild, isDev, isExternal, isLinkWithProtocol, logLevels, parseRect, resolveAttr, resolveAttrs, resolveMatcherPattern, resolveRouteLink, slugify, stringifyAttrs, treatAsHtml };

package/package.json

@@ -1,15 +1,19 @@
 {
   "name": "vitepress-plugin-toolkit",
   "type": "module",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Development toolkit for vitepress plugins",
   "author": "pengzhanbo <q942450674@outlook.com> (https://github.com/pengzhanbo/)",
   "license": "MIT",
+  "homepage": "https://tuck.pengzhanbo.cn/guide/toolkit",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pengzhanbo/vitepress-tuck.git",
     "directory": "packages/plugin-toolkit"
   },
+  "bugs": {
+    "url": "https://github.com/pengzhanbo/vitepress-tuck/issues"
+  },
   "keywords": [
     "vitepress",
     "vitepress-plugin",
@@ -40,7 +44,8 @@
     "@pengzhanbo/utils": "^3.7.3",
     "@vueuse/core": "^14.3.0",
     "ansis": "^4.3.1",
-    "markdown-it-container": "^4.0.0"
+    "markdown-it-container": "^4.0.0",
+    "picomatch": "^4.0.4"
   },
   "publishConfig": {
     "access": "public",