跳到主要内容

文档首页维护工作流

这篇文档记录当前知识库首页，也就是 /docs/intro 对应入口页的维护方式。

现在这个入口不再是一篇普通 Markdown 长文，而是由一个很薄的 MDX 文件挂载 React 组件：

docs/intro.mdx
src/components/DocsIntro/
src/data/siteStats.generated.json
scripts/generate-site-stats.mjs

这样做的目的，是把“文档入口页”从纯正文页升级成更清晰的站点地图：首屏说明知识库定位，下面按主题分支展示主要入口，并在顶部展示文章数量和累计字数。

文件职责​

docs/intro.mdx​

这个文件只保留 Docusaurus 文档页需要的 front matter，并导入 DocsIntro 组件。

不要在这里继续堆大段正文。首页内容、链接分组、统计展示和视觉结构都应该维护在组件里，否则后续会出现同一个入口页同时由 MDX 正文和 React 组件共同控制的混乱状态。

src/components/DocsIntro/index.js​

这个文件维护文档首页的内容结构。

主要包括：

  • TOPIC_GROUPS：首页展示的主题分组、入口链接、说明文字和图标类型
  • CONTACT_LINKS：首页底部联系方式
  • HERO_STATS：首屏统计项，当前从主题数量和生成统计数据组合而来
  • Icon：当前组件内使用的轻量图标集合

以后新增大的内容板块时，如果它已经是稳定入口，并且应该出现在文档首页，就同步更新 TOPIC_GROUPS。

如果只是新增普通文章，不需要改这里。文章数量和字数会由统计脚本自动刷新。

src/components/DocsIntro/styles.module.css​

这个文件只负责文档首页组件的样式。

维护时要注意：

  • 首页卡片链接需要在桌面和移动端都可读
  • 统计数字不能因为字数增长导致布局横向溢出
  • 深色主题需要和浅色主题同时检查
  • 颜色、间距、圆角和卡片样式应保持和站点现有设计一致

scripts/generate-site-stats.mjs​

这个脚本会扫描 docs/ 和 blog/ 下的 Markdown / MDX 文件，跳过 draft: true 的文章，生成：

{
  "docsArticleCount": 0,
  "blogPostCount": 0,
  "articleCount": 0,
  "wordCount": 0
}

统计结果写入：

src/data/siteStats.generated.json

wordCount 是面向站点展示的粗略可读字数统计，不是论文级精确字数。脚本会去掉 front matter、代码块、行内代码、MDX 标签、图片语法和普通链接语法，再统计中文字符和英文数字词。

构建流程变化​

当前 package.json 已经把统计刷新接入本地启动和生产构建：

npm start
npm run build

这两个命令都会先执行：

npm run generate:site-stats

因此正常开发和上线前构建时，不需要手动额外刷新统计数据。

只有在下面这些情况下才需要单独运行：

npm run generate:site-stats
  • 想在不启动 Docusaurus 的情况下更新 src/data/siteStats.generated.json
  • 批量新增或删除文章后，想先检查统计结果
  • 调整统计脚本后，想单独验证输出

新增或调整首页入口时怎么做​

1. 确认入口已经稳定​

不要把临时文章、未成体系的草稿或还会频繁改路径的内容放进首页入口。

首页适合放：

  • 长期维护的主题板块
  • 已经有稳定分类页的内容集合
  • 读者第一次进入知识库时最应该看到的主线

2. 更新 TOPIC_GROUPS​

在 src/components/DocsIntro/index.js 里给对应分组增加或调整条目。

每个条目至少要确认：

  • title 是前端显示名
  • href 是稳定可访问路径
  • meta 是简短主题标签
  • description 能说明这个入口适合读什么
  • icon 在 Icon 函数里存在
  • accent 和当前页面配色协调

如果新增了新的 icon 类型，需要同步补 Icon 里的 SVG path。

3. 不要让首页替代目录规则​

首页只是更友好的入口，不替代 Docusaurus 的分类页、侧边栏和专题目录规则。

新增专题目录时仍然要遵循：

也就是说，先保证目录、_category_.json、sidebars.js 和路由是稳定的，再考虑是否把它挂到首页。

验证清单​

改动文档首页或统计脚本后，至少执行：

npm run build

然后检查：

  1. src/data/siteStats.generated.json 已经刷新
  2. /docs/intro 能正常构建
  3. 首页主题卡片链接没有 broken link
  4. 深色主题下首屏文字和卡片可读
  5. 移动端统计区和卡片区没有横向溢出

如果只调整文字和入口链接，通常不需要额外写测试；如果修改统计脚本逻辑，至少要用 npm run generate:site-stats 单独确认输出格式没有变化。