vitepress-allyouneed 0.3.4 → 0.3.7

package/CHANGELOG.md

@@ -2,6 +2,64 @@
 
 本项目遵循 [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 模板换成"文件管理器风格"(子文件夹在上、文件在下)。
+
+### Added
+
+- **`sidebarAuto.folderLinkFallback: 'first-file' | 'none'`(默认 `'first-file'`)**
+  控制"文件夹链接缺 index 时怎么办"。三处效果一致:
+  - 自动生成的 sidebar group:无 dirIndex 时,group title 链到该文件夹第一个文件;
+  - 自动生成的 nav tab:无 dirIndex 时,tab 链到第一个文件(不再 silently skip);
+  - 用户手写的 `[[folder/]]` wikilink:同样兜底到第一个文件,label 用文件夹名(不用 first file 的 basename)。
+  设为 `'none'` 退回老行为(无 link / 死链)。最常见用法:`autoFolderIndex: 'off'` + `folderLinkFallback: 'first-file'`,完全不在 vault 写 `index.md` 也能从导航走通。
+  > **注意 sidebar vs nav 的差异**:
+  > - **Sidebar group**:**空 frontmatter-only dirIndex** 是用户显式 opt-out 信号(读 frontmatter 中的 `sidebarTitle` / `sidebarCollapsed`,但 group **无 link**,只展开/折叠)。这种文件**不会**触发 first-file 兜底 —— 兜底只在**完全没有** dirIndex 文件时生效。
+  > - **Nav tab**:nav tab 没"展开/折叠"状态,空 dirIndex 不兜底就成了点不动的死 tab。所以 nav 一视同仁:空或无 dirIndex **都**走 first-file 兜底(若 `folderLinkFallback === 'first-file'`);兜底也找不到才 skip。
+  > - **`[[folder/]]` wikilink**:用户写 `[[folder/]]` 时本就期望"跳转",和 nav 同语义 —— 空 dirIndex 兜底到第一个文件。
+- **`resolveWikilink` 加同名 dirIndex 路径变体** —— `[[Themen/]]` 现在会查 `Themen/Themen.md` 当作索引(对应 `pickDirIndexes` 同名优先策略)。
+- **`[[folder/]]` 写法支持完整化**:之前 `[[Themen/]]` 由于 `target + '/index.md'` 拼出 `Themen//index.md` 双斜杠 bug,实际是死链。现在 normalize 时剥尾 `/` 并强制走 path-style 分支,变体查找正确。
+
+### Changed
+
+- **默认 `autoFolderIndex` 模板 = "Folders 在上、Files 在下"**(像文件管理器 / Tags 视图)。
+  - 段标题改成 `## Folders` + `## Files`(原 `## Sections` + `## Pages`)。
+  - 子文件夹位置:**上面**(老模板在下面)。
+  - 子文件夹标题是否可点接 `sidebarAuto.groupLink`(等同 sidebar 配置语义):
+    - `'all'`(默认):所有子文件夹标题都用 wikilink 可点
+    - `'top-level'`:仅根 `index.md` 内可点;深层 `index.md` 内为纯文字
+    - `'off'`:全部纯文字
+  - 子文件夹的"可点目的地"再走 `folderLinkFallback` 兜底,所以即使子文件夹无 index,点了也能进。
+- **`FolderIndexOptions` / `TemplateContext` 扩展**:新增 `groupLink` 字段;`TemplateContext` 新增 `isRoot` / `groupLink`。
+- **`resolveWikilink` 的 `defaultLabel`**:wasFolderForm 时(`[[folder/]]`),label 用文件夹名,而不是兜底文件的 basename。
+
+### Migration
+
+老用户若觉得新默认行为"不对路":
+```ts
+sidebarAuto: {
+  folderLinkFallback: 'none',  // 回到 v0.3.4 行为
+  autoFolderIndex: {
+    template: oldTemplate,       // 自己写模板覆盖
+  },
+}
+```
+
 ## [0.3.4] - 2026-05-20
 
 真实 Obsidian 物理笔记 vault 测试暴露的 9 个 bug + 3 个隐性问题的集中修复。

package/dist/index.cjs

@@ -661,12 +661,20 @@ function resolveWikilink(rawTarget, index, options, kind = "page", currentSource
     headingPart = target.slice(hashIdx + 1).trim();
     target = target.slice(0, hashIdx).trim();
   }
+  const wasFolderForm = /\/$/.test(target);
+  if (wasFolderForm) target = target.replace(/\/+$/, "");
   target = stripMarkdownExt(target);
-  const entry = lookupEntry(target, index, options, currentSourcePath);
+  const entry = lookupEntry(
+    target,
+    index,
+    options,
+    currentSourcePath,
+    wasFolderForm
+  );
   if (!entry) {
     return {
       url: buildDeadUrl(rawTarget, options),
-      defaultLabel: defaultLabel(target, headingPart, void 0, options),
+      defaultLabel: defaultLabel(target, headingPart, void 0, options, wasFolderForm),
       isDead: true,
       hasUnmatchedAnchor: false,
       kind
@@ -687,22 +695,25 @@ function resolveWikilink(rawTarget, index, options, kind = "page", currentSource
   }
   return {
     url,
-    defaultLabel: defaultLabel(target, headingPart, entry, options),
+    defaultLabel: defaultLabel(target, headingPart, entry, options, wasFolderForm),
     isDead: false,
     hasUnmatchedAnchor,
     target: entry,
     kind
   };
 }
-function lookupEntry(target, index, options, currentSourcePath) {
+function lookupEntry(target, index, options, currentSourcePath, forcePathStyle = false) {
   if (!target) return void 0;
-  if (target.includes("/")) {
+  if (target.includes("/") || forcePathStyle) {
+    const lastSeg = target.split("/").pop() ?? "";
     const variants = [
       target,
       target + ".md",
       target + ".markdown",
       target + "/index.md",
-      target + "/index.markdown"
+      target + "/index.markdown",
+      // 同名文件夹索引(和 pickDirIndexes 优先级 1 对齐)
+      ...lastSeg ? [target + "/" + lastSeg + ".md", target + "/" + lastSeg + ".markdown"] : []
     ];
     for (const v of variants) {
       const e = index.byRelativePath.get(v);
@@ -728,6 +739,11 @@ function lookupEntry(target, index, options, currentSourcePath) {
         }
       }
     }
+    const folderFallback = options.sidebarAuto?.folderLinkFallback ?? "first-file";
+    if (folderFallback === "first-file") {
+      const first = findFirstFileInFolder(target, index);
+      if (first) return first;
+    }
     return void 0;
   }
   const aliasKey = options.caseSensitive ? target : target.toLowerCase();
@@ -749,14 +765,31 @@ function lookupEntry(target, index, options, currentSourcePath) {
       return void 0;
   }
 }
+function findFirstFileInFolder(folderPath, index) {
+  const prefix = folderPath + "/";
+  const candidates = [];
+  for (const f of index.files.values()) {
+    if (f.relativePath.startsWith(prefix)) candidates.push(f);
+  }
+  if (candidates.length === 0) return void 0;
+  candidates.sort((a, b) => {
+    const da = a.relativePath.split("/").length;
+    const db = b.relativePath.split("/").length;
+    if (da !== db) return da - db;
+    return a.relativePath.localeCompare(b.relativePath);
+  });
+  return candidates[0];
+}
 function buildDeadUrl(rawTarget, options) {
   const safe = encodeURIComponent(stripMarkdownExt(rawTarget).split("#")[0]);
   return options.base + safe;
 }
-function defaultLabel(target, headingPart, entry, options) {
+function defaultLabel(target, headingPart, entry, options, wasFolderForm = false) {
   const lt = options.wikilinks.linkText;
   let base;
-  if (typeof lt === "function") {
+  if (wasFolderForm) {
+    base = basename(target) || target;
+  } else if (typeof lt === "function") {
     if (entry) {
       base = lt(entry, target);
     } else {
@@ -2391,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 {
@@ -2513,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) {
@@ -2534,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;
@@ -2579,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);
@@ -2761,7 +2833,8 @@ function resolveSidebarAutoOptions(user = {}) {
     groupLink: user.groupLink ?? "all",
     includePrefix: user.includePrefix,
     excludePrefixes: user.excludePrefixes ?? [],
-    foldersFirst: user.foldersFirst ?? false
+    foldersFirst: user.foldersFirst ?? false,
+    folderLinkFallback: user.folderLinkFallback ?? "first-file"
   };
 }
 function defaultItemTitle(entry, strip) {
@@ -2923,8 +2996,13 @@ function renderNode(node, opts, depth, isRoot, index, options) {
       collapsed: resolveGroupCollapsed(child.dirIndex, opts),
       items: childItems
     };
-    if (child.dirIndex && !child.dirIndexEmpty && shouldLinkGroup(opts, isRoot)) {
-      group.link = child.dirIndex.url;
+    if (shouldLinkGroup(opts, isRoot)) {
+      if (child.dirIndex && !child.dirIndexEmpty) {
+        group.link = child.dirIndex.url;
+      } else if (!child.dirIndex && opts.folderLinkFallback === "first-file") {
+        const first = findFirstPageUrl(child, opts);
+        if (first) group.link = first;
+      }
     }
     folderItems.push(group);
   }
@@ -3008,8 +3086,13 @@ function toFlatSidebar(root, opts) {
       collapsed: resolveGroupCollapsed(d.dirIndex, opts),
       items
     };
-    if (d.dirIndex && !d.dirIndexEmpty && shouldLinkGroup(opts, true)) {
-      group.link = d.dirIndex.url;
+    if (shouldLinkGroup(opts, true)) {
+      if (d.dirIndex && !d.dirIndexEmpty) {
+        group.link = d.dirIndex.url;
+      } else if (!d.dirIndex && opts.folderLinkFallback === "first-file") {
+        const first = findFirstPageUrl(d, opts);
+        if (first) group.link = first;
+      }
     }
     out.push(group);
   }
@@ -3042,7 +3125,12 @@ function toPerFolderSidebar(root, opts, options, index) {
       /* isTopLevel */
       true
     )) {
-      const firstUrl = child.dirIndex && !child.dirIndexEmpty ? child.dirIndex.url : findFirstPageUrl(child, opts);
+      let firstUrl = null;
+      if (child.dirIndex && !child.dirIndexEmpty) {
+        firstUrl = child.dirIndex.url;
+      } else if (!child.dirIndex && opts.folderLinkFallback === "first-file") {
+        firstUrl = findFirstPageUrl(child, opts);
+      }
       if (firstUrl) {
         rootItems.push({ text: labelText, link: firstUrl });
       } else {
@@ -3067,16 +3155,23 @@ function toPerFolderSidebar(root, opts, options, index) {
     );
     if (items.length === 0 && !child.dirIndex) continue;
     const sidebar = [];
-    const canLink = child.dirIndex && !child.dirIndexEmpty && shouldLinkGroup(
+    if (shouldLinkGroup(
       opts,
       /* isTopLevel */
       true
-    );
-    if (canLink) {
-      sidebar.push({
-        text: computeGroupText(child.path, child.dirIndex, opts),
-        link: child.dirIndex.url
-      });
+    )) {
+      let selfUrl = null;
+      if (child.dirIndex && !child.dirIndexEmpty) {
+        selfUrl = child.dirIndex.url;
+      } else if (!child.dirIndex && opts.folderLinkFallback === "first-file") {
+        selfUrl = findFirstPageUrl(child, opts);
+      }
+      if (selfUrl) {
+        sidebar.push({
+          text: computeGroupText(child.path, child.dirIndex, opts),
+          link: selfUrl
+        });
+      }
     }
     sidebar.push(...items);
     out[`/${key}/`] = sidebar;
@@ -3104,10 +3199,12 @@ function generateNav(index, options, autoOptions = {}) {
     let link;
     if (child.dirIndex && !child.dirIndexEmpty) {
       link = stripBase(child.dirIndex.url, base);
-    } else {
+    } else if (opts.folderLinkFallback === "first-file") {
       const first = findFirstPageUrl(child, opts);
       if (!first) continue;
       link = first;
+    } else {
+      continue;
     }
     const escapedPrefix = `/${key}/`.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
     out.push({ text, link, activeMatch: "^" + escapedPrefix });
@@ -3277,7 +3374,9 @@ function generateFolderIndexes(options, folderOpts = {}) {
       dirRelPath: dirRel,
       title: humanize2(lastSeg, strip) || "Home",
       files,
-      subDirs
+      subDirs,
+      isRoot: dirRel === "",
+      groupLink: folderOpts.groupLink ?? "all"
     };
     try {
       import_node_fs8.default.writeFileSync(target, template(ctx), "utf8");
@@ -3358,6 +3457,7 @@ function humanize2(name, stripNumeric) {
 }
 function defaultTemplate(ctx) {
   const prefix = ctx.dirRelPath === "" ? "" : `${ctx.dirRelPath}/`;
+  const subDirLinkable = subFolderClickable(ctx.groupLink, ctx.isRoot);
   const lines = [];
   lines.push("---");
   lines.push(`title: ${ctx.title}`);
@@ -3368,15 +3468,19 @@ function defaultTemplate(ctx) {
   lines.push(`# ${ctx.title}`);
   lines.push("");
   if (ctx.subDirs.length > 0) {
-    lines.push("## Sections");
+    lines.push("## Folders");
     lines.push("");
     for (const d of ctx.subDirs) {
-      lines.push(`- [[${prefix}${d.name}/|${d.title}]]`);
+      if (subDirLinkable) {
+        lines.push(`- [[${prefix}${d.name}/|${d.title}]]`);
+      } else {
+        lines.push(`- ${d.title}`);
+      }
     }
     lines.push("");
   }
   if (ctx.files.length > 0) {
-    lines.push("## Pages");
+    lines.push("## Files");
     lines.push("");
     for (const f of ctx.files) {
       lines.push(`- [[${prefix}${f.relPath}|${f.title}]]`);
@@ -3385,6 +3489,11 @@ function defaultTemplate(ctx) {
   }
   return lines.join("\n");
 }
+function subFolderClickable(groupLink, isRoot) {
+  if (groupLink === "off") return false;
+  if (groupLink === "top-level") return isRoot;
+  return true;
+}
 
 // src/core/scan-wikilinks.ts
 var WIKILINK_RE3 = /(!?)\[\[([^\]\n]+)\]\]/g;
@@ -3534,6 +3643,7 @@ function defineConfigWithAllYouNeed(config, pluginOptions = {}) {
           sidebarAuto.autoFolderIndex,
           sidebarAuto.stripNumericPrefix
         );
+        folderOpts.groupLink = sidebarAuto.groupLink ?? "all";
         if (folderOpts.mode !== "off") {
           try {
             generateFolderIndexes(resolvedForWrapper, folderOpts);
@@ -3604,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) {