## Context

**当前状态**:

项目目前有两个主要文档文件：
- `README.md` (1102 行) - 面向终端用户，包含安装、使用、API 文档等
- `README_DEV.md` (1249 行) - 面向开发者，包含架构、开发规范、测试等

这种"巨型单文件"结构导致：
- 新用户需要滚动大量内容才能找到快速开始指南
- 开发者难以在 1249 行中定位特定的模块说明
- AI 处理长文档时容易丢失上下文
- 违反渐进式披露设计原则

**约束条件**:
- 不引入文档生成工具（MkDocs、Docusaurus 等），保持纯 Markdown
- 不修改代码功能
- 保持用户文档和开发文档的明确划分
- 项目尚未上线，无现有用户需要迁移

## Goals / Non-Goals

**Goals:**
- README.md 精简到约 300 行，聚焦快速开始和核心概念
- 建立清晰的文档导航结构，用户能在 3 次点击内找到所需信息
- 按主题模块化拆分文档，每个文件控制在 100-300 行
- 保持文档内容的完整性和准确性，只重组不删除

**Non-Goals:**
- 不改变代码行为或 API
- 不引入新的文档工具链
- 不创建多语言版本
- 不改变项目现有的开发规范

## Decisions

### 1. 文档目录结构

**决策**: 采用两层目录结构 `docs/` 和 `docs/development/`

**理由**:
- 用户文档和开发文档读者群体不同，分离后避免相互干扰
- 两层结构比单层更清晰，比三层更简洁
- 与 GitHub/GitLab 的文档展示方式兼容

**替代方案考虑**:
- 单层 `docs/` 目录：会导致用户和开发文档混在一起，增加认知负担
- 三层结构（如 `docs/user/guide/`）：对于纯 Markdown 项目过于复杂，导航困难

### 2. README.md 内容策略

**决策**: 保留"概览 + 快速开始 + 导航链接"结构

**理由**:
- 项目首页需要给用户最核心的信息：这是什么、怎么快速开始、去哪里深入了解
- 300 行限制确保在 GitHub 首页可以完整浏览而不需要大量滚动

**README.md 保留内容**:
1. 项目标题和一句话描述
2. 功能特性列表（精简）
3. 快速开始（安装、5 分钟上手、实时预览）
4. 核心概念概述（YAML 语法、元素类型、模板系统，各控制在 50 行内）
5. 文档导航（分类链接到 docs/）
6. 常见用例（3-5 个示例）
7. 项目信息（依赖、许可证）

### 3. 拆分粒度

**决策**: 按主题拆分，每个文件 100-300 行

**理由**:
- 按主题拆分符合用户的思维模型（"我需要了解模板系统" → 打开 templates/）
- 100-300 行确保每个文件专注单一主题，易于维护
- 过细的拆分（如 50 行一个文件）会导致文件碎片化，增加导航负担

**具体拆分方案**:

```
docs/
├── user-guide.md           (200-300行) - 用户完整指南
├── elements/               - 按元素类型拆分
│   ├── text.md             (100-150行)
│   ├── image.md            (100-150行)
│   ├── shape.md            (100-150行)
│   └── table.md            (100-150行)
├── templates/              - 按模板功能拆分
│   ├── inline.md           (150-200行)
│   ├── external-library.md (150-200行)
│   ├── mixing-mode.md      (150-200行)
│   └── condition-rendering.md (150-200行)
├── fonts.md                (200行) - 字体主题系统
├── reference/              - API 参考文档
│   ├── commands.md         (50-100行)
│   ├── coordinates.md      (50-100行)
│   ├── colors.md           (50-100行)
│   └── validation.md       (50-100行)
├── examples.md             (200行) - 示例集合
└── troubleshooting.md      (100行) - 故障排查

docs/development/
├── architecture.md         (300行) - 架构设计
├── modules/                - 按代码模块拆分
│   ├── elements.md         (100-200行)
│   ├── template.md         (100-200行)
│   ├── validators.md       (100-200行)
│   ├── renderers.md        (100-200行)
│   └── loaders.md          (100-200行)
├── font-system.md          (150行) - 字体系统实现
├── scope-system.md         (200行) - 作用域系统
├── development-guide.md    (150行) - 开发规范
├── extending.md            (200行) - 扩展指南
├── testing.md              (200行) - 测试规范
└── maintenance.md          (100行) - 维护指南
```

