文档中心使用指南
本项目使用 Next.js 服务端渲染（SSR） 实现了自动扫描 app/docs/**/*.md 目录并在 /docs 页面显示文档列表的功能。
功能特性
- ✅ 自动扫描
app/docs目录下的所有 Markdown 文件 - ✅ 自动提取文档标题和描述
- ✅ 自动分类按类别分组显示文档
- ✅ 实时更新添加文档立即生效，无需手动操作
- ✅ 深层目录支持任意深度的子目录结构
- ✅ 智能过滤自动排除备份文件、虚拟环境等
使用方法
📝 添加新文档
- 在
app/docs/目录或子目录创建.md文件：
# 文档标题
> 这里是文档的简短描述，会自动提取作为文档描述。
## 内容开始
文档正文...
- 刷新浏览器 - 就这么简单！✨
无需： - ~~运行脚本~~ - ~~生成元数据文件~~ - ~~重启服务器~~
📂 文档格式
标题：第一个 # 标题会作为文档标题
描述：第一个引用块 > 或第一个段落会作为文档描述
支持：任意深度的子目录
示例：
# CRM 客户创建 SOP
> 本文档描述客户创建的标准操作流程。
## 1. 准备工作
...
🗂️ 目录结构
app/
└── docs/ # 文档根目录
├── CRM_OPERATION_MANUAL.md # 操作手册
├── workflows.md # 工作流文档
├── SOP/ # SOP 子目录
│ ├── README.md
│ ├── customer-creation-e2e.md
│ └── screenshots/ # 截图（自动排除）
└── API/ # API 文档目录
└── *.md
文档分类
系统会根据文件路径自动分类：
| 路径特征 | 分类 |
|---|---|
包含 sop/、test、e2e |
SOP / 测试流程 |
包含 operation、manual |
操作手册 |
包含 workflow |
工作流 |
包含 api、interface |
API / 接口 |
| 其他 | 其他文档 |
修改分类规则：编辑 lib/docs.ts 中的 categorizeDoc() 函数。
自动排除的内容
系统会自动排除以下内容：
screenshots/目录.venv/Python 虚拟环境node_modules/Node.js 依赖.git/Git 目录__pycache__/Python 缓存*.bk.md备份文件LICENSE.md许可证文件
技术实现
服务端渲染（SSR）
文档列表和详情页面都使用 Next.js 服务端渲染：
// 服务端直接读取文件系统
export default async function DocsLandingPage() {
const docs = await getDocsList(); // 每次请求都是最新的
// ...
}
优势： - ✨ 添加文档立即生效 - ✨ 无需手动生成步骤 - ✨ 始终保持最新 - ✨ 更好的 SEO
文档扫描
// lib/docs.ts
export async function getDocsList(): Promise<DocEntry[]> {
// 递归扫描目录
// 提取标题和描述
// 自动分类
// 返回文档列表
}
截图和资源
文档中的截图应放在对应的 screenshots/ 目录：
系统会自动将路径转换为 /api/docs/screenshots/customer-list.png。
文档查看器功能
内置的文档查看器支持：
- ✅ 全文搜索 -
Cmd+K(Mac) 或Ctrl+K(Windows) - ✅ 目录导航 - 自动生成文档目录（TOC）
- ✅ Markdown 渲染 - 支持 GitHub Flavored Markdown
- ✅ 代码高亮 - 自动语法高亮
- ✅ 响应式设计 - 适配手机/平板/桌面
- ✅ 暗色模式 - 支持主题切换
- ✅ 面包屑导航 - 清晰的导航路径
访问文档
文档列表
http://localhost:3000/docs
文档详情
http://localhost:3000/docs/{slug}
例如：
- http://localhost:3000/docs/crm-operation-manual
- http://localhost:3000/docs/sop-customer-creation-e2e
文件结构
admin/
├── lib/
│ └── docs.ts # 服务端文档工具
├── app/
│ ├── docs/ # 📁 文档源文件（添加到这里）
│ │ ├── *.md
│ │ └── SOP/
│ │ └── *.md
│ └── (public)/
│ └── docs/
│ ├── page.tsx # 文档列表页（SSR）
│ ├── [page]/page.tsx # 文档详情页（SSR）
│ └── DocViewer.tsx # 文档查看器
└── app/api/
└── docs/
└── [...path]/route.ts # 文档内容 API
常见问题
Q: 添加文档后看不到？
A: 刷新浏览器页面即可。服务端渲染会自动读取最新文件。
Q: 如何修改文档分类？
A: 编辑 lib/docs.ts 中的 categorizeDoc() 函数。
Q: 支持哪些 Markdown 语法？
A: 支持 GitHub Flavored Markdown (GFM)，包括表格、任务列表、删除线等。
Q: 描述显示不正确？
A: 确保文档格式正确：
# 标题
> 描述文本（优先提取）
或者没有引用块时，会提取第一段普通文本
Q: 如何优化性能？
A: 可以添加 ISR（增量静态再生成）：
// 在 page.tsx 中添加
export const revalidate = 60; // 60秒后重新验证
更新日志
2025-12-21
- 🎉 切换到服务端渲染（SSR）
- ✨ 无需手动运行脚本
- ✨ 添加文档立即生效
- ✨ 简化工作流程
- ✨ 更好的开发体验
之前版本
- ✨ 实现文档自动扫描
- ✨ 添加文档分类功能
- ✨ 创建文档列表展示页面