feat(docs): CommunityShare 索引改为从 fumadocs source 自动生成（替代 #110） by longsizhuo · Pull Request #288 · InvolutionHell/involutionhell

longsizhuo · 2026-04-16T19:01:16Z

背景

`app/docs/CommunityShare/index.mdx` 一直是人工维护的 Markdown 列表，已经明显落后：

缺列 5 个实际存在的分类：`Amazing-AI-Tools / Language / Leetcode / Life / Personal-Study-Notes`
反向遗留"身体健康"分类（没对应目录，只有标题和 4 个空条目占位）
社区每新增一篇都得记得回来改 index，事实上没人这么做

这也是 #110 最早想解决的问题。LynPtl 在 #110 里方向是对的，但实现路线：

引入 `glob` + `gray-matter` 两个新依赖
写一个 Node 脚本 `scripts/generate-community-index.js` 走一遍目录 + 解析 frontmatter
把生成结果写回静态 `index.mdx`
接 CI workflow 让它定期跑

这条路线的问题：fumadocs 本身已经在跑目录扫描 + slug 规范化（包括 `lib/source.ts` 里给 `CommunityShare/Leetcode` 做的拼音 slug transform——硬拼 URL 会漏掉这个 transform），再自己复一份属于重复造轮子；而且 `index.mdx` 留在 git 里"被脚本重写"的文件，prettier / docId sync 等其他 workflow 容易互相打架。#110 里 TSK 也留了 "需要加依赖、workflow 要接" 的 Changes Requested，7 个月没跟进。

方案（这个 PR）

改成 server component 实时从 fumadocs source 读取，零新增依赖、零脚本、零 CI 步骤：

`app/components/CommunityShareIndex.tsx`:

`source.getPages()` 拉所有页面，filter path 以 `CommunityShare/` 开头
按第一级子目录分组 → 每组一个分类 section
分类标题：优先读子目录 `index.mdx` 的 frontmatter.title，没 index 时降级用目录名
翻译版（`lang === "en"` 或文件名以 `.en` 结尾）统一过滤，列表只出原文 URL；语言切换仍由 `[...slug]/page.tsx` 的 cookie 逻辑负责
条目数超过阈值 (12) 的分类折叠成"查看全部 N 篇 →"单行链接，避免 Leetcode（49 篇）把首页顶爆
所有链接走 `page.url`，不硬拼 `/docs/CommunityShare/`（Leetcode 的拼音 slug transform 靠这个保留）

`app/docs/CommunityShare/index.mdx`:

保留 intro 段落 / 投稿引导 / 版权说明
移除全部硬编码分类列表，换成 ``

本地验证

```
$ curl -s localhost:3010/docs/CommunityShare | grep -oE "[0-9]+ 篇" | sort -u
1 篇（Amazing-AI-Tools, Language, Life, Personal-Study-Notes — 新挖出来的空/单篇分类）
3 篇（MentalHealth, RAG）
11 篇（Geek — 技术分享）
49 篇（Leetcode — 折叠为"查看全部 49 篇 →"）
```
"身体健康"分类消失；新分类自动出现。

关联 / 关闭

取代 feat(docs): 新增脚本以自动生成 CommunityShare 索引页 #110，关掉那个 PR（credits 保留，LynPtl 最早指出了手维护会过期这个根本问题）
不引入 `glob` / `gray-matter`，不加 workflow 步骤
`lib/source.ts` 里 Leetcode 的拼音 slug transform 被这个组件复用，不再需要在索引脚本里重复一遍

Test plan

本地 dev server (`localhost:3010/docs/CommunityShare`) 验证所有 8 个分类正确渲染，Leetcode 触发折叠
`pnpm tsc --noEmit` 对改动文件无报错
合并部署后目视 Prod 页面
随便往 CommunityShare/XXX 放一篇新文章，确认不需要改 index.mdx 就能出现在索引里（下次社区贡献时自然验证）

vercel · 2026-04-16T19:01:37Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
involutionhell-github-io	Ready	Preview, Comment	Apr 16, 2026 8:11pm
website-preview	Ready	Preview, Comment	Apr 16, 2026 8:11pm

Copilot

Pull request overview

将 CommunityShare 索引页从“手写静态列表”改为在渲染时从 fumadocs source 自动读取并生成分类与条目列表，避免索引长期过期。

Changes:

app/components/CommunityShareIndex.tsx 新增 Server Component：扫描 source.getPages()，按一级目录分组生成分类索引，并对大分类做折叠展示。
app/docs/CommunityShare/index.mdx 移除硬编码分类/链接列表，改为渲染 <CommunityShareIndex />。

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
app/docs/CommunityShare/index.mdx	用组件替换手写索引列表，避免后续人工维护。
app/components/CommunityShareIndex.tsx	从 fumadocs source 读取页面并生成分类索引（含英文变体过滤与大类折叠）。

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-16T19:06:28Z

+      const displayTitle = categoryIndex?.data.title ?? dirName;
+      const categoryUrl = categoryIndex?.url ?? `/docs/${ROOT}/${dirName}`;
+


