自动 Frontmatter ​

功能说明 ​

自动为所有文档和目录索引页生成/更新 frontmatter，包括 permalink、title、createTime、updateTime 等字段，确保文档元信息的完整性和一致性。

实现流程 ​

1. 创建索引页 ​

• 检查每个目录是否存在 index.md
• 如果不存在，创建基础的 index.md 文件（不含首页）

2. Frontmatter 生成/更新 ​

• 为所有文档和索引页生成/更新 frontmatter
• 自动分配 permalink（基于目录规则，如 /eda/e78b7）
• 设置 createTime 和 updateTime
• 同步 H1 标题与 title 字段
• 添加基础字段：description、aside、outline

3. 规则与保护 ​

• 跳过根首页 docs/index.md
• 跳过 docs/AllArticles.md（避免并发读写）
• 目录 index.md 的 permalink 采用前缀 + UUID5 规则
• 全局移除 coverImg 字段

执行时机 ​

• 开发模式：pnpm docs:dev 时自动执行
• 构建模式：pnpm docs:build 时自动执行
• 手动执行：可单独运行 AutoFrontmatter 插件

手动命令 ​

# 生成/修复 frontmatter（跳过首页与 AllArticles）
node -e "import('./docs/.vitepress/plugins/auto-frontmatter.js').then(m=>m.runAutoFrontmatter && m.runAutoFrontmatter())"

辅助组件 ​

• .vitepress/utils/articleMeta.ts：将 frontmatter 渲染为元信息区域（时间、分类、标签）

本次修复小结（针对 docs/70建站/52.本站主题） ​

• 新增按目录参数运行的校验与修复：
  • 校验：node scripts/validate-frontmatter.mjs "docs/70建站/52.本站主题"
  • 修复：node scripts/fix-frontmatter.mjs "docs/70建站/52.本站主题"
• 典型修复项：
  • 统一 title 与 H1 一致性（如移除 H1 中的自定义组件标签以对齐 title）
  • 规范化 categories、tags 为字符串数组
  • 修正不规范的标题空格与命名（如“文章元信息与 SEO”）

permalink 的 uuid5 与更新策略 ​

• 插件位置：docs/.vitepress/plugins/auto-frontmatter.js
• 规则配置：通过 rules 映射目录到前缀，前缀里用 $uuid5 占位，例如：
  • 70.建站/10.wordpress → /wordpress/$uuid5
  • 70.建站/51.Teek → /teek/$uuid5
  • 70.建站（顶层兜底）→ /website/$uuid5
• 匹配与优先级：
  • 先按 folderName 长度降序排序，优先匹配更具体的子目录
  • 路径大小写不敏感，Windows \\ 会转换为 / 比较
• uuid5 生成：
  • 使用 Date.now() 与 Math.random() 拼接后做 md5，截取前 5 个十六进制字符，确保短且冲突概率极低
  • 仅作为 URL 尾段标识，不承诺跨机器/跨时间的稳定可复现
• 智能更新四种情形（通过正则检测现有 permalink 是否已含 5 位 uuid 模式）：
  1. 无 permalink：依据匹配到的规则新增（将 $uuid5 替换为新生成的 5 位串）
  2. 有 permalink 但不含 uuid5：覆盖为规则前缀 + 新 uuid5
  3. 已含 uuid5 且前缀与期望一致：跳过更新，保留原值
  4. 已含 uuid5 但前缀与规则不一致：覆盖更新为新前缀 + 新 uuid5
• 未匹配任何规则：输出警告“未指定前缀”，不做更改

提示：该插件默认在构建阶段生效，建议在 pnpm docs:build 期间统一固化 permalink，开发阶段不建议自动改写以避免干扰编辑体验。

title 的生成与清洗逻辑 ​

• 校验脚本：scripts/validate-frontmatter.mjs
  • 要求 title 为非空字符串，并提示 H1 与 title 不一致的情况（仅提示，不改写）
• 修复脚本：scripts/fix-frontmatter.mjs
  • 从正文提取首个 H1（^# 标题）作为候选标题
  • 清洗规则 sanitizeTitle：
    • 移除内联组件/HTML 标签（如 <Icon />、<span>...</span>）
    • 合并多余空白，去除首尾空格
  • 当存在 H1 且与现有 title 不同：以清洗后的 H1 覆盖 frontmatter 中的 title
  • 若正文无 H1：不改写 title，仅保留原值或留待人工补充

示例命令：

# 仅检查，输出不一致与类型问题
node scripts/validate-frontmatter.mjs "docs/70建站/52.本站主题"

# 自动修复 title 清洗与数组字段规范化
node scripts/fix-frontmatter.mjs "docs/70建站/52.本站主题"