# DEV-001: 文档布局与 Frontmatter 要求

# 1. 文档位置概览

所有公开文档集中在 docs/i18n/{lang}/ 下。

# 有英文版时 symlink 到英文版（GitHub 默认显示）
packages/vue-app/README.md → ../../docs/i18n/en/README.md

# 无英文版时 symlink 到中文版
packages/fastapi-server/README.md → ../../docs/i18n/zh-Hans/README.md

位置	文件类型	lang 值
docs/i18n/{lang}/*.md	DEV-NNN, CFG-NNN, USER-NNN, REF-NNN（根文档）	zh-Hans / en
docs/i18n/{lang}/{pkg}/*.md	包子文档（README, INDEX）	zh-Hans / en

非公开目录（不纳入 frontmatter 标准化）：

目录	原因
plans/	计划文档，有自身 PLAN metadata 规范
SPRINTS/	Sprint 文档
.github/、.kilo/	Agent 配置
AGENTS.md	AI Agent 指引
CHANGELOG.md	变更日志，有自身格式
.changeset/	Changeset 文件
docs/基于Python的自动部署方案设计.md	历史设计记录

# 2. 统一 Frontmatter Schema

所有公开文档必须使用以下统一的 frontmatter schema：

---
title: "文档标题"              # text, 必填。文档显示标题
category: user-guide            # text, 必填。枚举值见下方
sidebar_order: 1                 # number, 可选。同 category 内排序
lang: zh-Hans                    # text, 必填。BCP 47 语言标签
sidebar_group: "开发指南"
tags:                            # list, 可选。标签列表
    - indexeddb
    - sync
status: active                   # text, 可选。active | deprecated | draft
created: 2026-05-20              # date, 可选。ISO 8601，创建日期
updated: 2026-06-06              # date, 可选。ISO 8601，最后更新日期
version: 1.0                     # text, 可选。语义化版本号
---

# 2.1. category 枚举值

值	适用范围	LYJ sidebar 分区
user-guide	USER-* 用户指南、README.md 包介绍	用户手册
dev-guide	DEV-、REF- 开发者文档、CFG-* 配置参考	开发手册

config、api、adr 等 category 在 LYJ 中暂未渲染。如需新增分区，需同步更新 LingYiJu/packages/project/generate-config.ts 的 catOrder。

# 2.2. lang 字段

BCP 47 语言标签，使用 script-based 而非 region-based：

标签	含义	适用场景
zh-Hans	简体中文（书写系统）	默认语言，地域中立
en	英语	英文翻译

# 2.3. 被 LYJ 站点跳过渲染的文档

以下文件会被 LYJ 自动排除，不需要特殊标记：

排除规则	效果	依据
**/INDEX.md	所有 INDEX.md 不生成页面	LYJ DocSource.excludePatterns
无 frontmatter	跳过渲染	scan() 检测
category 不在 catOrder 中	跳过渲染	scan() 检测

skip_doc_render 字段仍然有效，但仅作为每文件覆盖开关——正常情况下不需要在 frontmatter 中设置它。

# 2.4. 各位置字段要求

位置	必填字段	可选字段
docs/i18n/{lang}/*.md (根文档)	title, category, lang	sidebar_order, tags, status, created, updated, version
docs/i18n/{lang}/packages/{pkg}/README.md	title, category, lang	sidebar_order

INDEX.md 由 LYJ 端排除，无需 frontmatter 约束。README.md 如需在 LYJ 站点显示，需有 title + category；仅在 GitHub 展示则省略 frontmatter 即可。

# 2.5. sidebar_order 分配策略

文件模式	策略
docs/i18n/{lang}/DEV-NNN	按编号：DEV-001=1, …, DEV-010=10
docs/i18n/{lang}/USER-NNN	按编号
docs/i18n/{lang}/REF-NNN	按编号
docs/i18n/{lang}/CFG-NNN	=1
docs/i18n/{lang}/known-issues/*	=99
docs/i18n/{lang}/packages/*/README.md	README=1

# 3. 文档编号约定

前缀	范围	说明
DEV-NNN	开发指南	架构、设计、环境搭建、集成等
USER-NNN	用户手册	功能指南、操作说明
REF-NNN	参考	迁移策略、演变历史、深度主题
CFG-NNN	配置参考	环境变量、配置文件说明

adr/ 目录下的 ADR 文档使用独立编号体系（ADR-NNN-title.md）。

# 4. 新增文档检查清单

新增公开文档时，请确保：

1. [ ] 文件位于 docs/i18n/{lang}/ 下对应的子目录
2. [ ] 包含统一 frontmatter：title、category、lang 必填
3. [ ] sidebar_order 不与该 category 内现有文档冲突
4. [ ] 仅 GitHub 展示的文档（如根 README）省略 frontmatter，无需 doc site 渲染
5. [ ] 想被 doc site 渲染的文件必须有 frontmatter 且 category 在允许值中
6. [ ] lang 值必须与所在目录的语言一致
7. [ ] 文件命名符合 [PREFIX-]NNN-name.md 格式（如 DEV-003-cmtx-integration.md）

INDEX.md 等纯导航文件不需要特殊设置——LYJ 端自动排除。

# 5. 参考

• CMTX docs/i18n/zh-Hans/DEV-010-documentation-layout-and-frontmatter.md — CMTX 原始规范（含完整调研背景）
• LingYiJu/packages/project/generate-config.ts — LYJ 端扫描和排除逻辑