文档模板与写作规范¶
基础元数据¶
- 分类:附录
- 落地难度:—
- 必备原料:无
- 是否需要特殊工具:否
- 适用场景:贡献指南
- 标签:#规范 #模板 #贡献
一、统一文档模板¶
所有技术文档必须遵循以下结构(可直接复制修改):
# 文档标题(技术名 + 核心内容)
## 基础元数据
- 分类:农业增产 / 医疗防疫 / 日用化工 / 冶金锻造 / 建筑机械 / 测绘数理 / 长期工业 / 避坑合集
- 落地难度:当日落地 / 1个月可量产 / 完整产业链(数年)
- 必备原料:xxx
- 是否需要特殊工具:是(列出)/ 否
- 适用场景:生存致富 / 官府建功 / 基建改造 / 医疗救人
- 标签:#低成本手工 #高收益 #无电力
---
## 一、现代底层原理(简化)
用初中生能懂的语言讲清科学逻辑,一句话总结加粗放在段尾。
## 二、古代实操完整步骤
分步写清,每步可执行;涉及危险操作必须写"判断标准"和"失败表现"。
## 三、优势对比(对比古代现有技术)
3-5 条,写清"比什么、强在哪、强多少"。
## 四、局限性与短板
3-5 条,诚实列出资源、风险、政治、季节限制。
## 五、拓展延伸配套技术
- 关联文档跳转(相对路径)+ 一句话说明关联点
- 最后一条固定链接 → [落地总路线](roadmap.md)
二、章节写作要点¶
| 章节 | 核心要求 | 常见错误 |
|---|---|---|
| 元数据 | 与正文严格一致,难度取值只用三种 | 自造难度等级 |
| 原理 | 先讲"为什么",再给一句总结 | 直接抄教科书定义 |
| 实操 | 每一步可照做,含验收标准 | 跳步、依赖现代工具而不注明 |
| 优势 | 有具体倍数或对比物 | 空泛地说"效果好" |
| 局限 | 包含至少一条政治/伦理/安全风险 | 只写技术短板不写环境约束 |
| 拓展 | 链接必须真实可达 | 链接断裂、路径写错 |
三、危险内容红线¶
- 涉及火药、酒精蒸馏、麻醉药品的文档,必须在文档开头用
!!! warning声明块提示风险,并在正文中写明安全规程与法律风险 - 所有"不可行"结论必须给出理由,归入避坑合集而非正文
- 医疗内容不得给出可能致死的确定性方案,麻醉、手术类文档要明确"供设定参考,现实中请勿尝试"
四、命名与路径规范¶
- 文件名:小写英文 + 连字符,放在对应分类目录下,如
docs/daily-chemistry/paper-making.md - 相对链接:同目录直接
xxx.md,跨目录用../category/xxx.md - 图片:放
docs/assets/,命名分类-主题-序号.png,并更新docs/assets/README.md说明 - 标题:文档第一行
#标题与导航条目可以不同(导航用短名)
五、简易视频讲解(文档开头必备)¶
每篇技术文档在"基础元数据"分隔线之后、"一、现代底层原理"之前,必须插入一个纯 CSS 自动播放的流程讲解动画(播放器样式已内置于 css/ancient.css,无需额外配置):
<div class="vid-player vid-n5" style="--vid-dur: 25s;">
<div class="vid-header">
<span class="vid-dot"></span>
<span class="vid-title">▶ 简易视频讲解 · 全流程短标题</span>
<span class="vid-hint">自动播放</span><span class="vid-btn" data-label="⏸ 暂停" role="button" tabindex="0"></span>
</div>
<div class="vid-stage">
<div class="vid-slide">
<div class="vid-icon">🧪</div>
<div class="vid-step-title">核心原理</div>
<div class="vid-step-desc">一句话讲清为什么可行(对应第一节原理)</div>
<div class="vid-counter">01 / 05</div>
</div>
<!-- 中间 3-4 帧:第二节的关键实操步骤,每帧一句 -->
<div class="vid-slide">
<div class="vid-icon">📜</div>
<div class="vid-step-title">成品 / 价值</div>
<div class="vid-step-desc">最终产物或核心收益一句话</div>
<div class="vid-counter">05 / 05</div>
</div>
</div>
<div class="vid-footer"></div>
</div>
写作要点:
- 帧数 4-6 帧为宜(类名
vid-n4~vid-n6,--vid-dur= 帧数 × 5 秒) - 第一帧固定为"核心原理",中间帧对应第二节实操步骤(每帧 ≤ 40 字),最后一帧为成品或价值
- HTML 块前后各留一个空行,块内不要写 Markdown 语法
- 计数器用
01 / 05零填充格式,与帧数一致 - 避坑类文档:第一帧讲"看似可行的点",最后一帧给出"为何不可行"结论
六、新增文档 Checklist¶
- [ ] 遵循统一文档头部元数据模板
- [ ] 在元数据分隔线后插入"简易视频讲解"动画(见第五节)
- [ ] 在
mkdocs.yml的nav中添加导航条目 - [ ] 文档内添加跨文档跳转链接(
../相对路径),至少 3 条 - [ ] 首页
docs/index.md添加对应知识卡片 - [ ] 涉及相关技术时更新 落地总路线 的阶段表格
- [ ] 涉及图片时在
docs/assets/下放置,并更新docs/assets/README.md - [ ] 危险内容已加
!!! warning声明 - [ ] 本地
mkdocs build无 WARNING
七、RAG 切片约定¶
为方便 AI 向量知识库导入,请额外遵守:
- 每个二级标题(
##)下不超过 1200 字,超过就拆分小节 - 关键术语第一次出现时用通俗语言解释
- 元数据中的"落地难度"会在检索时用作权重标签,务必准确
详见仓库 rag-config/ 目录的导入指南(GitHub 仓库内查看)。