@ruan-cat/vitepress-preset-config 2.14.0 → 3.0.0

package/dist/config.d.mts

@@ -158,19 +158,22 @@ interface CopyClaudeFilesOptions {
  */
 declare function copyClaudeFiles(options: CopyClaudeFilesOptions): void;
 
-interface AddChangelog2docOptions<T extends Record<string, any> = Record<string, any>> {
+interface AddChangelog2docOptions<T extends Record<string, unknown> = Record<string, unknown>> {
     /** 目标文件夹 */
     target: string;
     /** 被插入到md头部的数据 */
     data?: T;
 }
 /** 将变更日志添加到指定的文档目录内 并提供参数 */
-declare function addChangelog2doc<T extends Record<string, any>>(options: AddChangelog2docOptions<T>): void;
+declare function addChangelog2doc<T extends Record<string, unknown>>(options: AddChangelog2docOptions<T>): void;
 
 type VitePressSidebarOptions = Parameters<typeof generateSidebar>[0];
 /**
  * 设置自动生成侧边栏的配置
  * @see https://vitepress-sidebar.cdget.com/zhHans/guide/options
+ *
+ * 注意：在 Windows 环境下，必须使用相对路径（如 "./docs"）而不是绝对路径，
+ * 否则 vitepress-sidebar 内部的 path.join 会导致路径拼接错误。
  */
 declare function setGenerateSidebar(options?: VitePressSidebarOptions): vitepress_sidebar_types.Sidebar;
 /** 设置vitepress主配置 */

package/dist/config.mjs

@@ -1,8 +1,8 @@
 // src/config.mts
 import { defineConfig } from "vitepress";
-import { generateSidebar } from "vitepress-sidebar";
+import { generateSidebar as generateSidebar2 } from "vitepress-sidebar";
 import { vitepressDemoPlugin } from "vitepress-demo-plugin";
-import { merge as merge3, isUndefined as isUndefined3, cloneDeep as cloneDeep2 } from "lodash-es";
+import { merge as merge4, isUndefined as isUndefined3, cloneDeep as cloneDeep3 } from "lodash-es";
 
 // src/config/page-order-config.ts
 var pageOrderConfig = {
@@ -136,8 +136,9 @@ import matter from "gray-matter";
 import fs3 from "fs";
 import path3 from "path";
 import consola3 from "consola";
-function hasChangelogMd() {
-  const res = fs3.existsSync(path3.resolve(process.cwd(), "CHANGELOG.md"));
+function checkChangelogExists() {
+  const sourceDir = path3.resolve(process.cwd(), "CHANGELOG.md");
+  const res = fs3.existsSync(sourceDir);
   if (!res) {
     consola3.log("\u5F53\u524D\u9879\u76EE\u6839\u76EE\u5F55\u4E3A\uFF1A", process.cwd());
     consola3.warn("\u5F53\u524D\u9879\u76EE\u6839\u76EE\u5F55\u4E0D\u5B58\u5728 CHANGELOG.md \u6587\u4EF6");
@@ -145,7 +146,7 @@ function hasChangelogMd() {
   return res;
 }
 function copyChangelogMd(target) {
-  if (!hasChangelogMd()) {
+  if (!checkChangelogExists()) {
     return;
   }
   const source = path3.resolve(process.cwd(), "CHANGELOG.md");
@@ -154,9 +155,13 @@ function copyChangelogMd(target) {
 }
 
 // src/config/add-changelog-to-doc.ts
+function hasChangelogInRoot() {
+  const changelogPath = path4.resolve(process.cwd(), "CHANGELOG.md");
+  return fs4.existsSync(changelogPath);
+}
 function addChangelog2doc(options) {
   const { data = pageOrderConfig.changelog, target } = options;
-  if (!hasChangelogMd()) {
+  if (!hasChangelogInRoot()) {
     return;
   }
   copyChangelogMd(target);
@@ -212,31 +217,15 @@ function handlePlugins(userConfig, extraConfig) {
 }
 
 // src/config/changelog-nav.ts
-import consola5 from "consola";
+import consola6 from "consola";
 import { isUndefined } from "lodash-es";
-import { printFormat } from "@ruan-cat/utils";
-function handleChangeLog(userConfig) {
-  var _a;
-  if (!hasChangelogMd()) {
-    consola5.warn(` \u672A\u627E\u5230\u53D8\u66F4\u65E5\u5FD7\u6587\u4EF6\uFF0C\u4E0D\u6DFB\u52A0\u53D8\u66F4\u65E5\u5FD7\u5BFC\u822A\u680F\u3002 `);
-    return;
-  }
-  const nav = (_a = userConfig == null ? void 0 : userConfig.themeConfig) == null ? void 0 : _a.nav;
-  if (isUndefined(nav)) {
-    consola5.error(` \u5F53\u524D\u7684\u7528\u6237\u914D\u7F6E\u4E3A\uFF1A `, userConfig);
-    throw new Error(` nav \u9ED8\u8BA4\u63D0\u4F9B\u7684\u5BFC\u822A\u680F\u914D\u7F6E\u4E3A\u7A7A\u3002\u4E0D\u7B26\u5408\u9ED8\u8BA4\u914D\u7F6E\uFF0C\u8BF7\u68C0\u67E5\u3002 `);
-  }
-  nav.push({ text: "\u66F4\u65B0\u65E5\u5FD7", link: "/CHANGELOG.md" });
-  console.log(" \u67E5\u770B\u4FA7\u8FB9\u680F\u6570\u636E ", printFormat(userConfig == null ? void 0 : userConfig.themeConfig.sidebar));
-}
 
-// src/config/prompts-nav.ts
+// src/utils/vitepress-project.ts
 import fs5 from "fs";
 import path5 from "path";
-import consola6 from "consola";
-import { isUndefined as isUndefined2, merge } from "lodash-es";
-import matter2 from "gray-matter";
+import consola5 from "consola";
 var PROMPTS_INDEX_MD_PATH = "prompts/index.md";
+var CHANGELOG_MD_FILENAME = "CHANGELOG.md";
 function getProjectRootFromArgs() {
   const args = process.argv;
   const vitepressIndex = args.findIndex((arg) => arg.includes("vitepress"));
@@ -254,36 +243,60 @@ function getProjectRootFromArgs() {
       }
       continue;
     }
-    return path5.resolve(process.cwd(), arg);
+    let inputPath = path5.resolve(process.cwd(), arg);
+    let currentDir = inputPath;
+    const root = path5.parse(currentDir).root;
+    while (currentDir !== root) {
+      if (fs5.existsSync(path5.join(currentDir, ".vitepress"))) {
+        consola5.log("\u4ECE\u547D\u4EE4\u884C\u53C2\u6570\u83B7\u53D6\u5230 VitePress \u9879\u76EE\u6839\u76EE\u5F55\uFF1A", currentDir);
+        return currentDir;
+      }
+      currentDir = path5.dirname(currentDir);
+    }
+    if (fs5.existsSync(path5.join(root, ".vitepress"))) {
+      consola5.log("\u4ECE\u547D\u4EE4\u884C\u53C2\u6570\u83B7\u53D6\u5230 VitePress \u9879\u76EE\u6839\u76EE\u5F55\uFF1A", root);
+      return root;
+    }
+    return null;
   }
   return null;
 }
-function getVitepressProjectRoot() {
-  const projectRootFromArgs = getProjectRootFromArgs();
-  if (projectRootFromArgs) {
-    const vitepressDir2 = path5.join(projectRootFromArgs, ".vitepress");
-    if (fs5.existsSync(vitepressDir2)) {
-      consola6.log("\u4ECE\u547D\u4EE4\u884C\u53C2\u6570\u83B7\u53D6\u5230 VitePress \u9879\u76EE\u6839\u76EE\u5F55\uFF1A", projectRootFromArgs);
-      return projectRootFromArgs;
-    }
-  }
-  let currentDir = process.cwd();
-  const root = path5.parse(currentDir).root;
+function findProjectRootFromDir(startDir) {
+  const root = path5.parse(startDir).root;
+  let currentDir = startDir;
   while (currentDir !== root) {
-    const vitepressDir2 = path5.join(currentDir, ".vitepress");
-    if (fs5.existsSync(vitepressDir2)) {
-      consola6.log("\u901A\u8FC7\u5411\u4E0A\u67E5\u627E\u83B7\u53D6\u5230 VitePress \u9879\u76EE\u6839\u76EE\u5F55\uFF1A", currentDir);
+    const vitepressDir = path5.join(currentDir, ".vitepress");
+    if (fs5.existsSync(vitepressDir)) {
       return currentDir;
     }
     currentDir = path5.dirname(currentDir);
   }
-  const vitepressDir = path5.join(root, ".vitepress");
-  if (fs5.existsSync(vitepressDir)) {
-    consola6.log("\u5728\u6587\u4EF6\u7CFB\u7EDF\u6839\u76EE\u5F55\u627E\u5230 VitePress \u9879\u76EE\u6839\u76EE\u5F55\uFF1A", root);
+  const rootVitepressDir = path5.join(root, ".vitepress");
+  if (fs5.existsSync(rootVitepressDir)) {
     return root;
   }
+  return null;
+}
+function getVitepressProjectRoot() {
+  const projectRootFromArgs = getProjectRootFromArgs();
+  if (projectRootFromArgs) {
+    const foundRoot = findProjectRootFromDir(projectRootFromArgs);
+    if (foundRoot) {
+      consola5.log("\u4ECE\u547D\u4EE4\u884C\u53C2\u6570\u83B7\u53D6\u5230 VitePress \u9879\u76EE\u6839\u76EE\u5F55\uFF1A", foundRoot);
+      return foundRoot;
+    }
+  }
+  const foundFromCwd = findProjectRootFromDir(process.cwd());
+  if (foundFromCwd) {
+    consola5.log("\u901A\u8FC7\u5F53\u524D\u5DE5\u4F5C\u76EE\u5F55\u83B7\u53D6\u5230 VitePress \u9879\u76EE\u6839\u76EE\u5F55\uFF1A", foundFromCwd);
+    return foundFromCwd;
+  }
+  if (projectRootFromArgs) {
+    consola5.warn("\u672A\u627E\u5230 .vitepress \u76EE\u5F55\uFF0C\u56DE\u9000\u5230\u547D\u4EE4\u884C\u53C2\u6570\u8DEF\u5F84\uFF1A", projectRootFromArgs);
+    return projectRootFromArgs;
+  }
   const fallbackDir = process.cwd();
-  consola6.warn("\u672A\u627E\u5230 .vitepress \u76EE\u5F55\uFF0C\u56DE\u9000\u5230\u5F53\u524D\u5DE5\u4F5C\u76EE\u5F55\uFF1A", fallbackDir);
+  consola5.warn("\u672A\u627E\u5230 .vitepress \u76EE\u5F55\uFF0C\u56DE\u9000\u5230\u5F53\u524D\u5DE5\u4F5C\u76EE\u5F55\uFF1A", fallbackDir);
   return fallbackDir;
 }
 function getVitepressSourceDirectory(userConfig) {
@@ -291,67 +304,98 @@ function getVitepressSourceDirectory(userConfig) {
   const srcDir = userConfig.srcDir;
   if (srcDir) {
     const sourceDirectory = path5.resolve(projectRoot, srcDir);
-    consola6.log("\u4ECE\u914D\u7F6E\u4E2D\u83B7\u53D6\u5230 srcDir:", srcDir);
-    consola6.log("VitePress \u6E90\u76EE\u5F55\u4E3A\uFF1A", sourceDirectory);
+    consola5.log("\u4ECE\u914D\u7F6E\u4E2D\u83B7\u53D6\u5230 srcDir:", srcDir);
+    consola5.log("VitePress \u6E90\u76EE\u5F55\u4E3A\uFF1A", sourceDirectory);
     return sourceDirectory;
   }
-  consola6.log("\u914D\u7F6E\u4E2D\u672A\u6307\u5B9A srcDir\uFF0C\u6E90\u76EE\u5F55\u7B49\u4E8E\u9879\u76EE\u6839\u76EE\u5F55\uFF1A", projectRoot);
+  consola5.log("\u914D\u7F6E\u4E2D\u672A\u6307\u5B9A srcDir\uFF0C\u6E90\u76EE\u5F55\u7B49\u4E8E\u9879\u76EE\u6839\u76EE\u5F55\uFF1A", projectRoot);
   return projectRoot;
 }
 function hasPromptsIndexMd(userConfig) {
   const sourceDir = getVitepressSourceDirectory(userConfig);
   const res = fs5.existsSync(path5.resolve(sourceDir, PROMPTS_INDEX_MD_PATH));
   if (!res) {
-    consola6.log("\u5F53\u524D\u9879\u76EE\u7684vitepress\u6E90\u76EE\u5F55\u4E3A\uFF1A", sourceDir);
-    consola6.warn(`\u5F53\u524D\u9879\u76EE\u7684vitepress\u6E90\u76EE\u5F55\u4E0D\u5B58\u5728 ${PROMPTS_INDEX_MD_PATH} \u6587\u4EF6`);
+    consola5.log("\u5F53\u524D\u9879\u76EE\u7684 vitepress \u6E90\u76EE\u5F55\u4E3A\uFF1A", sourceDir);
+    consola5.warn(`\u5F53\u524D\u9879\u76EE\u7684 vitepress \u6E90\u76EE\u5F55\u4E0D\u5B58\u5728 ${PROMPTS_INDEX_MD_PATH} \u6587\u4EF6`);
+  }
+  return res;
+}
+function hasChangelogMd(userConfig) {
+  const sourceDir = getVitepressSourceDirectory(userConfig);
+  const res = fs5.existsSync(path5.resolve(sourceDir, CHANGELOG_MD_FILENAME));
+  if (!res) {
+    consola5.log("\u5F53\u524D\u9879\u76EE\u7684 vitepress \u6E90\u76EE\u5F55\u4E3A\uFF1A", sourceDir);
+    consola5.warn(`\u5F53\u524D\u9879\u76EE\u7684 vitepress \u6E90\u76EE\u5F55\u4E0D\u5B58\u5728 ${CHANGELOG_MD_FILENAME} \u6587\u4EF6`);
   }
   return res;
 }
+
+// src/config/changelog-nav.ts
+function handleChangeLog(userConfig) {
+  var _a;
+  if (!hasChangelogMd(userConfig)) {
+    consola6.warn(` \u672A\u627E\u5230\u53D8\u66F4\u65E5\u5FD7\u6587\u4EF6\uFF0C\u4E0D\u6DFB\u52A0\u53D8\u66F4\u65E5\u5FD7\u5BFC\u822A\u680F\u3002 `);
+    return;
+  }
+  const nav = (_a = userConfig == null ? void 0 : userConfig.themeConfig) == null ? void 0 : _a.nav;
+  if (isUndefined(nav)) {
+    consola6.error(` \u5F53\u524D\u7684\u7528\u6237\u914D\u7F6E\u4E3A\uFF1A `, userConfig);
+    throw new Error(` nav \u9ED8\u8BA4\u63D0\u4F9B\u7684\u5BFC\u822A\u680F\u914D\u7F6E\u4E3A\u7A7A\u3002\u4E0D\u7B26\u5408\u9ED8\u8BA4\u914D\u7F6E\uFF0C\u8BF7\u68C0\u67E5\u3002 `);
+  }
+  nav.push({ text: "\u66F4\u65B0\u65E5\u5FD7", link: "/CHANGELOG.md" });
+}
+
+// src/config/prompts-nav.ts
+import fs6 from "fs";
+import path6 from "path";
+import consola7 from "consola";
+import { isUndefined as isUndefined2, merge } from "lodash-es";
+import matter2 from "gray-matter";
 function writeYaml2PromptsIndexMd(userConfig, data) {
   const newData = data ?? pageOrderConfig.prompts;
   const sourceDir = getVitepressSourceDirectory(userConfig);
-  const mdPath = path5.resolve(sourceDir, PROMPTS_INDEX_MD_PATH);
+  const mdPath = path6.resolve(sourceDir, PROMPTS_INDEX_MD_PATH);
   try {
     let fileContent = "";
     let existingData = {};
-    if (fs5.existsSync(mdPath)) {
-      fileContent = fs5.readFileSync(mdPath, "utf-8");
+    if (fs6.existsSync(mdPath)) {
+      fileContent = fs6.readFileSync(mdPath, "utf-8");
       const parsed = matter2(fileContent);
       if (parsed.data && Object.keys(parsed.data).length > 0) {
         existingData = parsed.data;
-        consola6.log("\u68C0\u6D4B\u5230\u5DF2\u6709 YAML frontmatter\uFF0C\u5C06\u8FDB\u884C\u6570\u636E\u5408\u5E76");
+        consola7.log("\u68C0\u6D4B\u5230\u5DF2\u6709 YAML frontmatter\uFF0C\u5C06\u8FDB\u884C\u6570\u636E\u5408\u5E76");
       } else {
-        consola6.log("\u6587\u4EF6\u5B58\u5728\u4F46\u6CA1\u6709 YAML frontmatter\uFF0C\u5C06\u5199\u5165\u65B0\u7684 frontmatter");
+        consola7.log("\u6587\u4EF6\u5B58\u5728\u4F46\u6CA1\u6709 YAML frontmatter\uFF0C\u5C06\u5199\u5165\u65B0\u7684 frontmatter");
       }
       const mergedData = merge({}, existingData, newData);
       const newContent = matter2.stringify(parsed.content, mergedData);
-      fs5.writeFileSync(mdPath, newContent, "utf-8");
-      consola6.success(`\u5DF2\u5C06YAML\u6570\u636E\u5199\u5165\u5230 ${mdPath}`);
+      fs6.writeFileSync(mdPath, newContent, "utf-8");
+      consola7.success(`\u5DF2\u5C06YAML\u6570\u636E\u5199\u5165\u5230 ${mdPath}`);
     } else {
-      consola6.warn(`\u6587\u4EF6 ${mdPath} \u4E0D\u5B58\u5728\uFF0C\u5C06\u521B\u5EFA\u65B0\u6587\u4EF6`);
-      const dir = path5.dirname(mdPath);
-      if (!fs5.existsSync(dir)) {
-        fs5.mkdirSync(dir, { recursive: true });
+      consola7.warn(`\u6587\u4EF6 ${mdPath} \u4E0D\u5B58\u5728\uFF0C\u5C06\u521B\u5EFA\u65B0\u6587\u4EF6`);
+      const dir = path6.dirname(mdPath);
+      if (!fs6.existsSync(dir)) {
+        fs6.mkdirSync(dir, { recursive: true });
       }
       const newContent = matter2.stringify("", newData);
-      fs5.writeFileSync(mdPath, newContent, "utf-8");
-      consola6.success(`\u5DF2\u521B\u5EFA\u6587\u4EF6\u5E76\u5199\u5165YAML\u6570\u636E\u5230 ${mdPath}`);
+      fs6.writeFileSync(mdPath, newContent, "utf-8");
+      consola7.success(`\u5DF2\u521B\u5EFA\u6587\u4EF6\u5E76\u5199\u5165YAML\u6570\u636E\u5230 ${mdPath}`);
     }
   } catch (error) {
-    consola6.error(`\u5199\u5165 YAML \u6570\u636E\u5230 ${mdPath} \u65F6\u53D1\u751F\u9519\u8BEF:`, error);
+    consola7.error(`\u5199\u5165 YAML \u6570\u636E\u5230 ${mdPath} \u65F6\u53D1\u751F\u9519\u8BEF:`, error);
     throw error;
   }
 }
 function handlePrompts(userConfig) {
   var _a;
   if (!hasPromptsIndexMd(userConfig)) {
-    consola6.warn(` \u672A\u627E\u5230\u63D0\u793A\u8BCD\u7D22\u5F15\u6587\u4EF6\uFF0C\u4E0D\u6DFB\u52A0\u63D0\u793A\u8BCD\u5BFC\u822A\u680F\u3002 `);
+    consola7.warn(` \u672A\u627E\u5230\u63D0\u793A\u8BCD\u7D22\u5F15\u6587\u4EF6\uFF0C\u4E0D\u6DFB\u52A0\u63D0\u793A\u8BCD\u5BFC\u822A\u680F\u3002 `);
     return;
   }
   writeYaml2PromptsIndexMd(userConfig);
   const nav = (_a = userConfig == null ? void 0 : userConfig.themeConfig) == null ? void 0 : _a.nav;
   if (isUndefined2(nav)) {
-    consola6.error(` \u5F53\u524D\u7684\u7528\u6237\u914D\u7F6E\u4E3A\uFF1A `, userConfig);
+    consola7.error(` \u5F53\u524D\u7684\u7528\u6237\u914D\u7F6E\u4E3A\uFF1A `, userConfig);
     throw new Error(` nav \u9ED8\u8BA4\u63D0\u4F9B\u7684\u5BFC\u822A\u680F\u914D\u7F6E\u4E3A\u7A7A\u3002\u4E0D\u7B26\u5408\u9ED8\u8BA4\u914D\u7F6E\uFF0C\u8BF7\u68C0\u67E5\u3002 `);
   }
   nav.push({ text: "\u63D0\u793A\u8BCD", link: `/${PROMPTS_INDEX_MD_PATH}` });
@@ -425,12 +469,106 @@ function handleTeekConfig(userConfig, extraConfig) {
   userConfig.extends = defineTeekConfig(merge2({}, cloneDeep(defaultTeekConfig), teekConfig));
 }
 
+// src/config/multi-sidebar.ts
+import { generateSidebar } from "vitepress-sidebar";
+import path7 from "path";
+import consola8 from "consola";
+import { merge as merge3, cloneDeep as cloneDeep2 } from "lodash-es";
+var defaultSidebarOptions = {
+  // 侧边栏需要折叠
+  collapsed: true,
+  // 用文件的 h1 标题作为侧边栏标题
+  useTitleFromFileHeading: true,
+  // 用index文件的标题作为折叠栏的标题
+  useFolderTitleFromIndexFile: true,
+  // 折叠栏链接到index文件
+  useFolderLinkFromIndexFile: true,
+  // 用order字段做菜单排序
+  sortMenusByFrontmatterOrder: true,
+  // 不使用名称排序
+  sortMenusByName: false,
+  useFolderLinkFromSameNameSubFile: true,
+  // 不输出调试信息了
+  debugPrint: false
+};
+function getMergeSidebarOptions(options) {
+  return merge3({}, cloneDeep2(defaultSidebarOptions), options ?? {});
+}
+function getSourceDirRelativePathFromCwd(userConfig) {
+  const projectRoot = getVitepressProjectRoot();
+  const sourceDir = getVitepressSourceDirectory(userConfig);
+  const relativePath = path7.relative(process.cwd(), sourceDir);
+  consola8.log("\u9879\u76EE\u6839\u76EE\u5F55:", projectRoot);
+  consola8.log("\u6E90\u76EE\u5F55:", sourceDir);
+  consola8.log("cwd:", process.cwd());
+  consola8.log("\u6E90\u76EE\u5F55\u76F8\u5BF9\u4E8E cwd \u7684\u8DEF\u5F84:", relativePath);
+  if (!relativePath || relativePath.startsWith("..")) {
+    return ".";
+  }
+  return relativePath.replace(/\\/g, "/");
+}
+function prefixSidebarLinks(items, prefix) {
+  return items.map((item) => {
+    const newItem = { ...item };
+    if (newItem.link && typeof newItem.link === "string") {
+      const link = newItem.link.startsWith("/") ? newItem.link : `/${newItem.link}`;
+      newItem.link = `${prefix}${link}`;
+    }
+    if (Array.isArray(newItem.items)) {
+      newItem.items = prefixSidebarLinks(newItem.items, prefix);
+    }
+    return newItem;
+  });
+}
+function setupMultiSidebar(userConfig) {
+  const hasPrompts = hasPromptsIndexMd(userConfig);
+  const hasChangelog = hasChangelogMd(userConfig);
+  if (!hasPrompts && !hasChangelog) {
+    consola8.log("\u672A\u68C0\u6D4B\u5230 prompts \u76EE\u5F55\u6216 CHANGELOG.md\uFF0C\u4E0D\u9700\u8981\u591A\u4FA7\u8FB9\u680F");
+    return;
+  }
+  const themeConfig = userConfig.themeConfig;
+  const extraSidebars = {};
+  if (hasPrompts) {
+    const sourceDirRelativePathFromCwd = getSourceDirRelativePathFromCwd(userConfig);
+    const promptsFullPath = sourceDirRelativePathFromCwd === "." ? "prompts" : `${sourceDirRelativePathFromCwd}/prompts`;
+    consola8.log("promptsFullPath:", promptsFullPath);
+    const promptsSidebar = generateSidebar(
+      getMergeSidebarOptions({
+        documentRootPath: promptsFullPath
+      })
+    );
+    extraSidebars["/prompts/"] = Array.isArray(promptsSidebar) ? prefixSidebarLinks(promptsSidebar, "/prompts") : promptsSidebar;
+  }
+  if (hasChangelog) {
+    extraSidebars["/CHANGELOG"] = [];
+  }
+  let businessSidebar = themeConfig.sidebar;
+  Object.defineProperty(themeConfig, "sidebar", {
+    configurable: true,
+    enumerable: true,
+    get() {
+      const result = { ...extraSidebars };
+      if (Array.isArray(businessSidebar)) {
+        result["/"] = businessSidebar;
+      } else if (typeof businessSidebar === "object" && businessSidebar !== null) {
+        Object.assign(result, businessSidebar);
+      }
+      return result;
+    },
+    set(value) {
+      businessSidebar = value;
+    }
+  });
+  consola8.success("\u591A\u4FA7\u8FB9\u680F defineProperty \u62E6\u622A\u5DF2\u8BBE\u7F6E");
+}
+
 // src/config.mts
 import { transformerTwoslash } from "@shikijs/vitepress-twoslash";
 import { copyOrDownloadAsMarkdownButtons } from "vitepress-plugin-llms";
 import { MermaidPlugin } from "@leelaa/vitepress-plugin-extended";
 import { defineTeekConfig as defineTeekConfig2 } from "vitepress-theme-teek/config";
-var defaultSidebarOptions = {
+var defaultSidebarOptions2 = {
   // documentRootPath: "./src",
   // 侧边栏需要折叠
   collapsed: true,
@@ -455,11 +593,15 @@ var defaultSidebarOptions = {
   // 不输出调试信息了
   debugPrint: false
 };
-function getMergeSidebarOptions(options) {
-  return merge3({}, cloneDeep2(defaultSidebarOptions), isUndefined3(options) ? {} : options);
+function getMergeSidebarOptions2(options) {
+  return merge4({}, cloneDeep3(defaultSidebarOptions2), isUndefined3(options) ? {} : options);
 }
 function setGenerateSidebar(options) {
-  return generateSidebar(getMergeSidebarOptions(options));
+  const merged = getMergeSidebarOptions2(options);
+  if (!Array.isArray(merged)) {
+    merged.excludeByGlobPattern = [...merged.excludeByGlobPattern ?? [], "**/prompts/**", "**/CHANGELOG.md"];
+  }
+  return generateSidebar2(merged);
 }
 var defaultUserConfig = {
   /**
@@ -481,8 +623,8 @@ var defaultUserConfig = {
       label: "\u672C\u9875\u76EE\u5F55",
       level: "deep"
     },
-    // 自动化侧边栏
-    sidebar: setGenerateSidebar(),
+    // 自动化侧边栏（多侧边栏）
+    // sidebar 在 setUserConfig 中动态生成
     socialLinks: [{ icon: "github", link: "https://github.com/ruan-cat" }],
     editLink: {
       pattern: "https://github.com/ruan-cat/monorepo/blob/dev/packages/vitepress-preset-config/src/docs/please-reset-themeConfig-editLink.md",
@@ -534,11 +676,12 @@ var defaultUserConfig = {
   }
 };
 function setUserConfig(config, extraConfig) {
-  const resUserConfig = merge3({}, cloneDeep2(defaultUserConfig), isUndefined3(config) ? {} : config);
+  const resUserConfig = merge4({}, cloneDeep3(defaultUserConfig), isUndefined3(config) ? {} : config);
   handlePrompts(resUserConfig);
   handleChangeLog(resUserConfig);
   handlePlugins(resUserConfig, extraConfig);
   handleTeekConfig(resUserConfig, extraConfig);
+  setupMultiSidebar(resUserConfig);
   return resUserConfig;
 }
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ruan-cat/vitepress-preset-config",
-  "version": "2.14.0",
+  "version": "3.0.0",
   "description": "用于给大多数的vitepress项目提供一个预设的配置文件。",
   "homepage": "https://vitepress-preset.ruancat6312.top",
   "types": "./src/config.mts",

package/src/config/add-changelog-to-doc.ts

@@ -3,10 +3,10 @@ import fs from "node:fs";
 import consola from "consola";
 import matter from "gray-matter";
 
-import { copyChangelogMd, hasChangelogMd } from "../utils/copy-changelog";
+import { copyChangelogMd } from "../utils/copy-changelog";
 import { pageOrderConfig } from "./page-order-config";
 
-export interface AddChangelog2docOptions<T extends Record<string, any> = Record<string, any>> {
+export interface AddChangelog2docOptions<T extends Record<string, unknown> = Record<string, unknown>> {
 	/** 目标文件夹 */
 	target: string;
 
@@ -14,11 +14,17 @@ export interface AddChangelog2docOptions<T extends Record<string, any> = Record<
 	data?: T;
 }
 
+/** 检查项目根目录是否存在 CHANGELOG.md */
+function hasChangelogInRoot(): boolean {
+	const changelogPath = path.resolve(process.cwd(), "CHANGELOG.md");
+	return fs.existsSync(changelogPath);
+}
+
 /** 将变更日志添加到指定的文档目录内 并提供参数 */
-export function addChangelog2doc<T extends Record<string, any>>(options: AddChangelog2docOptions<T>) {
+export function addChangelog2doc<T extends Record<string, unknown>>(options: AddChangelog2docOptions<T>) {
 	const { data = pageOrderConfig.changelog, target } = options;
 
-	if (!hasChangelogMd()) {
+	if (!hasChangelogInRoot()) {
 		return;
 	}
 

package/src/config/changelog-nav.ts

@@ -3,8 +3,8 @@
 import { type UserConfig, type DefaultTheme } from "vitepress";
 import consola from "consola";
 import { isUndefined } from "lodash-es";
-import { hasChangelogMd } from "../utils/copy-changelog";
-import { printFormat } from "@ruan-cat/utils";
+
+import { hasChangelogMd } from "../utils/vitepress-project.ts";
 
 /**
  * 设置导航栏的变更日志
@@ -15,7 +15,7 @@ import { printFormat } from "@ruan-cat/utils";
  * @private 内部使用即可
  */
 export function handleChangeLog(userConfig: UserConfig<DefaultTheme.Config>) {
-	if (!hasChangelogMd()) {
+	if (!hasChangelogMd(userConfig)) {
 		consola.warn(` 未找到变更日志文件，不添加变更日志导航栏。 `);
 		return;
 	}
@@ -28,8 +28,4 @@ export function handleChangeLog(userConfig: UserConfig<DefaultTheme.Config>) {
 	}
 
 	nav.push({ text: "更新日志", link: "/CHANGELOG.md" });
-
-	// TODO: 持续完成特殊侧边栏的处理
-	// @ts-ignore
-	console.log(" 查看侧边栏数据 ", printFormat(userConfig?.themeConfig.sidebar));
 }

package/src/config/index.ts

@@ -8,3 +8,4 @@ export * from "./plugins";
 export * from "./changelog-nav";
 export * from "./prompts-nav";
 export * from "./teek";
+export * from "./multi-sidebar";

package/src/config/multi-sidebar.ts

@@ -0,0 +1,161 @@
+// 多侧边栏配置 - 使用 Object.defineProperty 拦截实现透明多侧边栏
+
+import { type UserConfig, type DefaultTheme } from "vitepress";
+import { generateSidebar } from "vitepress-sidebar";
+import path from "node:path";
+import consola from "consola";
+import { merge, cloneDeep } from "lodash-es";
+
+import {
+	getVitepressProjectRoot,
+	getVitepressSourceDirectory,
+	hasPromptsIndexMd,
+	hasChangelogMd,
+} from "../utils/vitepress-project.ts";
+
+/** 从 generateSidebar 函数参数中提取类型 */
+type VitePressSidebarOptions = Parameters<typeof generateSidebar>[0];
+
+/** 默认侧边栏配置选项 */
+export const defaultSidebarOptions: VitePressSidebarOptions = {
+	// 侧边栏需要折叠
+	collapsed: true,
+
+	// 用文件的 h1 标题作为侧边栏标题
+	useTitleFromFileHeading: true,
+
+	// 用index文件的标题作为折叠栏的标题
+	useFolderTitleFromIndexFile: true,
+
+	// 折叠栏链接到index文件
+	useFolderLinkFromIndexFile: true,
+
+	// 用order字段做菜单排序
+	sortMenusByFrontmatterOrder: true,
+
+	// 不使用名称排序
+	sortMenusByName: false,
+
+	useFolderLinkFromSameNameSubFile: true,
+
+	// 不输出调试信息了
+	debugPrint: false,
+};
+
+/**
+ * 获取合并后的侧边栏配置
+ */
+export function getMergeSidebarOptions(options?: VitePressSidebarOptions) {
+	return merge({}, cloneDeep(defaultSidebarOptions), options ?? {});
+}
+
+/**
+ * 获取源目录相对于 process.cwd() 的路径
+ * @description 用于 vitepress-sidebar 的配置
+ */
+export function getSourceDirRelativePathFromCwd(userConfig: UserConfig<DefaultTheme.Config>): string {
+	const projectRoot = getVitepressProjectRoot();
+	const sourceDir = getVitepressSourceDirectory(userConfig);
+	const relativePath = path.relative(process.cwd(), sourceDir);
+
+	consola.log("项目根目录:", projectRoot);
+	consola.log("源目录:", sourceDir);
+	consola.log("cwd:", process.cwd());
+	consola.log("源目录相对于 cwd 的路径:", relativePath);
+
+	if (!relativePath || relativePath.startsWith("..")) {
+		return ".";
+	}
+
+	return relativePath.replace(/\\/g, "/");
+}
+
+/**
+ * 递归为侧边栏项的 link 添加路径前缀
+ * @description
+ * generateSidebar 以子目录为根扫描时，生成的 link 缺少父路径前缀。
+ * 例如扫描 prompts 目录时，link 为 "/make-dynamic-routes"，
+ * 需要补充为 "/prompts/make-dynamic-routes"。
+ */
+function prefixSidebarLinks(items: any[], prefix: string): any[] {
+	return items.map((item) => {
+		const newItem = { ...item };
+		if (newItem.link && typeof newItem.link === "string") {
+			// 处理带和不带前导斜杠的情况
+			const link = newItem.link.startsWith("/") ? newItem.link : `/${newItem.link}`;
+			newItem.link = `${prefix}${link}`;
+		}
+		if (Array.isArray(newItem.items)) {
+			newItem.items = prefixSidebarLinks(newItem.items, prefix);
+		}
+		return newItem;
+	});
+}
+
+/**
+ * 设置多侧边栏拦截
+ * @description
+ * 使用 Object.defineProperty 在 themeConfig.sidebar 上设置 getter/setter：
+ * - setter: 消费者赋值时，存储为业务侧边栏内容
+ * - getter: VitePress 读取时，返回包含 prompts/CHANGELOG 的多侧边栏对象
+ *
+ * 对消费者完全透明，无需修改任何消费者代码。
+ */
+export function setupMultiSidebar(userConfig: UserConfig<DefaultTheme.Config>): void {
+	const hasPrompts = hasPromptsIndexMd(userConfig);
+	const hasChangelog = hasChangelogMd(userConfig);
+
+	if (!hasPrompts && !hasChangelog) {
+		consola.log("未检测到 prompts 目录或 CHANGELOG.md，不需要多侧边栏");
+		return;
+	}
+
+	const themeConfig = userConfig.themeConfig!;
+
+	// 预生成额外侧边栏
+	const extraSidebars: Record<string, any> = {};
+
+	if (hasPrompts) {
+		const sourceDirRelativePathFromCwd = getSourceDirRelativePathFromCwd(userConfig);
+		const promptsFullPath =
+			sourceDirRelativePathFromCwd === "." ? "prompts" : `${sourceDirRelativePathFromCwd}/prompts`;
+
+		consola.log("promptsFullPath:", promptsFullPath);
+
+		const promptsSidebar = generateSidebar(
+			getMergeSidebarOptions({
+				documentRootPath: promptsFullPath,
+			}),
+		);
+
+		extraSidebars["/prompts/"] = Array.isArray(promptsSidebar)
+			? prefixSidebarLinks(promptsSidebar, "/prompts")
+			: promptsSidebar;
+	}
+
+	if (hasChangelog) {
+		extraSidebars["/CHANGELOG"] = [];
+	}
+
+	// 设置 getter/setter 拦截
+	let businessSidebar: any = themeConfig.sidebar;
+
+	Object.defineProperty(themeConfig, "sidebar", {
+		configurable: true,
+		enumerable: true,
+		get() {
+			const result: Record<string, any> = { ...extraSidebars };
+			if (Array.isArray(businessSidebar)) {
+				result["/"] = businessSidebar;
+			} else if (typeof businessSidebar === "object" && businessSidebar !== null) {
+				Object.assign(result, businessSidebar);
+			}
+			return result;
+		},
+		set(value: any) {
+			businessSidebar = value;
+		},
+	});
+
+	consola.success("多侧边栏 defineProperty 拦截已设置");
+}

package/src/config/prompts-nav.ts

@@ -6,143 +6,7 @@ import { isUndefined, merge } from "lodash-es";
 import matter from "gray-matter";
 
 import { pageOrderConfig } from "./page-order-config";
-
-/** 提示词索引文件的相对路径 */
-const PROMPTS_INDEX_MD_PATH = "prompts/index.md" as const;
-
-/**
- * 从命令行参数中获取 VitePress 项目根目录
- * @description
- * 解析命令行参数，查找 vitepress dev/build 命令后的第一个路径参数
- * @private 目前仅设计为内部使用
- */
-function getProjectRootFromArgs(): string | null {
-	const args = process.argv;
-
-	// 查找 vitepress 命令的索引
-	const vitepressIndex = args.findIndex((arg) => arg.includes("vitepress"));
-
-	if (vitepressIndex === -1) {
-		return null;
-	}
-
-	// 查找 dev 或 build 命令后的第一个非选项参数（不以 - 或 -- 开头）
-	for (let i = vitepressIndex + 1; i < args.length; i++) {
-		const arg = args[i];
-
-		// 跳过命令本身（dev, build等）和选项参数
-		if (arg === "dev" || arg === "build" || arg === "serve" || arg === "preview") {
-			continue;
-		}
-
-		// 跳过选项和选项值
-		if (arg.startsWith("-")) {
-			// 如果是 --port 这样的选项，也跳过下一个值
-			if (arg.startsWith("--") && !arg.includes("=")) {
-				i++; // 跳过选项值
-			}
-			continue;
-		}
-
-		// 找到路径参数，解析为绝对路径
-		return path.resolve(process.cwd(), arg);
-	}
-
-	return null;
-}
-
-/**
- * 获得 vitepress 项目的 `项目根目录 (project root)`
- * @description
- * 检查出当前运行vitepress build 命令时，所使用的项目根目录，并对外返回该目录。
- * @see https://vitepress.dev/zh/guide/routing#root-and-source-directory
- * @private 目前仅设计为内部使用
- */
-function getVitepressProjectRoot(): string {
-	// 首先尝试从命令行参数获取
-	const projectRootFromArgs = getProjectRootFromArgs();
-	if (projectRootFromArgs) {
-		const vitepressDir = path.join(projectRootFromArgs, ".vitepress");
-		if (fs.existsSync(vitepressDir)) {
-			consola.log("从命令行参数获取到 VitePress 项目根目录：", projectRootFromArgs);
-			return projectRootFromArgs;
-		}
-	}
-
-	// 如果命令行参数没有提供或无效，尝试向上查找 .vitepress 目录
-	let currentDir = process.cwd();
-	const root = path.parse(currentDir).root;
-
-	while (currentDir !== root) {
-		const vitepressDir = path.join(currentDir, ".vitepress");
-		if (fs.existsSync(vitepressDir)) {
-			consola.log("通过向上查找获取到 VitePress 项目根目录：", currentDir);
-			return currentDir;
-		}
-		currentDir = path.dirname(currentDir);
-	}
-
-	// 检查根目录本身
-	const vitepressDir = path.join(root, ".vitepress");
-	if (fs.existsSync(vitepressDir)) {
-		consola.log("在文件系统根目录找到 VitePress 项目根目录：", root);
-		return root;
-	}
-
-	// 如果找不到 .vitepress 目录，回退到当前工作目录
-	const fallbackDir = process.cwd();
-	consola.warn("未找到 .vitepress 目录，回退到当前工作目录：", fallbackDir);
-	return fallbackDir;
-}
-
-/**
- * 获取vitepress项目的源目录
- * @description
- * 获取vitepress项目的源目录 并对外返回该目录。
- *
- * 源目录的计算规则：
- * 1. 如果配置中指定了 srcDir，则源目录 = 项目根目录 + srcDir
- * 2. 如果没有指定 srcDir，则源目录 = 项目根目录
- *
- * @param userConfig - VitePress 用户配置对象
- * @see https://vitepress.dev/zh/guide/routing#source-directory
- * @private 目前仅设计为内部使用
- */
-function getVitepressSourceDirectory(userConfig: UserConfig<DefaultTheme.Config>): string {
-	// 获取项目根目录
-	const projectRoot = getVitepressProjectRoot();
-
-	// 读取配置中的 srcDir（如果有）
-	const srcDir = (userConfig as any).srcDir as string | undefined;
-
-	// 如果配置了 srcDir，将其与项目根目录拼接；否则返回项目根目录
-	if (srcDir) {
-		const sourceDirectory = path.resolve(projectRoot, srcDir);
-		consola.log("从配置中获取到 srcDir:", srcDir);
-		consola.log("VitePress 源目录为：", sourceDirectory);
-		return sourceDirectory;
-	}
-
-	// 默认情况下，源目录等于项目根目录
-	consola.log("配置中未指定 srcDir，源目录等于项目根目录：", projectRoot);
-	return projectRoot;
-}
-
-/**
- * 检查当前运行的 `源目录` 是否存在 `prompts/index.md` 文件
- * @description
- * 检查当前运行的 `源目录` 是否存在 `prompts/index.md` 文件，并对外返回检查结果。
- * @private 目前仅设计为内部使用·
- */
-function hasPromptsIndexMd(userConfig: UserConfig<DefaultTheme.Config>) {
-	const sourceDir = getVitepressSourceDirectory(userConfig);
-	const res = fs.existsSync(path.resolve(sourceDir, PROMPTS_INDEX_MD_PATH));
-	if (!res) {
-		consola.log("当前项目的vitepress源目录为：", sourceDir);
-		consola.warn(`当前项目的vitepress源目录不存在 ${PROMPTS_INDEX_MD_PATH} 文件`);
-	}
-	return res;
-}
+import { getVitepressSourceDirectory, hasPromptsIndexMd, PROMPTS_INDEX_MD_PATH } from "../utils/vitepress-project.ts";
 
 /**
  * 将YAML数据写入到提示词索引文件内

package/src/config.mts

@@ -15,7 +15,14 @@ import { transformerTwoslash } from "@shikijs/vitepress-twoslash";
 
 import llmstxt, { copyOrDownloadAsMarkdownButtons } from "vitepress-plugin-llms";
 
-import { defaultTeekConfig, handleTeekConfig, handlePlugins, handleChangeLog, handlePrompts } from "./config/index.ts";
+import {
+	defaultTeekConfig,
+	handleTeekConfig,
+	handlePlugins,
+	handleChangeLog,
+	handlePrompts,
+	setupMultiSidebar,
+} from "./config/index.ts";
 
 /** @see https://vitepress-ext.leelaa.cn/Mermaid.html#扩展-md-插件 */
 import { MermaidPlugin } from "@leelaa/vitepress-plugin-extended";
@@ -71,9 +78,16 @@ function getMergeSidebarOptions(options?: VitePressSidebarOptions) {
 /**
  * 设置自动生成侧边栏的配置
  * @see https://vitepress-sidebar.cdget.com/zhHans/guide/options
+ *
+ * 注意：在 Windows 环境下，必须使用相对路径（如 "./docs"）而不是绝对路径，
+ * 否则 vitepress-sidebar 内部的 path.join 会导致路径拼接错误。
  */
 export function setGenerateSidebar(options?: VitePressSidebarOptions) {
-	return generateSidebar(getMergeSidebarOptions(options));
+	const merged = getMergeSidebarOptions(options);
+	if (!Array.isArray(merged)) {
+		merged.excludeByGlobPattern = [...(merged.excludeByGlobPattern ?? []), "**/prompts/**", "**/CHANGELOG.md"];
+	}
+	return generateSidebar(merged);
 }
 
 /** 默认用户配置 */
@@ -104,8 +118,8 @@ const defaultUserConfig: UserConfig<DefaultTheme.Config> = {
 			level: "deep",
 		},
 
-		// 自动化侧边栏
-		sidebar: setGenerateSidebar(),
+		// 自动化侧边栏（多侧边栏）
+		// sidebar 在 setUserConfig 中动态生成
 
 		socialLinks: [{ icon: "github", link: "https://github.com/ruan-cat" }],
 
@@ -193,5 +207,8 @@ export function setUserConfig(
 	// 设置 Teek 主题配置
 	handleTeekConfig(resUserConfig, extraConfig);
 
+	// 设置多侧边栏拦截
+	setupMultiSidebar(resUserConfig);
+
 	return resUserConfig;
 }

package/src/utils/copy-changelog.ts

@@ -2,9 +2,14 @@ import fs from "node:fs";
 import path from "node:path";
 import consola from "consola";
 
-/** 检查当前运行的根目录 是否存在 CHANGELOG.md 文件 */
-export function hasChangelogMd() {
-	const res = fs.existsSync(path.resolve(process.cwd(), "CHANGELOG.md"));
+/**
+ * 检查当前运行的根目录是否存在 CHANGELOG.md 文件
+ * @description
+ * 此函数检查的是项目根目录（process.cwd()），而非 VitePress 的 source directory
+ */
+function checkChangelogExists(): boolean {
+	const sourceDir = path.resolve(process.cwd(), "CHANGELOG.md");
+	const res = fs.existsSync(sourceDir);
 	if (!res) {
 		consola.log("当前项目根目录为：", process.cwd());
 		consola.warn("当前项目根目录不存在 CHANGELOG.md 文件");
@@ -16,9 +21,10 @@ export function hasChangelogMd() {
  * 将 CHANGELOG.md 文件移动到指定要求的位置内
  * @description
  * 该函数相当于实现 `cpx CHANGELOG.md docs` 命令
+ * @param target - 目标文件夹
  */
-export function copyChangelogMd(/** 目标文件夹 */ target: string) {
-	if (!hasChangelogMd()) {
+export function copyChangelogMd(target: string) {
+	if (!checkChangelogExists()) {
 		return;
 	}
 

package/src/utils/vitepress-project.ts

@@ -0,0 +1,196 @@
+/**
+ * VitePress 项目工具函数
+ * @description 提供 VitePress 项目相关的公共工具函数，用于获取项目根目录、源目录等
+ */
+
+import { type UserConfig, type DefaultTheme } from "vitepress";
+import fs from "node:fs";
+import path from "node:path";
+import consola from "consola";
+
+/** 提示词索引文件的相对路径 */
+export const PROMPTS_INDEX_MD_PATH = "prompts/index.md" as const;
+
+/** CHANGELOG.md 文件名 */
+export const CHANGELOG_MD_FILENAME = "CHANGELOG.md" as const;
+
+/**
+ * 从命令行参数中获取 VitePress 项目根目录
+ * @description
+ * 解析命令行参数，查找 vitepress dev/build 命令后的第一个路径参数
+ * 返回项目根目录（.vitepress 所在目录），而非源目录
+ *
+ * 支持的场景：
+ * 1. vitepress dev - 使用当前目录
+ * 2. vitepress dev docs - docs 是源目录，项目根目录在父目录
+ * 3. vitepress dev src/docs - src/docs 是源目录，项目根目录需要向上查找
+ */
+export function getProjectRootFromArgs(): string | null {
+	const args = process.argv;
+	const vitepressIndex = args.findIndex((arg) => arg.includes("vitepress"));
+
+	if (vitepressIndex === -1) {
+		return null;
+	}
+
+	for (let i = vitepressIndex + 1; i < args.length; i++) {
+		const arg = args[i];
+
+		// 跳过命令关键字
+		if (arg === "dev" || arg === "build" || arg === "serve" || arg === "preview") {
+			continue;
+		}
+
+		// 跳过选项参数
+		if (arg.startsWith("-")) {
+			if (arg.startsWith("--") && !arg.includes("=")) {
+				i++; // 跳过选项值
+			}
+			continue;
+		}
+
+		// 解析传入的路径（可能是源目录或项目根目录）
+		let inputPath = path.resolve(process.cwd(), arg);
+
+		// 向上查找直到找到 .vitepress 目录或到达根目录
+		let currentDir = inputPath;
+		const root = path.parse(currentDir).root;
+
+		while (currentDir !== root) {
+			if (fs.existsSync(path.join(currentDir, ".vitepress"))) {
+				consola.log("从命令行参数获取到 VitePress 项目根目录：", currentDir);
+				return currentDir;
+			}
+			currentDir = path.dirname(currentDir);
+		}
+
+		// 检查根目录本身
+		if (fs.existsSync(path.join(root, ".vitepress"))) {
+			consola.log("从命令行参数获取到 VitePress 项目根目录：", root);
+			return root;
+		}
+
+		// 找不到，返回 null
+		return null;
+	}
+
+	return null;
+}
+
+/**
+ * 从指定目录向上查找 VitePress 项目根目录
+ * @description 递归向上查找包含 .vitepress 目录的目录
+ */
+function findProjectRootFromDir(startDir: string): string | null {
+	const root = path.parse(startDir).root;
+	let currentDir = startDir;
+
+	while (currentDir !== root) {
+		const vitepressDir = path.join(currentDir, ".vitepress");
+		if (fs.existsSync(vitepressDir)) {
+			return currentDir;
+		}
+		currentDir = path.dirname(currentDir);
+	}
+
+	// 检查根目录本身
+	const rootVitepressDir = path.join(root, ".vitepress");
+	if (fs.existsSync(rootVitepressDir)) {
+		return root;
+	}
+
+	return null;
+}
+
+/**
+ * 获得 vitepress 项目的 `项目根目录 (project root)`
+ * @description
+ * 检查出当前运行 vitepress build 命令时，所使用的项目根目录，并对外返回该目录。
+ * @see https://vitepress.dev/zh/guide/routing#root-and-source-directory
+ */
+export function getVitepressProjectRoot(): string {
+	// 首先尝试从命令行参数提供的路径开始查找
+	const projectRootFromArgs = getProjectRootFromArgs();
+	if (projectRootFromArgs) {
+		const foundRoot = findProjectRootFromDir(projectRootFromArgs);
+		if (foundRoot) {
+			consola.log("从命令行参数获取到 VitePress 项目根目录：", foundRoot);
+			return foundRoot;
+		}
+	}
+
+	// 如果命令行参数无效，使用当前工作目录查找
+	const foundFromCwd = findProjectRootFromDir(process.cwd());
+	if (foundFromCwd) {
+		consola.log("通过当前工作目录获取到 VitePress 项目根目录：", foundFromCwd);
+		return foundFromCwd;
+	}
+
+	// 如果找不到 .vitepress 目录，回退到命令行参数提供的路径（如果存在）
+	if (projectRootFromArgs) {
+		consola.warn("未找到 .vitepress 目录，回退到命令行参数路径：", projectRootFromArgs);
+		return projectRootFromArgs;
+	}
+
+	// 最后回退到当前工作目录
+	const fallbackDir = process.cwd();
+	consola.warn("未找到 .vitepress 目录，回退到当前工作目录：", fallbackDir);
+	return fallbackDir;
+}
+
+/**
+ * 获取 vitepress 项目的源目录
+ * @description
+ * 获取 vitepress 项目的源目录并对外返回该目录。
+ *
+ * 源目录的计算规则：
+ * 1. 如果配置中指定了 srcDir，则源目录 = 项目根目录 + srcDir
+ * 2. 如果没有指定 srcDir，则源目录 = 项目根目录
+ *
+ * @param userConfig - VitePress 用户配置对象
+ * @see https://vitepress.dev/zh/guide/routing#source-directory
+ */
+export function getVitepressSourceDirectory(userConfig: UserConfig<DefaultTheme.Config>): string {
+	const projectRoot = getVitepressProjectRoot();
+	const srcDir = (userConfig as Record<string, unknown>).srcDir as string | undefined;
+
+	if (srcDir) {
+		const sourceDirectory = path.resolve(projectRoot, srcDir);
+		consola.log("从配置中获取到 srcDir:", srcDir);
+		consola.log("VitePress 源目录为：", sourceDirectory);
+		return sourceDirectory;
+	}
+
+	consola.log("配置中未指定 srcDir，源目录等于项目根目录：", projectRoot);
+	return projectRoot;
+}
+
+/**
+ * 检查源目录是否存在 prompts/index.md 文件
+ * @description
+ * 检查当前文档的运行目录内是否存在 prompts/index.md 文件
+ */
+export function hasPromptsIndexMd(userConfig: UserConfig<DefaultTheme.Config>): boolean {
+	const sourceDir = getVitepressSourceDirectory(userConfig);
+	const res = fs.existsSync(path.resolve(sourceDir, PROMPTS_INDEX_MD_PATH));
+	if (!res) {
+		consola.log("当前项目的 vitepress 源目录为：", sourceDir);
+		consola.warn(`当前项目的 vitepress 源目录不存在 ${PROMPTS_INDEX_MD_PATH} 文件`);
+	}
+	return res;
+}
+
+/**
+ * 检查源目录是否存在 CHANGELOG.md 文件
+ * @description
+ * 检查当前文档的运行目录内是否存在 CHANGELOG.md 文件
+ */
+export function hasChangelogMd(userConfig: UserConfig<DefaultTheme.Config>): boolean {
+	const sourceDir = getVitepressSourceDirectory(userConfig);
+	const res = fs.existsSync(path.resolve(sourceDir, CHANGELOG_MD_FILENAME));
+	if (!res) {
+		consola.log("当前项目的 vitepress 源目录为：", sourceDir);
+		consola.warn(`当前项目的 vitepress 源目录不存在 ${CHANGELOG_MD_FILENAME} 文件`);
+	}
+	return res;
+}