### 4. 文档间链接策略

**决策**: 使用相对路径链接，创建导航辅助文件

**理由**:
- 相对路径在 Git clone 后仍然有效
- 每个目录下的 `index.md` 或 `_nav.md` 提供该目录的导航

**实现**:
- 在每个子目录创建索引文件（如 `docs/elements/_index.md`）列出该目录下的所有文档
- README.md 中的链接使用 `./docs/...` 相对路径
- 文档间的交叉引用也使用相对路径

### 5. 内容迁移策略

**决策**: 先创建新结构，再移动内容，最后清理原文件

**理由**:
- 降低操作风险，随时可以回滚
- 确保没有内容遗漏

**迁移顺序**:
1. 创建完整的目录结构
2. 创建空的目标文件（带模板头部）
3. 按主题从源文件复制内容到目标文件
4. 更新所有交叉引用链接
5. 精简 README.md 到 300 行
6. 删除 README_DEV.md（内容已迁移）
7. 验证所有链接有效性

## Risks / Trade-offs

### 风险 1: 外部链接失效

**风险**: 项目外部的博客、教程引用了原 README.md 的特定章节，迁移后这些链接会失效。

**缓解措施**:
- 项目尚未上线，无外部引用
- 在 README.md 顶部添加迁移说明（如果未来有外部引用）
- 考虑保留原文件的 Git 历史供追溯

### 风险 2: 用户找不到信息

**风险**: 用户习惯了在 README.md 中查找所有信息，迁移后可能不知道去哪里找详细内容。

**缓解措施**:
- README.md 保留清晰的文档导航区块，分类列出所有子文档
- 每个子文档顶部有"返回导航"链接
- 在 `docs/README.md` 创建完整文档索引

### 风险 3: 维护负担增加

**风险**: 文件数量从 2 个增加到约 25 个，可能增加维护成本。

**缓解措施**:
- 每个文件职责明确，单一主题，降低修改时的认知负担
- 使用相对路径链接，重命名时工具可自动更新
- 定期审计文档结构，合并过于碎片化的文件

### 权衡: 简洁 vs 完整

**权衡**: README.md 精简后可能让部分用户感觉"信息不完整"。

**缓解措施**:
- 在 README.md 中明确说明这是"快速入门"，完整文档在 docs/
- 保持 docs/ 文档的完整性和详细程度
- 提供"常见用例"覆盖 80% 用户的需求

## Migration Plan

### 阶段 1: 准备 (1-2 小时)

- [ ] 创建 `docs/` 和 `docs/development/` 目录结构
- [ ] 创建所有目标文件的空模板（带标题和简要说明）
- [ ] 在 `docs/README.md` 创建完整文档索引

### 阶段 2: 内容迁移 (3-4 小时)

- [ ] 按拆分方案从 README.md 复制内容到各子文档
- [ ] 按拆分方案从 README_DEV.md 复制内容到各开发文档
- [ ] 更新所有文档内部的交叉引用链接
- [ ] 添加每个文档的导航链接（返回上级、相关文档）

### 阶段 3: 精简主文件 (1 小时)

- [ ] 精简 README.md 到约 300 行
- [ ] 删除 README_DEV.md（内容已迁移）
- [ ] 更新 README.md 中的文档导航链接

### 阶段 4: 验证 (30 分钟)

- [ ] 检查所有相对路径链接是否有效
- [ ] 验证没有内容遗漏
- [ ] 在 GitHub 上预览文档显示效果

### 回滚策略

- 保留 Git 历史，随时可以 `git checkout` 回原来的文档结构
- 建议在新分支进行迁移，验证通过后再合并到主分支

## Open Questions

1. **是否需要文档搜索功能？**
   - 纯 Markdown 项目无法提供搜索，依赖 GitHub 的代码搜索
   - 用户反馈后可考虑引入文档生成工具

2. **示例文档策略？**
   - 目前未设计专门的示例文件
   - `docs/examples.md` 作为占位文档，未来可根据用户需求添加
   - 各主题文档中已内嵌代码示例供参考

3. **文档版本策略？**
   - 当前项目尚未发布，暂不考虑多版本文档
   - 未来发布后，可能需要为不同主版本维护独立文档分支