vitepress-plugin-file-tree 0.3.0 → 0.4.0

package/dist/client/browser/index.d.ts

@@ -1,13 +1,16 @@
+import { InjectionKey, Ref } from "vue";
 import { EnhanceAppContext } from "vitepress/client";
 
 //#region src/client/VPFileTree.vue.d.ts
 type __VLS_Props$1 = {
-  title?: string;
-  text: string;
+  /** Optional title displayed above the file tree. / 显示在文件树上方的可选标题。 */title?: string; /** URL-encoded plain-text representation of the file tree for the copy button. / 文件树的 URL 编码纯文本，供复制按钮使用。 */
+  text?: string;
 };
-declare var __VLS_6: {};
+declare var __VLS_1$1: {}, __VLS_8: {};
 type __VLS_Slots$1 = {} & {
-  default?: (props: typeof __VLS_6) => any;
+  title?: (props: typeof __VLS_1$1) => any;
+} & {
+  default?: (props: typeof __VLS_8) => any;
 };
 declare const __VLS_base$1: import("vue").DefineComponent<__VLS_Props$1, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props$1> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 declare const __VLS_export$1: __VLS_WithSlots$1<typeof __VLS_base$1, __VLS_Slots$1>;
@@ -20,12 +23,12 @@ type __VLS_WithSlots$1<T, S> = T & {
 //#endregion
 //#region src/client/VPFileTreeNode.vue.d.ts
 type __VLS_Props = {
-  type: 'file' | 'folder';
-  filename: string;
-  level: number;
-  diff?: 'add' | 'remove';
-  expanded?: boolean;
-  focus?: boolean;
+  /** Node type, either a folder or a file. / 节点类型，文件夹或文件。 */type: 'file' | 'folder'; /** Display name of the file or folder. / 文件或文件夹的显示名称。 */
+  filename: string; /** Indentation depth level, used for visual offset. / 缩进层级，用于视觉偏移。 */
+  level: number; /** Diff marker indicating the node was added or removed. / 差异标记，表示节点为新增或删除。 */
+  diff?: 'add' | 'remove'; /** Whether a folder node is expanded by default. / 文件夹节点是否默认展开。 */
+  expanded?: boolean; /** Whether this node is visually highlighted as focused. / 是否作为聚焦节点高亮显示。 */
+  focus?: boolean; /** Full file path used for active state matching. / 用于匹配激活状态的完整文件路径。 */
   filepath?: string;
 };
 declare var __VLS_1: {}, __VLS_3: {};
@@ -43,9 +46,36 @@ type __VLS_WithSlots<T, S> = T & {
   };
 };
 //#endregion
+//#region src/client/constants.d.ts
+/**
+ * File tree node click event
+ *
+ * 文件树节点点击事件
+ */
+declare const ON_NODE_CLICK: InjectionKey<(filename: string, type: 'folder' | 'file') => void>;
+/**
+ * Active file tree node
+ *
+ * 当前激活的文件树节点
+ */
+declare const ACTIVE_NODE_KEY: InjectionKey<Ref<string>>;
+//#endregion
 //#region src/client/index.d.ts
+/**
+ * Register file tree components globally during VitePress app enhancement.
+ *
+ * 在 VitePress 应用增强阶段全局注册文件树组件。
+ *
+ * Called automatically by the `virtual:enhance-app` module when the plugin
+ * is loaded via `vitepress-tuck`'s `defineConfig`. Registers `VPFileTree`
+ * and `VPFileTreeNode` as global Vue components so they can be used in
+ * markdown-rendered HTML without explicit imports.
+ *
+ * @param ctx - VitePress enhance app context / VitePress 应用增强上下文
+ * @param ctx.app - The VitePress Vue app instance / VitePress 的 Vue 应用实例
+ */
 declare function enhanceAppWithFileTree({
   app
 }: EnhanceAppContext): void;
 //#endregion
-export { _default as VPFileTree, _default$1 as VPFileTreeNode, enhanceAppWithFileTree };
+export { ACTIVE_NODE_KEY, ON_NODE_CLICK, _default as VPFileTree, _default$1 as VPFileTreeNode, enhanceAppWithFileTree };

package/dist/client/browser/index.js

@@ -1,12 +1,12 @@
 import "../style.css";
-import { computed, createCommentVNode, createElementBlock, createElementVNode, createVNode, defineComponent, inject, mergeProps, normalizeClass, openBlock, ref, renderSlot, toDisplayString, unref, vShow, withDirectives } from "vue";
+import { computed, createBlock, createCommentVNode, createElementBlock, createElementVNode, defineComponent, inject, mergeProps, normalizeClass, openBlock, ref, renderSlot, toDisplayString, unref, vShow, withDirectives } from "vue";
 import { VPCopyButton } from "vitepress-plugin-toolkit/client";
 //#region src/client/VPFileTree.vue
