跳转至

文档模板与写作规范

基础元数据

  • 分类:附录
  • 落地难度:—
  • 必备原料:无
  • 是否需要特殊工具:否
  • 适用场景:贡献指南
  • 标签:#规范 #模板 #贡献

一、统一文档模板

所有技术文档必须遵循以下结构(可直接复制修改):

# 文档标题(技术名 + 核心内容)

## 基础元数据
- 分类:农业增产 / 医疗防疫 / 日用化工 / 冶金锻造 / 建筑机械 / 测绘数理 / 长期工业 / 避坑合集
- 落地难度:当日落地 / 1个月可量产 / 完整产业链(数年)
- 必备原料:xxx
- 是否需要特殊工具:是(列出)/ 否
- 适用场景:生存致富 / 官府建功 / 基建改造 / 医疗救人
- 标签:#低成本手工 #高收益 #无电力

---

## 一、现代底层原理(简化)
用初中生能懂的语言讲清科学逻辑,一句话总结加粗放在段尾。

## 二、古代实操完整步骤
分步写清,每步可执行;涉及危险操作必须写"判断标准"和"失败表现"。

## 三、优势对比(对比古代现有技术)
3-5 条,写清"比什么、强在哪、强多少"。

## 四、局限性与短板
3-5 条,诚实列出资源、风险、政治、季节限制。

## 五、拓展延伸配套技术
- 关联文档跳转(相对路径)+ 一句话说明关联点
- 最后一条固定链接 → [落地总路线](roadmap.md)

二、章节写作要点

章节 核心要求 常见错误
元数据 与正文严格一致,难度取值只用三种 自造难度等级
原理 先讲"为什么",再给一句总结 直接抄教科书定义
实操 每一步可照做,含验收标准 跳步、依赖现代工具而不注明
优势 有具体倍数或对比物 空泛地说"效果好"
局限 包含至少一条政治/伦理/安全风险 只写技术短板不写环境约束
拓展 链接必须真实可达 链接断裂、路径写错

三、危险内容红线

  1. 涉及火药、酒精蒸馏、麻醉药品的文档,必须在文档开头用 !!! warning 声明块提示风险,并在正文中写明安全规程与法律风险
  2. 所有"不可行"结论必须给出理由,归入避坑合集而非正文
  3. 医疗内容不得给出可能致死的确定性方案,麻醉、手术类文档要明确"供设定参考,现实中请勿尝试"

四、命名与路径规范

  1. 文件名:小写英文 + 连字符,放在对应分类目录下,如 docs/daily-chemistry/paper-making.md
  2. 相对链接:同目录直接 xxx.md,跨目录用 ../category/xxx.md
  3. 图片:放 docs/assets/,命名 分类-主题-序号.png,并更新 docs/assets/README.md 说明
  4. 标题:文档第一行 # 标题与导航条目可以不同(导航用短名)

五、简易视频讲解(文档开头必备)

每篇技术文档在"基础元数据"分隔线之后、"一、现代底层原理"之前,必须插入一个纯 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>

写作要点:

  1. 帧数 4-6 帧为宜(类名 vid-n4~vid-n6,--vid-dur = 帧数 × 5 秒)
  2. 第一帧固定为"核心原理",中间帧对应第二节实操步骤(每帧 ≤ 40 字),最后一帧为成品或价值
  3. HTML 块前后各留一个空行,块内不要写 Markdown 语法
  4. 计数器用 01 / 05 零填充格式,与帧数一致
  5. 避坑类文档:第一帧讲"看似可行的点",最后一帧给出"为何不可行"结论

六、新增文档 Checklist

  • [ ] 遵循统一文档头部元数据模板
  • [ ] 在元数据分隔线后插入"简易视频讲解"动画(见第五节)
  • [ ] 在 mkdocs.yml 的 nav 中添加导航条目
  • [ ] 文档内添加跨文档跳转链接(../ 相对路径),至少 3 条
  • [ ] 首页 docs/index.md 添加对应知识卡片
  • [ ] 涉及相关技术时更新 落地总路线 的阶段表格
  • [ ] 涉及图片时在 docs/assets/ 下放置,并更新 docs/assets/README.md
  • [ ] 危险内容已加 !!! warning 声明
  • [ ] 本地 mkdocs build 无 WARNING

七、RAG 切片约定

为方便 AI 向量知识库导入,请额外遵守:

  1. 每个二级标题(##)下不超过 1200 字,超过就拆分小节
  2. 关键术语第一次出现时用通俗语言解释
  3. 元数据中的"落地难度"会在检索时用作权重标签,务必准确

详见仓库 rag-config/ 目录的导入指南(GitHub 仓库内查看)。