用途
doc-standard 是 youlai-admin 项目的文档写作规范，约束 youlai-admin-docs 所有栏目的写作风格。其目标是让读者快速找到代码、复制即用，不读废话。
核心原则是：读者带任务来，带代码走；代码给机器执行，文档给人理解。写文档时先想读者为什么打开这页、离开时手里该拿着什么。
文档分类框架
规范基于 Diátaxis 框架，按读者需求将文档分为四种模式，一篇文档只做一件事：
- 教程：回答“教我怎么一步步做”，对应操作指南（界面操作）、开发指南（写代码）。
- 操作指南：回答“帮我完成这个任务”，对应进阶定制。
- 参考：回答“这个组件/函数/配置项有哪些 API”，对应组件文档、Composable 文档、系统设置、FAQ。
- 解释：回答“团队约定是什么”，对应代码规范。
操作指南不混入原理，参考文档不混入教程。横切主题用交叉引用，不重复。
文档维护原则
借鉴 Google 文档最佳实践：
- 最小可用文档：少量新鲜准确的文档优于大量陈旧破损的文档，像修剪盆景一样持续维护。
- 随代码更新：文档变更与代码变更在同一个 PR，不滞后。
- 删除死文档：过时、错误、冗余的文档及时删除，死文档比没文档更糟。
- 消灭重复：链接而非复制，同一信息只在一处定义，其他地方交叉引用。
- 写给人看：代码能表达的不写文档（命名、类型签名）；文档写代码不能表达的（意图、约束、边界）。
禁止出现的元素
以下元素一律删除：
- 「先看什么？」导航表。
- 「介绍」「概览」纯描述段。
- 「功能特性」列表。
- 「使用场景」段落（进阶定制开头说明适用场景除外）。
- 「快速摘要」复述目录。
- ASCII 架构图，应改用 mermaid 或列表。
- 「下一步」「相关链接」尾巴。
- 「实现原理」长篇。
- emoji 装饰。
- 「源码位置」清单。
- 「常见问题」放正文，FAQ 应集中在 /faq/ 栏。
- 「总结」复述全文。
- 「参考来源」列表。
- 「为什么这样设计」解释段。
- 博客式过渡句。
- 空话引言。
允许但克制的元素
- 一句话引言：章节开头点明“这是什么、能做什么”，不超过 2 行。
- mermaid 流程图：真正复杂的流程才用，简单流程直接列表。
- 注意事项 ::: tip：真正会踩坑的点，每页不超过 1 个。
- 表格：只在字段多、需要对照时用。
通用结构约束
所有文档必须遵循：
---
title: 页面标题
---
# 页面标题
一句话说明这页讲什么、读者能做什么。不超过 2 行。
## 章节一
（代码 + 必要说明，不写「实现原理」）
## 章节二
（同上）
硬规则：
- 文件开头 title 与 # 标题一致。
- 一句话引言后直接进章节，不插入「介绍」「概览」「先看什么」。
- 章节标题写「做什么 / 是什么」，不写「原理」「机制」「详解」。
- 代码块必须带语言标注（
typescript /vue），TypeScript 统一用全称 typescript，不用缩写 ts。 - 代码示例值要具体（ref(1) 不要 ref('')），含注释说明值含义。
- 文档末尾不加「相关链接」「下一步」「源码位置」尾巴。
- 全文不出现 emoji（含代码注释中的正误符号）。
- 代码注释中标注正误时用文字而非符号：// 推荐 / // 不推荐。
目录与命名规范
- 所有目录和 .md 文件使用 kebab-case（小写 + 连字符）。
- 文件名与 title frontmatter 保持语义一致。
- 禁止同内容文件并存（如 index.md 与 introduction.md 重复）。
- 遗留文件及时清理（已合并的旧模板应删除）。
内容归属规则
当某个主题横跨两个文档类型时，按主操作归属，另一篇用交叉引用：
- 菜单标题国际化：归属 i18n.md，router-menu.md 一句话 + 链接。
- 环境变量：归属 settings.md，deploy.md 引用。
- Nginx 配置：归属 deploy.md，settings.md 不重复。
- 按钮权限与权限标识：归属 permission.md，router-menu.md 引用。
交叉引用格式：详见新增菜单，不单独开「相关链接」章节。
栏目模板
7 种栏目模板（操作指南、开发指南、项目部署、组件文档、Composable 文档、进阶定制、FAQ）定义了每种文档的结构、写作规则和字数控制。详见 templates.md。