categoryUrl 在没有分类 index 文件时会 fallback 到硬编码的 /docs/CommunityShare/<dirName>。仓库里已经存在没有 index 的分类目录（例如 CommunityShare/Language、CommunityShare/Life），这些 URL 当前并不会对应到任何页面（只存在 /docs/CommunityShare/Language/pte-intro 之类的叶子页），因此这里生成的分类标题链接与“查看全部 N 篇”链接会导致 404。建议：当 categoryIndex 不存在时不要渲染分类标题为链接/不要启用折叠；或改为使用该分类下某个实际存在页面的 page.url（例如第一篇 entry）作为跳转目标，并避免硬编码 URL。

@LynPtl

现状：/docs/CommunityShare/index.mdx 里的分类列表长期人工维护，已经过期： - 缺列了 Amazing-AI-Tools / Language / Leetcode / Life / Personal-Study-Notes 五个分类 - 还留着"身体健康"这种没对应目录、只有标题没有文章的占位分类 - 新增文章后还得记得回来改 index，实际做不到改法：新增 server component `CommunityShareIndex`，直接读 fumadocs `source.getPages()` 按第一级子目录分组渲染，分类标题优先读子目录 index.mdx 的 frontmatter.title，没 index 时降级用目录名。翻译版（lang === "en" / 文件名 .en）统一不进列表。条目数超过 12 的分类折叠成"查看全部 N 篇 →"单行链接，避免 Leetcode 顶爆页面。替代 #110：#110 是脚本生成静态 MDX 的路线，需要引入 glob / gray-matter 两个新依赖 + 一个 CI 步骤 + 一套目录名硬编码映射表。用 fumadocs source 之后这些全部不需要——fumadocs 已经在跑目录扫描和 slug 规范化（包括 lib/source.ts 里 Leetcode 的拼音 slug transform，硬拼 URL 会漏掉），直接复用更干净。感谢 @LynPtl 最早指出了手维护索引会过期的问题（#110 的痛点诊断）。 Co-authored-by: LynPtl <194795025+LynPtl@users.noreply.github.com>

合并 #288 + #290 + app/docs/CommunityShare/Leetcode/index.mdx 里原先三份各自实现的"列目录子节点"逻辑，改成一个 server component。 ## 为什么要合并原本三处各自实现： - /docs 根路由（PR #290 draft）—— 读 pageTree.children - CommunityShare/index.mdx（PR #288 draft）—— 读 getPages() 过滤 path - CommunityShare/Leetcode/index.mdx —— 内联 MDX 里 source.getPages().filter().map() drift 问题：排序、英文过滤、fallback URL 三份逻辑各走各的；更严重的是 PR #288 里对"没 index.mdx 的子目录"硬拼 /docs/CommunityShare/<dir> 会 404 （Copilot CR 指出），和 PR #290 修 /docs 404 是同一个根因：Next [...slug] 不匹配空 slug，folder 没 index 就意味着 /docs/X 没 route。 ## <SectionIndex root?> - 走 source.pageTree（不是 getPages），fumadocs 已经把 folder+index 关系建好了，不用自己从扁平 page 列表反推 - root 接 "CommunityShare" / "CommunityShare/Leetcode" 这种相对路径，不传就是从 pageTree 根开始（给 /docs landing 用） - URL 永不硬拼：folder 有 index 走 index.url；没 index 递归找子树第一个 page 的 url 作为 fallback（直接修掉 CR 那个 404 bug） - 英文翻译版（URL 末段 .en）过滤不进列表；语言切换仍由 [...slug] 的 cookie fallback 负责 - 统一 fumadocs <Cards>/<Card> 视觉 ## 本地验证 - /docs → 5 张卡片，全部 200 - /docs/CommunityShare → 8 张卡片，全部 200（包括原先会 404 的 Language/ Life/Personal-Study-Notes/RAG 四个没 index 的分类，现在点进去是子目录里第一篇 page，不再死链） - /docs/CommunityShare/Leetcode → 49 张卡片，0 个 .en 泄漏 ## 取代关系 - 关闭 PR #288（CommunityShareIndex 专用实现，有 404 bug） - 关闭 PR #290（/docs landing 单独实现） - 本 PR 一并覆盖，继续承担解决 #110 的责任 Co-authored-by: LynPtl <194795025+LynPtl@users.noreply.github.com>

longsizhuo · 2026-04-16T19:18:37Z

替代方案见 #292：合并为单一 <SectionIndex> 组件，同时 fix CR 指出的 404 bug（没 index.mdx 的子目录硬拼 URL 404）。

