文档站维护指南

本文说明 docs-site/ 的结构、写作规则和验证方式，供维护者在新增模块文档、架构说明、API 参考和部署指南时使用。

文档站边界

文档站是一个 Docusaurus 3 项目，位于仓库根目录的 docs-site/：

路径	作用
docs-site/docs/	正文文档，按 Docusaurus doc id 组织
docs-site/sidebars.ts	左侧导航配置
docs-site/docusaurus.config.ts	站点标题、导航栏、页脚、Markdown 策略和部署地址
docs-site/package.json	本地开发、构建、类型检查和 Cloudflare Pages 命令
.github/workflows/deploy-docs-cloudflare.yml	main 分支上文档变更后的自动构建与发布

默认语言是 zh-Hans，文档内容应优先使用中文。除非目标页面已经是英文，新增页面不要混用中英文标题。

维护流程

新增或改写文档时，按这个顺序处理：

1. 先读相关代码、AGENTS.md 和 .github/guidelines/。
2. 判断页面类型：入门、模块指南、架构说明、API 参考、配置说明、部署说明或排障说明。
3. 在 docs-site/docs/ 下选择合适目录。
4. 新建 Markdown 页面并补齐 front matter。
5. 如果页面需要出现在导航中，同步更新 docs-site/sidebars.ts。
6. 在 docs-site/ 目录运行构建或类型检查。

cd docs-site
pnpm typecheck
pnpm build

package.json 中的本地开发命令是：

pnpm dev

它会以 docusaurus start --port 4300 启动文档站。

页面放置规则

文档类型	推荐目录	示例
新人入门、配置、部署	docs-site/docs/	quick-start.md、configuration.md、deployment.md
公共基础设施	docs-site/docs/building-blocks/	web.md、infrastructure.md
架构专题	docs-site/docs/architecture/	api-layering.md、common-attachment.md
业务模块	docs-site/docs/modules/<module>/	modules/cmskit/architecture.md
FreeKit 基础库	docs-site/docs/freekit/	core.md、modularity.md
Docker 运维	docs-site/docs/docker/	Docker-MySql.md、Docker-Nginx.md
源码镜像或专项分析	docs-site/docs/source/	settings.md、validation-strategy.md

不要把模块文档放到顶层目录，也不要把架构专题混到模块目录里。一个页面只解决一个主题。

写作结构

模块文档推荐使用这个结构：

---
title: 模块名称
sidebar_label: 模块名称
---

# 模块名称

## 模块定位

## 目录结构

## 核心实体

## 应用服务

## API 与权限

## 配置项

## 启动与注册

## 扩展点

## 验证方式

## 相关源码

架构文档推荐使用这个结构：

---
title: 架构主题
sidebar_label: 架构主题
---

# 架构主题

## 解决的问题

## 组件关系

## 运行流程

## 依赖方向

## 扩展点

## 约束与风险

## 相关源码

API 参考应优先说明真实路由、权限、请求 DTO、响应 DTO 和错误行为。不要只复制 Controller 方法名。

代码依据

文档结论必须能回到源码。写文档时优先引用这些入口：

主题	入口
模块注册	src/Services/Host/FreeKit.DI/E.cs
主 API 宿主	src/Services/Host/FreeKit.Host/Program.cs
Job 宿主	src/Services/Host/FreeKit.Job.Host/Program.cs
Message 宿主	src/Services/Host/FreeKit.MessageHandler.Host/Program.cs
模块启动	src/Services/**/**ModuleStartup.cs
Controller	src/Services/**/Controllers/*.cs
应用服务	src/Services/**/Application/**/*.cs
DTO/接口	src/Services/**/Application/**/Contracts/*.cs
权限常量	src/Services/**/Contracts/*Permissions.cs
测试	src/Test/FreeKit.Tests/**/*.cs

如果源码和旧文档冲突，以源码为准，并在改文档时删除过期说法。

图示规则

复杂运行关系优先使用 Mermaid。模块依赖适合 flowchart，时序流程适合 sequenceDiagram。

flowchart LR
    Host[FreeKit.Host] --> DI[FreeKit.DI]
    DI --> Identity[Identity]
    DI --> Platform[Platform]
    DI --> CmsKit[CmsKit]
    DI --> Member[Member]

图示只表达关键关系，不要把所有类都塞进一张图。

使用 AI 写文档

本仓库已经安装项目级 Skill：

.github/skills/code-documentation-docs-architect/SKILL.md

需要 AI 编写或改写文档时，可以这样描述任务：

使用 code-documentation-docs-architect 写 docs-site 文档。
目标读者：新接手该模块的后端开发。
文档类型：模块指南。
请先阅读相关源码、AGENTS.md 和 .github/guidelines/，再修改 docs-site/docs/ 下的 Markdown。
要求：结论必须来自源码；新增页面要更新 sidebars.ts；示例命令要能运行；不要写营销文案。

如果是架构文档，把“文档类型”改成“架构说明”，并要求包含 Mermaid 图和相关源码列表。

发布链路

文档站在 main 分支发生这些路径变更时触发 Cloudflare Pages 发布：

• docs-site/**
• .github/workflows/deploy-docs-cloudflare.yml

工作流会在 docs-site/ 下执行：

pnpm install --frozen-lockfile
pnpm build

构建产物通过 Wrangler 发布到 Cloudflare Pages 项目 freekit-pro。