文档结构

Diátaxis 框架

本站各子系统文档遵循 Diátaxis 理论，将文档分为四类：

Diátaxis 类型	实际目录	读者需求	写作风格
Explanation	Overview / Developer Guide	理解原理	概念性、少步骤
Tutorial	Getting Started	第一次上手	逐步跟着做
How-to	User Guide / Deployment / Troubleshooting	完成具体任务	任务导向
Reference	API Reference / Configuration	查参数配置	结构化、可扫描

标准子系统目录

新增或重构某一业务系统文档时，推荐使用以下结构（以 docs/systems/<系统名>/ 为根）：

docs/systems/<系统名>/
├── index.md                    # 系统文档首页与导航
├── Overview/
│   ├── Introduction.md
│   ├── Features.md
│   ├── System-Architecture.md
│   └── Tech-Stack.md
├── Getting-Started/
│   ├── Installation.md
│   ├── Quick-Start.md
│   └── ...
├── User-Guide/
├── API-Reference/              # 有 API 的系统
├── Configuration/
├── Deployment-Guide/
├── Developer-Guide/            # 需要二次开发的系统
├── Troubleshooting/
├── FAQ.md
└── Contributing/               # 可选

组织级文档（简化结构）

以下顶层目录不必套用完整子系统结构：

路径	用途
docs/intro.md	站点欢迎页
docs/rules.md	技术部规章制度
docs/onboarding/	新人指引
docs/server/	服务器与运维
docs/members/	历史成员
docs/glossary.md	全局术语表

文档 ID 与 URL

• 文件 docs/systems/cssagpt/Overview/Introduction.md 的 doc ID 为 systems/cssagpt/Overview/Introduction
• 对应 URL：/docs/systems/cssagpt/Overview/Introduction
• sidebars.ts 中引用时使用 doc ID（不含 .md、不含 docs/ 前缀）

Frontmatter 约定

---
sidebar_position: 1    # 同目录内排序（可选）
title: 自定义标题       # 侧边栏与页面标题（可选）
---

系统首页 index.md 常用 sidebar_position: 0 排在分类最前。