…（取代 #288 #290） (#292) * refactor(docs): 统一 /docs、CommunityShare、Leetcode 三处索引为 <SectionIndex> 合并 #288 + #290 + app/docs/CommunityShare/Leetcode/index.mdx 里原先三份各自实现的"列目录子节点"逻辑，改成一个 server component。 ## 为什么要合并原本三处各自实现： - /docs 根路由（PR #290 draft）—— 读 pageTree.children - CommunityShare/index.mdx（PR #288 draft）—— 读 getPages() 过滤 path - CommunityShare/Leetcode/index.mdx —— 内联 MDX 里 source.getPages().filter().map() drift 问题：排序、英文过滤、fallback URL 三份逻辑各走各的；更严重的是 PR #288 里对"没 index.mdx 的子目录"硬拼 /docs/CommunityShare/<dir> 会 404 （Copilot CR 指出），和 PR #290 修 /docs 404 是同一个根因：Next [...slug] 不匹配空 slug，folder 没 index 就意味着 /docs/X 没 route。 ## <SectionIndex root?> - 走 source.pageTree（不是 getPages），fumadocs 已经把 folder+index 关系建好了，不用自己从扁平 page 列表反推 - root 接 "CommunityShare" / "CommunityShare/Leetcode" 这种相对路径，不传就是从 pageTree 根开始（给 /docs landing 用） - URL 永不硬拼：folder 有 index 走 index.url；没 index 递归找子树第一个 page 的 url 作为 fallback（直接修掉 CR 那个 404 bug） - 英文翻译版（URL 末段 .en）过滤不进列表；语言切换仍由 [...slug] 的 cookie fallback 负责 - 统一 fumadocs <Cards>/<Card> 视觉 ## 本地验证 - /docs → 5 张卡片，全部 200 - /docs/CommunityShare → 8 张卡片，全部 200（包括原先会 404 的 Language/ Life/Personal-Study-Notes/RAG 四个没 index 的分类，现在点进去是子目录里第一篇 page，不再死链） - /docs/CommunityShare/Leetcode → 49 张卡片，0 个 .en 泄漏 ## 取代关系 - 关闭 PR #288（CommunityShareIndex 专用实现，有 404 bug） - 关闭 PR #290（/docs landing 单独实现） - 本 PR 一并覆盖，继续承担解决 #110 的责任 Co-authored-by: LynPtl <194795025+LynPtl@users.noreply.github.com> * docs(SectionIndex): 加大量中文注释说明 pageTree 心智模型 + 每步做什么 * fix(SectionIndex): 按 CR 补齐 locale 变体过滤 + 去掉注释里的 markdown Copilot 在 #292 提了 3 条要修的： 1) isEnglishVariant 只过滤 .en，没管 .zh —— 站点实际有 .zh.md（原文是 en 时的中文翻译），重复链接会在索引里暴露。改成 isHideableLocaleVariant(url, canonicals)：只有对应 canonical 存在时才隐藏，孤儿（只有 .en 或 .zh 单一形态的文档，共 35 + 7 篇）保留。 2) folder.index 如果本身是翻译版（理论上会有 index.en.mdx / index.zh.mdx），不能直接当卡片 href，会暴露非 canonical URL。nodeToCard 里给 idxUrl 加同样的过滤，不合规时退回 findFirstPageUrl。 3) folderSegmentName 注释写的"倒数第二段"但代码取的是最后一段，改掉注释。另外按用户反馈清掉注释里的 markdown（**bold**、反引号等），代码注释又不会被渲染。 --------- Co-authored-by: LynPtl <194795025+LynPtl@users.noreply.github.com>

Copilot AI review requested due to automatic review settings April 16, 2026 19:01

longsizhuo mentioned this pull request Apr 16, 2026

feat(docs): 新增脚本以自动生成 CommunityShare 索引页 #110

Closed

Copilot started reviewing on behalf of longsizhuo April 16, 2026 19:01 View session

Copilot AI reviewed Apr 16, 2026

View reviewed changes

longsizhuo force-pushed the feat/community-share-auto-index-v2 branch from f529eeb to 010a596 Compare April 16, 2026 19:09

longsizhuo mentioned this pull request Apr 16, 2026

refactor(docs): 统一 /docs、CommunityShare、Leetcode 三处索引为 <SectionIndex>（取代 #288 #290） #292

Merged

5 tasks

longsizhuo closed this Apr 16, 2026

vercel Bot deployed to Preview – website-preview April 16, 2026 19:59 View deployment

vercel Bot deployed to Preview – involutionhell-github-io April 16, 2026 20:11 View deployment

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(docs): CommunityShare 索引改为从 fumadocs source 自动生成（替代 #110）#288

feat(docs): CommunityShare 索引改为从 fumadocs source 自动生成（替代 #110）#288
longsizhuo wants to merge 1 commit intomainfrom
feat/community-share-auto-index-v2

longsizhuo commented Apr 16, 2026

Uh oh!

vercel Bot commented Apr 16, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 16, 2026

Uh oh!

longsizhuo commented Apr 16, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		const displayTitle = categoryIndex?.data.title ?? dirName;
		const categoryUrl = categoryIndex?.url ?? `/docs/${ROOT}/${dirName}`;

Conversation

longsizhuo commented Apr 16, 2026

背景

方案（这个 PR）

本地验证

关联 / 关闭

Test plan

Uh oh!

vercel Bot commented Apr 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

longsizhuo commented Apr 16, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

vercel Bot commented Apr 16, 2026 •

edited

Loading