vitepress-allyouneed 0.3.4 → 0.3.6

package/CHANGELOG.md

@@ -2,6 +2,50 @@
 
 本项目遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/);版本号遵循 [SemVer](https://semver.org/lang/zh-CN/)。
 
+## [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 {
@@ -2761,7 +2794,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 +2957,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 +3047,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 +3086,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 +3116,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 +3160,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 +3335,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 +3418,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 +3429,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 +3450,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 +3604,7 @@ function defineConfigWithAllYouNeed(config, pluginOptions = {}) {
           sidebarAuto.autoFolderIndex,
           sidebarAuto.stripNumericPrefix
         );
+        folderOpts.groupLink = sidebarAuto.groupLink ?? "all";
         if (folderOpts.mode !== "off") {
           try {
             generateFolderIndexes(resolvedForWrapper, folderOpts);