-const _hoisted_1$1 = { class: "vp-file-tree has-copy" };
-const _hoisted_2$1 = {
+const _hoisted_1$1 = {
 	key: 0,
 	class: "vp-file-tree-title"
 };
+const _hoisted_2$1 = { class: "file-tree-content" };
 const _sfc_main = /*@__PURE__*/ defineComponent({
 	__name: "VPFileTree",
 	props: {
@@ -14,17 +14,34 @@ const _sfc_main = /*@__PURE__*/ defineComponent({
 		text: {}
 	},
 	setup(__props) {
-		const content = computed(() => decodeURIComponent(__props.text));
+		const content = computed(() => __props.text ? decodeURIComponent(__props.text) : "");
 		return (_ctx, _cache) => {
-			return openBlock(), createElementBlock("div", _hoisted_1$1, [
-				__props.title ? (openBlock(), createElementBlock("p", _hoisted_2$1, toDisplayString(__props.title), 1)) : createCommentVNode("v-if", true),
-				createVNode(unref(VPCopyButton), { text: content.value }, null, 8, ["text"]),
-				renderSlot(_ctx.$slots, "default")
-			]);
+			return openBlock(), createElementBlock("div", { class: normalizeClass(["vp-file-tree", { "has-copy": __props.text }]) }, [
+				renderSlot(_ctx.$slots, "title", {}, () => [__props.title ? (openBlock(), createElementBlock("p", _hoisted_1$1, toDisplayString(__props.title), 1)) : createCommentVNode("v-if", true)]),
+				__props.text ? (openBlock(), createBlock(unref(VPCopyButton), {
+					key: 0,
+					text: content.value
+				}, null, 8, ["text"])) : createCommentVNode("v-if", true),
+				createElementVNode("div", _hoisted_2$1, [renderSlot(_ctx.$slots, "default")])
+			], 2);
 		};
 	}
 });
 //#endregion
+//#region src/client/constants.ts
+/**
+* File tree node click event
+*
+* 文件树节点点击事件
+*/
+const ON_NODE_CLICK = Symbol(import.meta.env.DEV ? "on-file-tree-node-click" : "");
+/**
+* Active file tree node
+*
+* 当前激活的文件树节点
+*/
+const ACTIVE_NODE_KEY = Symbol(import.meta.env.DEV ? "active-file-tree-node" : "");
+//#endregion
 //#region src/client/VPFileTreeNode.vue
 const _hoisted_1 = { class: "vp-file-tree-node" };
 const _hoisted_2 = ["data-filename"];
@@ -48,13 +65,33 @@ const _sfc_main$1 = /*@__PURE__*/ defineComponent({
 		filepath: {}
 	},
 	setup(__props) {
-		const activeFileTreeNode = inject("active-file-tree-node", ref(""));
-		const onNodeClick = inject("on-file-tree-node-click", () => {});
+		const activeFileTreeNode = inject(ACTIVE_NODE_KEY, ref(""));
+		const onNodeClick = inject(ON_NODE_CLICK, () => {});
 		const active = ref(__props.expanded);
+		/**
+		* Notify the parent of a node click event via the injected callback.
+		*
+		* 通过注入的回调通知父组件节点点击事件。
+		*
+		* Ellipsis placeholders (`…` or `...`) are ignored to avoid triggering
+		* selection on empty folder markers.
+		*/
 		function nodeClick() {
 			if (__props.filename === "…" || __props.filename === "...") return;
 			onNodeClick(__props.filepath || __props.filename, __props.type);
 		}
+		/**
+		* Handle click events on the node, toggling folder expansion or firing
+		* the node click callback for files.
+		*
+		* 处理节点的点击事件，切换文件夹展开状态或触发文件节点的点击回调。
+		*
+		* For folders, clicks on the comment area are ignored so that inline
+		* comments remain interactive. For files, the click callback fires
+		* directly.
+		*
+		* @param ev - Native mouse event / 原生鼠标事件
+		*/
 		function toggle(ev) {
 			if (__props.type === "folder") {
 				if (!ev.target.matches(".comment, .comment *")) {
@@ -92,9 +129,22 @@ const _sfc_main$1 = /*@__PURE__*/ defineComponent({
 });
 //#endregion
 //#region src/client/index.ts
+/**
+* Register file tree components globally during VitePress app enhancement.
+*
+* 在 VitePress 应用增强阶段全局注册文件树组件。
+*
+* Called automatically by the `virtual:enhance-app` module when the plugin
+* is loaded via `vitepress-tuck`'s `defineConfig`. Registers `VPFileTree`
+* and `VPFileTreeNode` as global Vue components so they can be used in
+* markdown-rendered HTML without explicit imports.
+*
+* @param ctx - VitePress enhance app context / VitePress 应用增强上下文
+* @param ctx.app - The VitePress Vue app instance / VitePress 的 Vue 应用实例
+*/
 function enhanceAppWithFileTree({ app }) {
-	app.component("VPFileTree", _sfc_main);
-	app.component("VPFileTreeNode", _sfc_main$1);
+	if (!app._context.components.VPFileTree) app.component("VPFileTree", _sfc_main);
+	if (!app._context.components.VPFileTreeNode) app.component("VPFileTreeNode", _sfc_main$1);
 }
 //#endregion
-export { _sfc_main as VPFileTree, _sfc_main$1 as VPFileTreeNode, enhanceAppWithFileTree };
+export { ACTIVE_NODE_KEY, ON_NODE_CLICK, _sfc_main as VPFileTree, _sfc_main$1 as VPFileTreeNode, enhanceAppWithFileTree };

package/dist/client/ssr/index.d.ts

@@ -1,13 +1,16 @@
+import { InjectionKey, Ref } from "vue";
 import { EnhanceAppContext } from "vitepress/client";
 
 //#region src/client/VPFileTree.vue.d.ts
 type __VLS_Props$1 = {
-  title?: string;
-  text: string;
+  /** Optional title displayed above the file tree. / 显示在文件树上方的可选标题。 */title?: string; /** URL-encoded plain-text representation of the file tree for the copy button. / 文件树的 URL 编码纯文本，供复制按钮使用。 */
+  text?: string;
 };
-declare var __VLS_6: {};
+declare var __VLS_1$1: {}, __VLS_8: {};
 type __VLS_Slots$1 = {} & {
-  default?: (props: typeof __VLS_6) => any;
+  title?: (props: typeof __VLS_1$1) => any;
+} & {
+  default?: (props: typeof __VLS_8) => any;
 };
 declare const __VLS_base$1: import("vue").DefineComponent<__VLS_Props$1, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props$1> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 declare const __VLS_export$1: __VLS_WithSlots$1<typeof __VLS_base$1, __VLS_Slots$1>;
@@ -20,12 +23,12 @@ type __VLS_WithSlots$1<T, S> = T & {
 //#endregion
 //#region src/client/VPFileTreeNode.vue.d.ts
 type __VLS_Props = {
-  type: 'file' | 'folder';
-  filename: string;
-  level: number;
-  diff?: 'add' | 'remove';
-  expanded?: boolean;
-  focus?: boolean;
+  /** Node type, either a folder or a file. / 节点类型，文件夹或文件。 */type: 'file' | 'folder'; /** Display name of the file or folder. / 文件或文件夹的显示名称。 */
+  filename: string; /** Indentation depth level, used for visual offset. / 缩进层级，用于视觉偏移。 */
+  level: number; /** Diff marker indicating the node was added or removed. / 差异标记，表示节点为新增或删除。 */
+  diff?: 'add' | 'remove'; /** Whether a folder node is expanded by default. / 文件夹节点是否默认展开。 */
+  expanded?: boolean; /** Whether this node is visually highlighted as focused. / 是否作为聚焦节点高亮显示。 */
+  focus?: boolean; /** Full file path used for active state matching. / 用于匹配激活状态的完整文件路径。 */
   filepath?: string;
 };
 declare var __VLS_1: {}, __VLS_3: {};
@@ -43,9 +46,36 @@ type __VLS_WithSlots<T, S> = T & {
   };
 };
 //#endregion
+//#region src/client/constants.d.ts
+/**
+ * File tree node click event
+ *
+ * 文件树节点点击事件
+ */
+declare const ON_NODE_CLICK: InjectionKey<(filename: string, type: 'folder' | 'file') => void>;
+/**
+ * Active file tree node
+ *
+ * 当前激活的文件树节点
+ */
+declare const ACTIVE_NODE_KEY: InjectionKey<Ref<string>>;
+//#endregion
 //#region src/client/index.d.ts
+/**
+ * Register file tree components globally during VitePress app enhancement.
+ *
+ * 在 VitePress 应用增强阶段全局注册文件树组件。
+ *
+ * Called automatically by the `virtual:enhance-app` module when the plugin
+ * is loaded via `vitepress-tuck`'s `defineConfig`. Registers `VPFileTree`
+ * and `VPFileTreeNode` as global Vue components so they can be used in
+ * markdown-rendered HTML without explicit imports.
+ *
+ * @param ctx - VitePress enhance app context / VitePress 应用增强上下文
+ * @param ctx.app - The VitePress Vue app instance / VitePress 的 Vue 应用实例
+ */
 declare function enhanceAppWithFileTree({
   app
 }: EnhanceAppContext): void;
 //#endregion
-export { _default as VPFileTree, _default$1 as VPFileTreeNode, enhanceAppWithFileTree };
+export { ACTIVE_NODE_KEY, ON_NODE_CLICK, _default as VPFileTree, _default$1 as VPFileTreeNode, enhanceAppWithFileTree };

package/dist/client/ssr/index.js

@@ -10,14 +10,18 @@ const _sfc_main = /*@__PURE__*/ defineComponent({
 		text: {}
 	},
 	setup(__props) {
-		const content = computed(() => decodeURIComponent(__props.text));
+		const content = computed(() => __props.text ? decodeURIComponent(__props.text) : "");
 		return (_ctx, _push, _parent, _attrs) => {
-			_push(`<div${ssrRenderAttrs(mergeProps({ class: "vp-file-tree has-copy" }, _attrs))}>`);
-			if (__props.title) _push(`<p class="vp-file-tree-title">${ssrInterpolate(__props.title)}</p>`);
+			_push(`<div${ssrRenderAttrs(mergeProps({ class: ["vp-file-tree", { "has-copy": __props.text }] }, _attrs))}>`);
+			ssrRenderSlot(_ctx.$slots, "title", {}, () => {
+				if (__props.title) _push(`<p class="vp-file-tree-title">${ssrInterpolate(__props.title)}</p>`);
+				else _push(`<!---->`);
+			}, _push, _parent);
+			if (__props.text) _push(ssrRenderComponent(unref(VPCopyButton), { text: content.value }, null, _parent));
 			else _push(`<!---->`);
-			_push(ssrRenderComponent(unref(VPCopyButton), { text: content.value }, null, _parent));
+			_push(`<div class="file-tree-content">`);
 			ssrRenderSlot(_ctx.$slots, "default", {}, null, _push, _parent);
-			_push(`</div>`);
+			_push(`</div></div>`);
 		};
 	}
 });
@@ -28,6 +32,20 @@ _sfc_main.setup = (props, ctx) => {
 	return _sfc_setup$1 ? _sfc_setup$1(props, ctx) : void 0;
 };
 //#endregion
+//#region src/client/constants.ts
+/**
+* File tree node click event
+*
+* 文件树节点点击事件
+*/
+const ON_NODE_CLICK = Symbol(import.meta.env.DEV ? "on-file-tree-node-click" : "");
+/**
+* Active file tree node
+*
+* 当前激活的文件树节点
+*/
+const ACTIVE_NODE_KEY = Symbol(import.meta.env.DEV ? "active-file-tree-node" : "");
+//#endregion
 //#region src/client/VPFileTreeNode.vue
 const _sfc_main$1 = /*@__PURE__*/ defineComponent({
 	__name: "VPFileTreeNode",
@@ -42,13 +60,33 @@ const _sfc_main$1 = /*@__PURE__*/ defineComponent({
 		filepath: {}
 	},
 	setup(__props) {
-		const activeFileTreeNode = inject("active-file-tree-node", ref(""));
-		const onNodeClick = inject("on-file-tree-node-click", () => {});
+		const activeFileTreeNode = inject(ACTIVE_NODE_KEY, ref(""));
+		const onNodeClick = inject(ON_NODE_CLICK, () => {});
 		const active = ref(__props.expanded);
+		/**
+		* Notify the parent of a node click event via the injected callback.
+		*
+		* 通过注入的回调通知父组件节点点击事件。
+		*
+		* Ellipsis placeholders (`…` or `...`) are ignored to avoid triggering
+		* selection on empty folder markers.
+		*/
 		function nodeClick() {
 			if (__props.filename === "…" || __props.filename === "...") return;
 			onNodeClick(__props.filepath || __props.filename, __props.type);
 		}
+		/**
+		* Handle click events on the node, toggling folder expansion or firing
+		* the node click callback for files.
+		*
+		* 处理节点的点击事件，切换文件夹展开状态或触发文件节点的点击回调。
+		*
+		* For folders, clicks on the comment area are ignored so that inline
+		* comments remain interactive. For files, the click callback fires
+		* directly.
+		*
+		* @param ev - Native mouse event / 原生鼠标事件
+		*/
 		function toggle(ev) {
 			if (__props.type === "folder") {
 				if (!ev.target.matches(".comment, .comment *")) {
@@ -99,9 +137,22 @@ _sfc_main$1.setup = (props, ctx) => {
 };
 //#endregion
 //#region src/client/index.ts
+/**
+* Register file tree components globally during VitePress app enhancement.
+*
+* 在 VitePress 应用增强阶段全局注册文件树组件。
+*
+* Called automatically by the `virtual:enhance-app` module when the plugin
+* is loaded via `vitepress-tuck`'s `defineConfig`. Registers `VPFileTree`
+* and `VPFileTreeNode` as global Vue components so they can be used in
+* markdown-rendered HTML without explicit imports.
+*
+* @param ctx - VitePress enhance app context / VitePress 应用增强上下文
+* @param ctx.app - The VitePress Vue app instance / VitePress 的 Vue 应用实例
+*/
 function enhanceAppWithFileTree({ app }) {
-	app.component("VPFileTree", _sfc_main);
-	app.component("VPFileTreeNode", _sfc_main$1);
+	if (!app._context.components.VPFileTree) app.component("VPFileTree", _sfc_main);
+	if (!app._context.components.VPFileTreeNode) app.component("VPFileTreeNode", _sfc_main$1);
 }
 //#endregion
-export { _sfc_main as VPFileTree, _sfc_main$1 as VPFileTreeNode, enhanceAppWithFileTree };
+export { ACTIVE_NODE_KEY, ON_NODE_CLICK, _sfc_main as VPFileTree, _sfc_main$1 as VPFileTreeNode, enhanceAppWithFileTree };

package/dist/client/style.css

@@ -12,7 +12,6 @@
 .vp-file-tree {
   position: relative;
   max-width: 100%;
-  padding: 16px;
   overflow: auto hidden;
   font-size: 14px;
   background-color: var(--vp-file-tree-bg);
@@ -22,11 +21,10 @@
 }
 
 .vp-file-tree .vp-file-tree-title {
-  padding-block: 8px;
   padding-inline: 16px;
-  margin-block: -16px 8px;
-  margin-inline: -16px;
+  margin-block: 0;
   font-weight: bold;
+  line-height: 47px;
   color: var(--vp-c-text-1);
   border-bottom: solid 1px var(--vp-c-divider);
   transition: color 0.25s ease, border-color 0.25s ease;
@@ -36,6 +34,10 @@
   top: calc(45px + 1em) !important;
 }
 
+.vp-file-tree .file-tree-content {
+  padding: 16px;
+}
+
 .vp-file-tree .vp-file-tree-info {
   position: relative;
   display: flex;

package/dist/node/index.d.ts

@@ -1,47 +1,141 @@
 import { PluginSimple } from "markdown-it";
 
 //#region src/node/plugin.d.ts
+/**
+ * VitePress plugin for rendering file tree diagrams in markdown.
+ *
+ * VitePress 插件，用于在 markdown 中渲染文件树图。
+ *
+ * Registers the `fileTreeMarkdownPlugin` with markdown-it to parse both
+ * container syntax (`::: file-tree`) and fence syntax (` ```tree ` or
+ * ` ```file-tree `) into interactive collapsible file trees. On the client
+ * side, the `VPFileTree` and `VPFileTreeNode` Vue components are injected
+ * globally via `virtual:enhance-app`.
+ *
+ * The rendered tree supports inline comments, focus highlights, diff markers
+ * for added or removed entries, and a copy button that outputs the plain-text
+ * `tree` command representation.
+ *
+ * @example
+ * `.vitepress/config.ts`
+ * ```ts
+ * import { defineConfig } from 'vitepress-tuck'
+ * import fileTree from 'vitepress-plugin-file-tree'
+ *
+ * export default defineConfig({
+ *   plugins: [fileTree()],
+ * })
+ * ```
+ */
 declare const fileTree: (options?: unknown) => import("vitepress-tuck").VitepressPlugin;
 //#endregion
 //#region src/node/types.d.ts
 /**
- * File tree node structure
+ * File tree node structure.
+ *
+ * 文件树节点结构。
+ *
+ * Represents a single entry in the file tree. A node can be either a file or
+ * a folder, with optional metadata such as inline comments, focus highlight,
+ * expansion state, and diff markers used for before/after comparisons.
  *
- * 文件树节点结构
+ * @example
+ * ```ts
+ * const node: FileTreeNode = {
+ *   filename: 'src',
+ *   type: 'folder',
+ *   level: 0,
+ *   children: [
+ *     { filename: 'index.ts', type: 'file', level: 1, children: [] },
+ *   ],
+ * }
+ * ```
  */
 interface FileTreeNode {
+  /** Display name of the file or folder. / 文件或文件夹的显示名称。 */
   filename: string;
+  /** Optional inline comment rendered next to the filename. / 渲染在文件名旁的可选内联注释。 */
   comment?: string;
+  /** Whether this node is visually highlighted as focused. / 是否作为聚焦节点高亮显示。 */
   focus?: boolean;
+  /** Whether a folder node is expanded by default. / 文件夹节点是否默认展开。 */
   expanded?: boolean;
+  /** Node type, either a folder or a file. / 节点类型，文件夹或文件。 */
   type: 'folder' | 'file';
+  /** Diff marker indicating the node was added or removed. / 差异标记，表示节点为新增或删除。 */
   diff?: 'add' | 'remove';
+  /** Indentation depth level, starting from 0 at the root's direct children. / 缩进层级，根节点的直接子节点为 0。 */
   level: number;
+  /** Child nodes, only populated for folder nodes. / 子节点数组，仅文件夹节点会有子节点。 */
   children: FileTreeNode[];
 }
 /**
- * File tree container attributes
+ * File tree container attributes.
  *
- * 文件树容器属性
+ * 文件树容器属性。
+ *
+ * Defines the optional attributes parsed from the `::: file-tree` container
+ * syntax, used to configure the outer wrapper of the rendered file tree.
  */
 interface FileTreeAttrs {
+  /** Optional title displayed above the file tree. / 显示在文件树上方的可选标题。 */
   title?: string;
 }
 //#endregion
 //#region src/node/fileTreeToCMDText.d.ts
 /**
- * Convert file tree to command line text format
+ * Convert file tree nodes into `tree` command-style plain text.
+ *
+ * 将文件树节点转换为 `tree` 命令风格的纯文本。
+ *
+ * Produces a string representation using `├──` and `└──` branch markers with
+ * `│   ` and `    ` indentation, matching the output of the Unix `tree`
+ * command. Ellipsis placeholder children (`…`) are filtered out so empty
+ * folders render cleanly. The result is used by the copy button on the
+ * rendered file tree.
  *
- * 将文件树转换为命令行文本格式
+ * 使用 `├──` 和 `└──` 分支标记以及 `│` 和空格缩进生成字符串表示，与 Unix `tree` 命令的输出一致。
+ * 省略号占位符子项（`…`）会被过滤掉，使得空文件夹显示整洁。该结果用于渲染文件树上的复制按钮。
  *
- * @param nodes - File tree nodes / 文件树节点
- * @param prefix - Line prefix / 行前缀
- * @returns CMD text / CMD 文本
+ * @param nodes - File tree nodes to convert / 要转换的文件树节点数组
+ * @param prefix - Line prefix for recursive indentation / 递归缩进使用的行前缀
+ * @returns CMD-style text representation / CMD 风格的文本表示
+ *
+ * @example
+ * ```ts
+ * const nodes = [
+ *   { filename: 'src', type: 'folder', level: 0, children: [
+ *     { filename: 'index.ts', type: 'file', level: 1, children: [] },
+ *   ]},
+ * ]
+ * fileTreeToCMDText(nodes)
+ * // .
+ * // └── src
+ * //     └── index.ts
+ * ```
  */
 declare function fileTreeToCMDText(nodes: FileTreeNode[], prefix?: string): string;
 //#endregion
 //#region src/node/markdown.d.ts
 /**
+ * markdown-it plugin for rendering file tree diagrams.
+ *
+ * 用于渲染文件树图的 markdown-it 插件。
+ *
+ * Supports two syntaxes:
+ * - Container syntax: `::: file-tree` blocks with `- filename` indented entries
+ * - Fence syntax: ` ```tree ` or ` ```file-tree ` code blocks with `tree` command output
+ *
+ * The plugin converts the parsed tree structure into nested `<VPFileTreeNode>`
+ * components wrapped by a `<VPFileTree>` container, with a URL-encoded
+ * plain-text representation for the copy button.
+ *
+ * 支持两种语法：
+ * - 容器语法：`::: file-tree` 块，其中包含以 `- 文件名` 缩进的条目
+ * - 围栏语法：` ```tree ` 或 ` ```file-tree ` 代码块，其中包含 `tree` 命令的输出
+ *
+ * 该插件将解析后的树结构转换为由 `<VPFileTree>` 容器包裹的嵌套 `<VPFileTreeNode>` 组件，并附带一个 URL 编码的纯文本表示，用于复制按钮。
+ *
  * @example
  * ```ts
  * import { fileTreeMarkdownPlugin } from 'vitepress-plugin-file-tree'
@@ -61,10 +155,27 @@ declare const fileTreeMarkdownPlugin: PluginSimple;
 /**
  * Parse the content from the `::: file-tree` container into a node tree structure.
  *
- * 从 `::: file-tree` 容器中解析内容为节点树结构
+ * 从 `::: file-tree` 容器中解析内容为节点树结构。
+ *
+ * Accepts indented list-style text where each entry starts with `- ` and
+ * indentation is measured in two-space increments. The first line's leading
+ * whitespace is stripped to normalize the root level. Each entry is passed
+ * to `parseNodeInfo` to extract the filename, comment, type, and other
+ * metadata.
  *
  * @param content - Raw file tree text content / 文件树的原始文本内容
  * @returns File tree node array / 文件树节点数组
+ *
+ * @example
+ * ```ts
+ * const content = `
+ * - src/  # source folder
+ *   - index.ts
+ *   - utils.ts
+ * - package.json
+ * `
+ * parseContentWithContainer(content)
+ * ```
  */
 declare function parseContentWithContainer(content: string): FileTreeNode[];
 //#endregion
@@ -72,6 +183,8 @@ declare function parseContentWithContainer(content: string): FileTreeNode[];
 /**
  * Parse `tree` command output format into a structured file tree node array.
  *
+ * 将 `tree` 命令行输出格式解析为结构化的文件树节点数组。
+ *
  * Converts text like:
  * ```
  * .
@@ -82,9 +195,10 @@ declare function parseContentWithContainer(content: string): FileTreeNode[];
  * ```
  *
  * into a `FileTreeNode[]` tree structure, with support for inline comments
- * (text after `#`) on each entry.
- *
- * 将 `tree` 命令行输出格式解析为结构化的文件树节点数组
+ * (text after `#`) on each entry. The leading root marker line (`.`) is
+ * skipped if present. Indentation depth is derived from the 4-character
+ * prefix segments, and any parent node that gains children is automatically
+ * promoted to the `folder` type.
  *
  * @param content - Raw `tree` command output text / `tree` 命令输出的原始文本
  * @returns Structured file tree node array / 结构化的文件树节点数组
@@ -93,12 +207,31 @@ declare function parseContentWithFence(content: string): FileTreeNode[];
 //#endregion
 //#region src/node/parseNodeInfo.d.ts
 /**
- * Parse single node info string, extract filename, comment, type, etc.
+ * Parse a single node info string, extracting filename, comment, type, and
+ * other metadata.
+ *
+ * 解析单个节点的 info 字符串，提取文件名、注释、类型等属性。
  *
- * 解析单个节点的 info 字符串，提取文件名、注释、类型等属性
+ * Recognizes the following syntax within the info string:
+ * - `++filename` — marks the node as a diff addition
+ * - `--filename` — marks the node as a diff removal
+ * - `**filename**` — highlights the node as focused
+ * - `filename # comment` — attaches an inline comment after `#`
+ * - `filename/` — treats the entry as a folder (trailing slash removed)
  *
  * @param info - Node description string / 节点描述字符串
- * @returns File tree node props / 文件树节点属性
+ * @returns File tree node properties excluding `children` and `level` / 文件树节点属性（不含 `children` 和 `level`）
+ *
+ * @example
+ * ```ts
+ * parseNodeInfo('src/  # source folder')
+ * // { filename: 'src', comment: '# source folder', focus: false,
+ * //   expanded: false, type: 'folder', diff: undefined }
+ *
+ * parseNodeInfo('**index.ts**')
+ * // { filename: 'index.ts', comment: '', focus: true,
+ * //   expanded: true, type: 'file', diff: undefined }
+ * ```
  */
 declare function parseNodeInfo(info: string): Omit<FileTreeNode, 'children' | 'level'>;
 //#endregion

package/dist/node/index.js

@@ -3,13 +3,35 @@ import { createContainerSyntaxPlugin, stringifyAttrs } from "vitepress-plugin-to
 import { removeTrailingSlash } from "@pengzhanbo/utils";
 //#region src/node/fileTreeToCMDText.ts
 /**
-* Convert file tree to command line text format
+* Convert file tree nodes into `tree` command-style plain text.
 *
-* 将文件树转换为命令行文本格式
+* 将文件树节点转换为 `tree` 命令风格的纯文本。
 *
-* @param nodes - File tree nodes / 文件树节点
-* @param prefix - Line prefix / 行前缀
-* @returns CMD text / CMD 文本
+* Produces a string representation using `├──` and `└──` branch markers with
+* `│   ` and `    ` indentation, matching the output of the Unix `tree`
+* command. Ellipsis placeholder children (`…`) are filtered out so empty
+* folders render cleanly. The result is used by the copy button on the
+* rendered file tree.
+*
+* 使用 `├──` 和 `└──` 分支标记以及 `│` 和空格缩进生成字符串表示，与 Unix `tree` 命令的输出一致。
+* 省略号占位符子项（`…`）会被过滤掉，使得空文件夹显示整洁。该结果用于渲染文件树上的复制按钮。
+*
+* @param nodes - File tree nodes to convert / 要转换的文件树节点数组
+* @param prefix - Line prefix for recursive indentation / 递归缩进使用的行前缀
+* @returns CMD-style text representation / CMD 风格的文本表示
+*
+* @example
+* ```ts
+* const nodes = [
+*   { filename: 'src', type: 'folder', level: 0, children: [
+*     { filename: 'index.ts', type: 'file', level: 1, children: [] },
+*   ]},
+* ]
+* fileTreeToCMDText(nodes)
+* // .
+* // └── src
+* //     └── index.ts
+* ```
 */
 function fileTreeToCMDText(nodes, prefix = "") {
 	let content = prefix ? "" : ".\n";
@@ -24,18 +46,40 @@ function fileTreeToCMDText(nodes, prefix = "") {
 //#endregion
 //#region src/node/parseNodeInfo.ts
 /**
-* Regex for focus marker
+* Regular expression for the focus marker `**filename**`.
 *
-* 高亮标记正则
+* 聚焦标记 `**filename**` 的正则表达式。
+*
+* A filename wrapped in double asterisks is highlighted as a focused node.
+* The marker may be followed by a space and an inline comment.
 */
 const RE_FOCUS = /^\*\*(.*)\*\*(?:$|\s+)/;
 /**
-* Parse single node info string, extract filename, comment, type, etc.
+* Parse a single node info string, extracting filename, comment, type, and
+* other metadata.
+*
+* 解析单个节点的 info 字符串，提取文件名、注释、类型等属性。
 *
-* 解析单个节点的 info 字符串，提取文件名、注释、类型等属性
+* Recognizes the following syntax within the info string:
+* - `++filename` — marks the node as a diff addition
+* - `--filename` — marks the node as a diff removal
+* - `**filename**` — highlights the node as focused
+* - `filename # comment` — attaches an inline comment after `#`
+* - `filename/` — treats the entry as a folder (trailing slash removed)
 *
 * @param info - Node description string / 节点描述字符串
-* @returns File tree node props / 文件树节点属性
+* @returns File tree node properties excluding `children` and `level` / 文件树节点属性（不含 `children` 和 `level`）
+*
+* @example
+* ```ts
+* parseNodeInfo('src/  # source folder')
+* // { filename: 'src', comment: '# source folder', focus: false,
+* //   expanded: false, type: 'folder', diff: undefined }
+*
+* parseNodeInfo('**index.ts**')
+* // { filename: 'index.ts', comment: '', focus: true,
+* //   expanded: true, type: 'file', diff: undefined }
+* ```
 */
 function parseNodeInfo(info) {
 	let filename = "";
@@ -81,10 +125,27 @@ function parseNodeInfo(info) {
 /**
 * Parse the content from the `::: file-tree` container into a node tree structure.
 *
-* 从 `::: file-tree` 容器中解析内容为节点树结构
+* 从 `::: file-tree` 容器中解析内容为节点树结构。
+*
+* Accepts indented list-style text where each entry starts with `- ` and
+* indentation is measured in two-space increments. The first line's leading
+* whitespace is stripped to normalize the root level. Each entry is passed
+* to `parseNodeInfo` to extract the filename, comment, type, and other
+* metadata.
 *
 * @param content - Raw file tree text content / 文件树的原始文本内容
 * @returns File tree node array / 文件树节点数组
+*
+* @example
+* ```ts
+* const content = `
+* - src/  # source folder
+*   - index.ts
+*   - utils.ts
+* - package.json
+* `
+* parseContentWithContainer(content)
+* ```
 */
 function parseContentWithContainer(content) {
 	const root = {
@@ -114,7 +175,9 @@ function parseContentWithContainer(content) {
 //#endregion
 //#region src/node/parseContentWithFence.ts
 /**
-* Regex for matching a single line of `tree` command output.
+* Regular expression for matching a single line of `tree` command output.
+*
+* 匹配 `tree` 命令输出的单行正则。
 *
 * Matches lines like:
 *   ├── filename
@@ -125,13 +188,13 @@ function parseContentWithContainer(content) {
 * - Group 1: prefix segments, each is either `│   ` (has next sibling) or `    ` (last sibling)
 * - Group 2: branch marker, either `├── ` (non-last) or `└── ` (last)
 * - Group 3: the filename with optional comment
-*
-* 匹配 `tree` 命令输出的单行正则
 */
 const TREE_LINE_RE = /^((?:│ {3}| {4})*)([├└]── )(.+)$/u;
 /**
 * Parse `tree` command output format into a structured file tree node array.
 *
+* 将 `tree` 命令行输出格式解析为结构化的文件树节点数组。
+*
 * Converts text like:
 * ```
 * .
@@ -142,9 +205,10 @@ const TREE_LINE_RE = /^((?:│ {3}| {4})*)([├└]── )(.+)$/u;
 * ```
 *
 * into a `FileTreeNode[]` tree structure, with support for inline comments
-* (text after `#`) on each entry.
-*
-* 将 `tree` 命令行输出格式解析为结构化的文件树节点数组
+* (text after `#`) on each entry. The leading root marker line (`.`) is
+* skipped if present. Indentation depth is derived from the 4-character
+* prefix segments, and any parent node that gains children is automatically
+* promoted to the `folder` type.
 *
 * @param content - Raw `tree` command output text / `tree` 命令输出的原始文本
 * @returns Structured file tree node array / 结构化的文件树节点数组
@@ -179,6 +243,24 @@ function parseContentWithFence(content) {
 //#endregion
 //#region src/node/markdown.ts
 /**
+* markdown-it plugin for rendering file tree diagrams.
+*
+* 用于渲染文件树图的 markdown-it 插件。
+*
+* Supports two syntaxes:
+* - Container syntax: `::: file-tree` blocks with `- filename` indented entries
+* - Fence syntax: ` ```tree ` or ` ```file-tree ` code blocks with `tree` command output
+*
+* The plugin converts the parsed tree structure into nested `<VPFileTreeNode>`
+* components wrapped by a `<VPFileTree>` container, with a URL-encoded
+* plain-text representation for the copy button.
+*
+* 支持两种语法：
+* - 容器语法：`::: file-tree` 块，其中包含以 `- 文件名` 缩进的条目
+* - 围栏语法：` ```tree ` 或 ` ```file-tree ` 代码块，其中包含 `tree` 命令的输出
+*
+* 该插件将解析后的树结构转换为由 `<VPFileTree>` 容器包裹的嵌套 `<VPFileTreeNode>` 组件，并附带一个 URL 编码的纯文本表示，用于复制按钮。
+*
 * @example
 * ```ts
 * import { fileTreeMarkdownPlugin } from 'vitepress-plugin-file-tree'
@@ -194,9 +276,20 @@ function parseContentWithFence(content) {
 */
 const fileTreeMarkdownPlugin = (md) => {
 	/**
-	* Recursively render file tree nodes
+	* Recursively render file tree nodes into nested `<VPFileTreeNode>` markup.
+	*
+	* 递归地将文件树节点渲染为嵌套的 `<VPFileTreeNode>` 标记。
+	*
+	* Empty folders automatically receive an ellipsis placeholder child so the
+	* folder icon is displayed correctly. Inline comments are rendered through
+	* `md.renderInline` and passed via the `#comment` slot.
 	*
-	* 递归渲染文件树节点
+	* 空文件夹会自动获得一个省略号占位符子项，以便正确显示文件夹图标。
+	* 内联注释通过 `md.renderInline` 渲染，并通过 `#comment` 插槽传递。
+	*
+	* @param nodes - File tree nodes to render / 要渲染的文件树节点数组
+	* @param meta - Container-level attributes / 容器级属性
+	* @returns Rendered HTML string of nested nodes / 嵌套节点的 HTML 字符串
 	*/
 	const renderFileTree = (nodes, meta) => nodes.map((node) => {
 		const { level, children, filename, comment, focus, expanded, type, diff } = node;
@@ -242,6 +335,32 @@ ${renderedComment}${children.length > 0 ? renderFileTree(children, meta) : ""}
 };
 //#endregion
 //#region src/node/plugin.ts
+/**
+* VitePress plugin for rendering file tree diagrams in markdown.
+*
+* VitePress 插件，用于在 markdown 中渲染文件树图。
+*
+* Registers the `fileTreeMarkdownPlugin` with markdown-it to parse both
+* container syntax (`::: file-tree`) and fence syntax (` ```tree ` or
+* ` ```file-tree `) into interactive collapsible file trees. On the client
+* side, the `VPFileTree` and `VPFileTreeNode` Vue components are injected
+* globally via `virtual:enhance-app`.
+*
+* The rendered tree supports inline comments, focus highlights, diff markers
+* for added or removed entries, and a copy button that outputs the plain-text
+* `tree` command representation.
+*
+* @example
+* `.vitepress/config.ts`
+* ```ts
+* import { defineConfig } from 'vitepress-tuck'
+* import fileTree from 'vitepress-plugin-file-tree'
+*
+* export default defineConfig({
+*   plugins: [fileTree()],
+* })
+* ```
+*/
 const fileTree = definePlugin(() => ({
 	name: "vitepress-plugin-file-tree",
 	client: { enhance: "enhanceAppWithFileTree" },
@@ -255,6 +374,14 @@ const fileTree = definePlugin(() => ({
 }));
 //#endregion
 //#region src/node/index.ts
+/**
+* Entry point for the `vitepress-plugin-file-tree` package.
+*
+* `vitepress-plugin-file-tree` 插件的入口模块。
+*
+* Re-exports all node-side utilities, the markdown-it plugin, parsing helpers,
+* and the main `fileTree` plugin definition as the default export.
+*/
 var node_default = fileTree;
 //#endregion
 export { node_default as default, fileTree, fileTreeMarkdownPlugin, fileTreeToCMDText, parseContentWithContainer, parseContentWithFence, parseNodeInfo };

package/package.json

@@ -1,15 +1,19 @@
 {
   "name": "vitepress-plugin-file-tree",
   "type": "module",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Render file tree structure in your VitePress site.",
   "author": "pengzhanbo <q942450674@outlook.com> (https://github.com/pengzhanbo/)",
   "license": "MIT",
+  "homepage": "https://tuck.pengzhanbo.cn/plugins/file-tree",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pengzhanbo/vitepress-tuck.git",
     "directory": "packages/plugin-file-tree"
   },
+  "bugs": {
+    "url": "https://github.com/pengzhanbo/vitepress-tuck/issues"
+  },
   "keywords": [
     "vitepress",
     "vitepress-plugin",
@@ -35,8 +39,8 @@
   "dependencies": {
     "@pengzhanbo/utils": "^3.7.3",
     "@vueuse/core": "^14.3.0",
-    "vitepress-plugin-toolkit": "0.3.0",
-    "vitepress-tuck": "0.3.0"
+    "vitepress-plugin-toolkit": "0.4.0",
+    "vitepress-tuck": "0.4.0"
   },
   "publishConfig": {
     "access": "public",