内容模型

这份规范的目标只有一个：

让文档既适合人阅读，也适合后续检索、内链、搜索与 RAG 切片。

0. 文档受众边界

当前仓库默认分成两大文档域：

• docs/：读者域
• dev/：开发维护域

判断原则：

• 面向访问者、学习者、读者的内容，进入 docs/
• 面向维护者、开发者、协作者的内容，进入 dev/
• GitHub 工作流模板进入 .github/

docs/ 中尽量不混入：

• 版本发布流程
• 开发排期
• 维护日志
• Issue 模板说明
• 内部开发模板

当前机器侧注册表位于：

• docs/.vitepress/content-registry.mjs

新增文档时，默认同时更新：

• 实际文档文件
• 注册表
• 必要时更新索引页与侧边导航

一、文档层级

每篇文档默认归入以下四类之一：

• landing：入口页
• guide：导读页
• concept：概念页
• note：笔记页

不要把不同类型混在一页里。

二、信息架构层级

为了支持后续多板块、多模块、多章节扩展，当前默认采用四级结构：

• section：板块
• module：模块
• topic：主题
• doc：文档

可理解为：

板块 -> 模块 -> 主题 -> 文档

例如：

易经 -> 基础 -> 学习方法 -> learning-method.md
道家 -> 原典 -> 道德经 -> index.md

判断原则：

• 板块解决“大类内容归属”
• 模块解决“稳定子域归属”
• 主题解决“可持续扩展的小集合”
• 文档解决“单一问题表达”

三、目录粒度

默认遵循：

• 一个目录表示一个稳定主题域
• 一个页面只解决一个清晰问题
• 长内容拆成多个短页面，通过入口页组织

建议控制：

• 入口页：目录与路径为主
• 正文页：聚焦单一主题
• 单页尽量短而完整，避免超长滚动页

四、文件命名

为了兼顾链接稳定、工具链兼容和后续知识库处理，当前默认：

• 文件路径用 ASCII slug
• 页面标题用中文
• 同级命名保持一致风格

例如：

• daoism/texts/dao-de-jing/index.md
• yijing/basics/core-concepts.md

五、推荐 Frontmatter

后续新增内容建议统一包含：

---
title: 页面标题
description: 一句话描述
---

如果后续要增强检索，可扩展：

---
title: 道德经导读
description: 道家入门的第一站
category: guide
tags:
  - 道家
  - 原典
  - 道德经
source:
  - 老子《道德经》
---

六、内链原则

优先建立三种链接：

• 入口页 → 正文页
• 概念页 → 相关原典页
• 笔记页 → 所依据的原典 / 专题页

避免孤页。

七、面向扩展的拆分原则

当一个主题开始变大时，优先这样拆：

• 先保留 index.md 作为主题入口
• 再把正文拆到同级子页
• 不要把入口页写成正文总集

例如：

daoism/texts/dao-de-jing/
  index.md
  background.md
  reading-method.md
  concepts.md

这样做的好处是：

• URL 稳定
• 目录可持续长大
• 不会因为单页过长影响阅读与后续切片

八、单页推荐结构

推荐按以下顺序组织：

1. 是什么
2. 为什么重要
3. 怎么读 / 怎么理解
4. 我的理解
5. 参考来源

或使用三问：

• 象
• 理
• 用