vitepress-allyouneed 0.3.6 → 0.3.7

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 本项目遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/);版本号遵循 [SemVer](https://semver.org/lang/zh-CN/)。
 
+## [0.3.6] - 2026-05-20
+
+针对用户反馈"Perspectives 有时不加载 / sidebar 有时错"的间歇性问题做了系统排查,5 个真 bug。
+
+### Fixed
+- **Perspectives 在 `locales.root.themeConfig` 配置下消失**:VitePress 1.6 渲染时浅 merge `themeConfig` 与 `siteData.locales[k]?.themeConfig` —— locale 整个**替换**顶层 nav/sidebar。wrapper 之前 `if (lang === 'root') continue` 跳过 root,导致用户用标准 i18n 写法 `locales: { root: { themeConfig: { nav: [...] }}}` 时,顶层 Perspectives 被 root 的(未注入)nav 覆盖。现在所有 locale(含 root)都过 inject。
+- **dev 模式下新增 / 删除文件后 sidebar/nav 不更新**:wrapper 只在 config time 跑一次 scan + 生成 sidebar,后续 hot-update 只刷新 Vite 插件的 index(用于 wikilink / asset / vault-data.json)。结构变化静默吞掉。现在 `handleHotUpdate` 检测到 `.md` 文件 add / remove 时 `console.warn` 提示"重启 dev 服务器才能反映 sidebar/nav 变化"。
+- **空 `themeConfig.sidebar = {}` 或部分 per-path 配置下 Perspectives 在根路径消失**:`injectViewsSidebar` 老逻辑 `for (Object.keys(sidebar))` 在空 object 上跑 0 次,Perspectives 没塞任何路径;用户在 `/` 或非匹配路径访问时看不到。现在显式给 `/` key 兜底一份。
+- **`themeConfig.nav` 是 function 时被替换为 `[Perspectives]`**:VitePress nav 支持 function(动态 / locale-aware)。老 `Array.isArray(fn) ? [...fn] : []` 把 function 错判成"无 nav",推 Perspectives 后用单元素数组覆盖用户函数。现在 `typeof === 'function'` 时 wrap 一层,运行时调用用户 fn + 追加 Perspectives;用户 fn 抛错时容错只返 Perspectives 并 warn。
+- **perspective fallback sidebar 含标题为 `/` 的死项**:`buildPerspectivesFallbackSidebar` 过滤 `p !== base`,但 base 是 `/sub/` 时永远不等于 `/` → `/` 进 topPaths → seg 为空 → 渲染为 `text: '/'` 的死项。现在显式排除 `'/'` + 双保险 `if (!seg) continue`。
+
+### Tests
+- 新增 `tests/v036-perspective-locale.test.ts`,覆盖以上 5 个 bug。
+
 ## [0.3.5] - 2026-05-20
 
 零配置导航更顺手:不写 `index.md` 也能从导航 / sidebar / 用户手写 wikilink 进到一个文件夹;默认 index 模板换成"文件管理器风格"(子文件夹在上、文件在下)。

package/dist/index.cjs

@@ -2424,15 +2424,28 @@ function viteAllYouNeed(userOptions = {}) {
     },
     handleHotUpdate(ctx) {
       if (!index) return;
+      const isMd = /\.(md|markdown)$/i.test(ctx.file);
+      const wasIndexed = isMd && index.files.has(ctx.file);
+      let structuralChange = null;
       try {
         const stat = import_node_fs7.default.statSync(ctx.file);
         if (stat.isFile()) {
           updateFile(index, ctx.file, resolved);
+          const isNowIndexed = index.files.has(ctx.file);
+          if (!wasIndexed && isNowIndexed) structuralChange = "add";
         } else if (!import_node_fs7.default.existsSync(ctx.file)) {
           removeFile(index, ctx.file, resolved);
+          if (wasIndexed) structuralChange = "remove";
         }
       } catch {
         removeFile(index, ctx.file, resolved);
+        if (wasIndexed) structuralChange = "remove";
+      }
+      if (structuralChange) {
+        const rel = toPosix(ctx.file).replace(toPosix(resolved.srcDir) + "/", "");
+        console.warn(
+          `vitepress-allyouneed: \u68C0\u6D4B\u5230\u7ED3\u6784\u53D8\u5316(${structuralChange === "add" ? "\u65B0\u589E" : "\u5220\u9664"} ${rel}),sidebar/nav \u5DF2\u88AB\u70D8\u7119\u5230 VitePress \u914D\u7F6E\u4E2D,**\u91CD\u542F dev \u670D\u52A1\u5668**\u624D\u80FD\u53CD\u6620;wikilink/asset \u5DF2\u5B9E\u65F6\u5237\u65B0\u3002`
+        );
       }
       if (resolved.modules.views) {
         try {
@@ -2546,6 +2559,11 @@ function injectViewsSidebar(sidebar, options) {
           arr.push(group);
         }
       }
+      if (!sidebar["/"]) {
+        sidebar["/"] = [group];
+      } else if (!sidebar["/"].some((it) => it.text === group.text)) {
+        sidebar["/"].push(group);
+      }
     }
     const prefix = options.views.urlPrefix ? options.views.urlPrefix.replace(/^\/+|\/+$/g, "") : "";
     if (prefix) {
@@ -2567,10 +2585,11 @@ function buildPerspectivesFallbackSidebar(allSidebars, group, base, viewsPrefix)
   const out = [{ text: "Home", link: "/" }];
   const persSuffix = `/${viewsPrefix}/`;
   const topPaths = Object.keys(allSidebars).filter(
-    (p) => p !== base && !p.endsWith(persSuffix)
+    (p) => p !== "/" && p !== base && !p.endsWith(persSuffix)
   );
   for (const p of topPaths) {
     const seg = p.replace(/^\/|\/$/g, "").split("/").filter(Boolean).pop() ?? p;
+    if (!seg) continue;
     const text = seg.charAt(0).toUpperCase() + seg.slice(1);
     const b = base.endsWith("/") ? base : base + "/";
     const stripped = b !== "/" && p.startsWith(b) ? "/" + p.slice(b.length) : p;
@@ -2612,6 +2631,26 @@ function injectViewsNav(nav, options) {
       link: it.link
     }))
   };
+  if (typeof nav === "function") {
+    const userFn = nav;
+    return () => {
+      let arr2;
+      try {
+        const r = userFn();
+        arr2 = Array.isArray(r) ? [...r] : [];
+      } catch (e) {
+        console.warn(
+          "vitepress-allyouneed: themeConfig.nav \u51FD\u6570\u6267\u884C\u5931\u8D25,\u4EC5\u8FD4\u56DE Perspectives \u4E0B\u62C9\u3002",
+          e instanceof Error ? e.message : String(e)
+        );
+        arr2 = [];
+      }
+      if (!arr2.some((it) => it && it.text === navItem.text)) {
+        arr2.push(navItem);
+      }
+      return arr2;
+    };
+  }
   const arr = Array.isArray(nav) ? [...nav] : [];
   if (!arr.some((it) => it.text === navItem.text)) {
     arr.push(navItem);
@@ -3675,7 +3714,6 @@ function defineConfigWithAllYouNeed(config, pluginOptions = {}) {
     const localesForViews = config.locales;
     if (localesForViews) {
       for (const lang of Object.keys(localesForViews)) {
-        if (lang === "root") continue;
         const lc = localesForViews[lang];
         if (!lc.themeConfig) lc.themeConfig = {};
         if (lc.themeConfig.sidebar !== void 0) {