文档
**文档（Document）**模块是社团的知识库：规范、手册、教程、资料整理都沉淀在这里。
它按分类组织，正文用 Markdown 编写，也支持从 .md、.markdown 或 .txt 文件导入。
- 📚 文档列表：https://gfssm.butian.club/docs
- 文档详情：
/docs/[slug]
查看文档对所有成员开放。新建、编辑文档与分类属于管理动作，
当前代码要求管理员身份；种子权限元数据将它标记为 documents:manage。
详见角色与鉴权。
浏览与查阅
打开 /docs 就是文档列表。文档通过**分类（DocumentCategory）**组织，
你可以按关键词和分类筛选，并按更新时间、创建时间或标题排序；点击标题进入详情页
/docs/[slug] 阅读完整正文。
- 每篇文档都有一个
slug（地址里的可读标识），详情页地址稳定，方便收藏和分享。 - 正文以 Markdown 渲染，排版清晰，支持表格、任务列表、代码块等。
把常用的规范或手册加到浏览器书签，或直接分享 /docs/[slug] 链接给队友，
比口头转述更准确。
发布状态：草稿与已发布
文档有发布状态，分为两种：
| 状态 | 含义 |
|---|---|
| 草稿 | 正在编写、尚未公开，供作者继续打磨 |
| 已发布 | 正式对成员开放阅读 |
草稿用于内容还没定稿的阶段；确认无误后再发布，避免半成品内容误导成员。 状态的切换由有编辑权限的管理员操作。
编辑文档（管理员）
新建和编辑文档需要管理员权限（documents:manage），而且就在文档页面（/docs）内完成：
顶部有上传文档 / 新建文档按钮，每篇文档卡片上有编辑 / 删除入口，管理员还能看到
普通成员看不到的草稿。当前编辑对话框提供 Markdown 文本框，保存后在详情页查看渲染结果；
它没有分栏实时预览。
编写文档的一般步骤：
- 进入文档模块，新建文档或打开已有文档编辑。
- 填写标题、选择所属分类。
- 在正文框用 Markdown 撰写内容；需要检查渲染效果时保存后打开详情页。
- 先保存为草稿，反复打磨。
- 内容定稿后切换为已发布，成员即可阅读。
文档正文支持 GitHub 风格 Markdown（GFM，remark-gfm）：表格、任务列表
（- [ ] / - [x]）、代码块、链接等都可使用，适合写规范和技术文档。
分类如何维护
分类（DocumentCategory）用来把文档归类整理，让知识库结构清晰、易于查找。
当前没有独立的分类管理页：管理员在新建或编辑文档时填写分类名称，系统会按名称生成
slug，自动复用已有分类或创建新分类；留空则文档进入「未分类」。
- 规划分类时建议贴合社团实际，例如「参赛规范」「技术手册」「资料汇总」等。
- 修改文档的分类字段会按生成后的
slug复用或创建分类。当前没有独立的批量重命名、 合并或删除分类入口。
导入与分享到聊天
- 列表页的上传文档会把
.md、.markdown或.txt文件直接创建为已发布文档， 标题取第一个一级标题，找不到时使用文件名；文件上限为 2 MB，并默认归入「未分类」。 - 新建对话框也可先导入上述文本文件，再检查标题、分类、摘要、正文和发布状态。
- 文档详情页可把标题和站内链接分享到聊天；上传的源文本会成为文档正文，并不会作为 可下载附件保留。
写好文档的建议
- 标题清晰：让人一眼知道这篇讲什么。
- 善用结构：用多级标题、列表、表格拆分内容，避免大段文字。
- 保持更新：规范变了要及时改文档；过时内容比没有更容易误导人。
- 先草稿后发布：没定稿的内容留在草稿，别急着发布。