用Git+Markdown构建课程手册：告别版本地狱，实现自动化发布

第 7 版《课程手册.pdf》被拖进课程群的时候，我坐在工位上沉默了十秒钟。往前翻聊天记录，第 5 版、第 6 版、第 6.1 版，再加上课程主页上一份和 PDF 内容对不上的 HTML，整个教学团队已经有四个“唯一正确版本”。上一学期我们踩过最大的坑，就是有三位老师分别按三个版本批改了同一份作业，最后团队内部花了整整一个半小时去对齐评分标准。我记得有老师半开玩笑说：“这本手册就是个活文档，但活得有点乱。”我心里清楚，课程手册作为一门课的“总章”，正在变成所有人都不愿意碰的东西。

Coursebook 这个项目，就是被这种“版本地狱”逼出来的内部工具。思路很简单：用 Markdown 写内容，用 Git 管历史，用 Python 脚本生成一份带导航、可打印、手机上也好看的单文件 HTML，然后自动部署到静态托管上。核心代码只有几百行，却实实在在跑通了两学期，成了整个教学组每天都在用的基础设施。这篇文章不是完整的项目教程，而是把这套系统从选型、文档结构、构建细节到协作方式的完整思路讲一遍，也把踩过的坑和做过的取舍一并交代清楚。

1. Coursebook 的诞生：从版本地狱到文档焦虑

1.1 事情是从第 7 版《课程手册》PDF 开始的

上面那个场景并不是个例。传统课程手册的维护路径极其脆弱：一名老师先在 Word 里排好内容，导出 PDF，传到课程群，再在课程主页上传一份。任何一处修改，都意味着重新导出、重新上传、重新在群里＠所有人“以此为准”。于是文件名里的 FINAL 后缀会不断生长，FINAL_v2、FINAL_final、最终版_真的最终，没人能说清哪个版本覆盖了哪个。两位老师同时维护一份手册时，唯一的协作方式就是“你改前半段，我改后半段”，遇到共同负责的一周，只能靠线下沟通硬扛。

课程手册里最容易出错的还不是格式，而是字段漂移。评分权重、作业截止日期、周次安排，这些都是学生和老师都会反复查阅的关键信息。可一旦进入“多版本并存”的状态，这些字段就成了重灾区。有一学期我们甚至出现过同一门课两份手册上作业截止时间相差一天的情况，学生交完作业被系统判逾期，在群里炸了锅。最后查来查去，是因为负责发布的那位老师用了过期模板，而她的本地文件确实是最新版的——但没人知道除了她以外还有谁的手里是那版。

Coursebook 的目标非常朴素：让课程手册像软件代码一样可追溯，像网页一样好读，像表格一样易更新。任何一位老师提出修改，改动都能被记录、被审查、被回滚，学生永远只面对一个最新入口，任课老师又不需要学任何复杂的工具。这个目标听起来不炫，但落地过程里牵扯的细节，比预想多得多。

1.2 翻了一圈现成工具，为什么都不顺手

动手之前，我认真试过四类现成方案，各有各的难受。

第一类是 Word / PPT 协作。门槛最低，但历史版本只存在于本地文件名里。多人同时编辑后合并几乎靠人工比对，而课程手册这种几十页的长文档，在 Word 里调目录、改页码、统一样式，几乎每一种操作都在给未来的维护挖坑。我们组里一位老教师习惯在笔记本上维护“唯一原稿”，每隔两周往课程群转发一次最新版 PDF，其他人永远改不到他那份。

第二类是市面上的在线协作文档。权限和版本回退都有，但课程手册不是一份普通文档，它需要固定的信息结构：课程信息区、教学计划表、评分标准、每周安排、资源链接。在线文档虽然也能排版出类似效果，但每次新增一个栏目都要人工调整格式，导出 PDF 后样式经常崩坏。更关键的是，它要求学生记住“去某某文档平台的某个共享空间找第几个文件”，这种入口太重了。课程手册的入口必须轻到像打开一个网址那样自然。

第三类是学校 LMS 里自带的课程工具。这类系统功能全但普遍很重。一门课要在后台配置十几个模块，涉及管理员权限审核；学期一结束，上一轮课程的页面结构和权限设置往往要全部重建。而且 LMS 的二次开发能力基本为零，想加一个“本周状态标记”这种小功能，都得看平台脸色。

我也考虑过用 Hugo 或 VitePress 这类静态站点生成器做课程站点。方案是可行的，但对普通老师来说，目录、标签、布局这些概念太工程化。课程手册属于典型的“内容简单、结构严格”的文档：内容再多也跑不出大纲、日程、评分、资源、周细五个维度。与其套一个通用站点框架，不如直接按课程场景写个构建脚本把内容约定死，这样老师和我的维护成本都能降到最低。

1.3 技术路线定下来：内容源文件加上构建流水线

对比完所有方案，我给 Coursebook 定了一条非常传统的路线：源文件全部用 Markdown 写，版本管理交给 Git，构建时用 Python 脚本把 Markdown 渲染成单文件 HTML，然后部署到 GitHub Pages 或任意静态托管平台。

选 Markdown，因为对老师足够友好。会写纯文本就能写课程手册：# 是标题，- 是列表，| 可以画表格。没有排版软件的复杂概念，更不需要处理分页符和样式冲突。同时它是纯文本，天然适合 Git，diff 时可以精确到某一行的改动，这在课程手册场景里价值极大。比如“作业截止时间从 3 月 21 日改到 3 月 23 日”，在 Git 历史里就是清清楚楚的一行变更。

选 Git，理由更直接：课程手册最怕的是“没有历史”。很多团队维护手册全靠兵来将挡，出了矛盾谁也说不清当初的稿子长什么样。Git 把一个“说不清楚”变成很自然的事：每个版本的变更都是 commit，有作者、有说明、有时间戳。即使老师不碰命令行，由协调人代提交，学期末也能自动整理出一张完整的变更记录。

构建脚本则是把“内容文件”和“最终成品”之间的桥。内容是一堆散落的 .md 文件，师生看到的应该是带导航、有统一样式、能打印、能在手机上正常阅读的完整页面。我把 Markdown 到 HTML 的三步流水线固定成 build.py，之后所有人都只改内容，不碰布局。学期初跑一次得到整学期骨架，每周更新只改对应周文件，前端后端互不干扰。

事实证明这个选择是对的。Coursebook 迭代了两个学期，我没有重写过任何核心逻辑，只加过检查脚本和模板样式。一个工具的架构能撑住多少真实运行周期，才是对它最好的验证。

2. 内容组织：课程手册不只是一篇长文，而是一套结构

2.1 把一门课拆成“配置、内容、构建”三层

课程手册最常见的失败，是把它当成“一篇比较长的文章”来写。开头背景、中间课程介绍、后面作业标准，全部塞在同一个文件里，越写越长，最终变成没人愿意翻的一堵墙。Coursebook 从一开始就按“配置、内容、构建”三层来组织仓库：

把内容拆成多个小文件，核心原因是为了让每次修改的“粒度”变小。老师想调整第 15 周的实验安排，只需要打开 week-15.md 改动一个段落，commit 信息写“调整第 15 周实验提交方式”。对应 Git 历史干净聚焦，协作检查时目标也非常明确。如果所有内容都在一个大文件里，稍微动一处，就得在一大片改动里找真正变的是什么。

资源文件我单独放在 assets/，不参与 Markdown 渲染。这里有个细节建议：课程手册大部分内容是文本，插入大图反而增加维护成本。老师的照片、操作截图这类，我一般引用现有课程主页的静态资源链接，让源文件保持轻量，build 的过程保持快。

2.2 元数据和正文分离：config 管全局，front matter 管页面

既然拆了文件，就必须有一套机制把散落的内容“缝合”成一个有序整体。Coursebook 用两层元数据：全局配置放在根目录的 config.yaml，单页配置写在 Markdown 文件头部（YAML front matter）。

全局配置管一门课里最大的那些变量：

这份配置的价值，是提供一个“唯一事实来源”。所有页面里的课程代码、教师邮箱、评分权重，构建时都会从这里统一拉取。以前在 Word 时代改一次邮箱要在五六个页面里找五处替换，现在只改配置文件，重新 build 一次就全部同步。这个变化看着不起眼，却消灭了团队里大量“你邮箱写错了”这种无效沟通。

单个 Markdown 文件的 front matter 只负责两件事：本页在整体结构里的位置，以及导航上显示什么名字：

weight 字段用于排序，这是一个踩过坑之后才确定的方案，原因稍后展开。type 字段区分内容性质，overview、syllabus、week 在最终页面上会有微小的展示差异。比如 syllabus 会在目录树里默认展开为表格，week 则会展示状态标记。

2.3 每周计划模板化：16 周课程怎么拆才好用

课程手册里使用频率最高、结构也最规范的部分，是“每周计划”。几乎每门课都会按周组织主题、阅读、作业和截止时间，但这些内容在不同老师的笔下格式千差万别。Coursebook 为每周准备一个独立文件，并约定一套固定模板：

固定模板的意义在于降低心智负担。老师在第 6 周只想改一下“课堂安排”，不需要想内容该放在哪个位置，模板已经框住了；学生快速扫一眼也知道该从哪里获取信息。以前 Word 时代每周计划的格式换一个老师就可能换一种风格，现在全组遵循同一模板，页面整齐很多。

模板化最大的阻力来自“老师觉得受限”。我的应对方式是允许在模板内加自定义小节，只要不破坏约定的几个固定栏目，多写“补充阅读”“加分挑战”都支持。结构约束要设在“索引和导航”层面，而不是“句子和表达”层面。学期进行到一半时，我发现周计划文件还有一个额外收获：增加 status 字段后，构建时可以在目录树里自动生成状态标签。planned 表示尚未定稿，published 表示已经确定，updated 表示本周内容有过修订。学生一眼就能看出哪些周的计划可以放心复习，哪些还需等待更新。这个功能纯粹是内容结构化带来的红利，属于设计之初没有预料到的收获。

3. 构建引擎：单文件 HTML 背后值得抠的几个实现

3.1 从 Markdown 到页面的三段式流水线

Coursebook 的 build.py 全程只做三件事：读配置、组装文档树、渲染输出。逻辑稳定紧凑，完整骨架也不到两百行：

我用的 Markdown 扩展只有最常用的几个：tables 对应教学计划表，fenced_code 放代码块，toc 自动生成页内目录，attr_list 允许给标题加自定义 id。一开始我还考虑过 footnotes 扩展，实测发现它生成的锚点在小屏幕上容易重叠，最后放弃了。

流水线的顺序很重要：不能先把所有 Markdown 全部转成 HTML 再去拼导航，因为导航需要前置的 front matter 信息（标题、权重、类型）。所以处理分两遍：第一遍扫文件只提取 YAML 头，第二遍做正文渲染，最后合并输出。这个两遍扫描的方式，换来的是定位 bug 非常容易——出现问题时，要么是 front matter 解析问题，要么是正文渲染问题，判断路径很清晰。

3.2 导航树、锚点与打印友好样式

单文件 HTML 的优势是分发容易，但对阅读体验的要求也相应提高。Coursebook 做了三件事保证体验。

第一，左侧固定导航树。导航树按 weight 排序，条目显示 front matter 里的 title，点击后平滑滚动到对应区域。实现不复杂，但我特别处理了一个细节：当前阅读位置对应的导航条目要明显高亮。学生翻到第 8 周时，左侧“第 8 周”那一项会亮起来，长文档阅读最怕失去“我在哪”的上下文，这一点小交互能显著降低迷失感。

第二，页内锚点。每周页面都通过 toc 扩展生成自己的小目录，允许学生直接跳到“本周目标”“作业”等位置。锚点 id 必须和导航跳转保持同一套命名规则，否则点击会出现落点偏差。我的处理是把所有标题统一 slug 化：中文保留，空格转连字符，去掉标点符号。这个函数很小，但为了兼容中英文混排的标题，我反复测了很多轮。

第三，打印样式。这是被严重低估的需求。即便大家都有手机和电脑，不少老师依然习惯学期初把整本手册打印成纸质版。我用 @media print 单独写了一套黑白报表样式：

隐藏导航、调整表格边框粗细、把链接文字还原成可读 URL。加入打印样式之后，老师要“纸质版手册”的频率明显降低，因为他们自己用浏览器按下打印就能得到一份排版整齐的传统样式。这件事提醒我：任何数字工具，都要认真对待那些“还在用物理媒介”的使用者。

3.3 文件排序、中文混排与特殊字符的坑

这里值得专门记录一下。项目做到一半，我发现 sorted(content_dir.glob("*.md")) 对中文文件名的排序结果在不同操作系统上完全不一致。用 week-01.md 这种命名没问题，可一旦某门课的文件叫“第 1 周.md”，Python 默认调用操作系统的文件名排序，结果在不同平台上各不一样。最稳妥的方案是彻底不依赖文件名排序，统一以 front matter 里的 weight 字段为准。排序逻辑是这样的：

第二个坑是中文混排的阅读体验。Markdown 渲染成 HTML 之后，中英文之间如果没有合适间距，在无衬线字体下会显得很挤。我尝试过引入自动加空格之类的后处理，效果不稳定，最后用 CSS 的 word-break: break-word 配合 text-align: justify 兜底，保证各种屏幕上都稳定可读。排版不是这个项目的主战场，守住“不缺漏、可阅读”的底线就够了。

特殊字符也翻过车。有些老师的讲义里包含 {{、}} 这类符号，比如在代码示例中写 Vue 模板。最初模板引擎会把它当成变量替换符处理，导致整个页面输出错乱。后来我明确规定：变量替换只发生在普通段落里，代码块内的文本一律原样输出。这个教训让我养成了一个习惯：任何自定义文本处理都要考虑“用户的书写意图”，不能因为一个正常字符就把用户的整个页面炸掉。

4. 从一个人改到大家一起改：Git 与自动化质量检查

4.1 Git 不是给程序员用的，但课程手册确实用好了它

一提到让老师用 Git，预期的反应通常是“我们不写代码，学这个干嘛”。我的处理方式是把 Git 隐藏到协作流程后面：老师不进入命令行，他们只需要在同步目录里改 Markdown 文件，由我来负责 commit、merge、tag。真正核心的部分在于 commit 规范和 tag 策略。

我们约定了几条非常简单但好用的规则。第一，每次修改一个文件的最小单元对应一次 commit，提交说明统一按 docs: 调整第 6 周作业截止时间 这种格式写，方便之后直接当更新日志看。第二，学期开始第一天打一个 v1.0.0 的 tag，期中全面修订后打 v1.1.0，期末冻结时打 v2.0.0。tag 就是对外发布版本号，和 config.yaml 里的版本字段互相对照。学生问“现在手册是哪个版本”时，永远有一个清晰的答案。

最惊艳的效果是 git diff。以前老师说“我改了第 3 周的作业”，我收到这句话，脑子里依然对“具体改成什么”一团浆糊；现在直接执行：

屏幕上精确显示哪一行从什么值改成了什么值。老师之间对“截止时间到底哪天”的分歧，一秒内就有确定答案。这个体验让所有潜在反对者都闭了嘴，也让我真正理解了为什么把历史管理做好，收益远大于绝大多数花里胡哨的功能。

4.2 检查脚本：把人工找错误变成自动化扫描

光有版本管理还不够，因为课程手册最常见的错误不是“改坏了”，而是“没改干净”。例如评分标准写着作业权重 20%，教学计划表里却还保留 30%；第 10 周的章节编号和教材目录对不上；外部链接已经 404。人工排查这些琐碎错误极其折磨，于是我在 check.py 里加了几个有针对性的自动化检查。

第一个检查是 front matter 完整性。每个 Markdown 文件必须以 --- 开头，必须包含 title、weight、type 三个字段，缺了就报错。这能拦住最常见的新人失误：复制旧文件改成新内容，却忘了改头部信息。

第二个检查是日期范围一致性。用正则抽取全文所有日期字符串，和 config.yaml 里的学期起止日期比对，超出范围直接报错：

这个检查在学期初价值最大，能拦住把“2024 年日期复制进 2025 年课程”的典型失误。我统计过，检查脚本在第一个学期就拦截了 11 处日期错误，而此前这些错误大概率会被学生发现后反馈到课程群里。

第三个检查是链接健康。最初我尝试在构建时用 HTTP 请求逐一探测所有外链，结果发现不少校园内网资源会拒绝非校园网请求，误报率高得没法用。后来改成只做静态正则提取，把所有可疑链接整理成一个清单，由协调人每周人工过一遍。这个折中方案兼顾了“看到问题”和“不被误报打扰”。

检查脚本同时承担了本地预检和 CI 拦截两种角色。原则很简单：检查不通过，不发布新版本。

4.3 没有审批流，但要有痕迹

课程手册在真实团队里的维护，本质上是一个“无组织有纪律”的过程。我们团队没有设置审批流，毕竟为了改个错别字走一遍工单流程很不现实。但我对所有修改提出了一个统一要求：所有改动要么在单独分支，要么至少是独立文件副本，通过检查后合回主分支，并由协调人统一 commit。

这个流程几乎不需要额外的工具成本，核心是保持仓库里的痕迹完整。如果有两位老师在同一周修改不同段落，Git 能正确自动合并；只有当他们改了完全相同的行时才会冲突。这种冲突通常意味着两人对同一问题有不同意见，正好借 merge 提示推动他们当面把问题说清。

学期末我做了个统计：97 个 commit、27 次版本变更、18 处截止时间修正、5 处评分措辞澄清。这些数字比任何年度总结都有说服力——课程手册不再是学期初固定的一次性文档，而是整个学期里被整个团队真实地共同喂养长大的活文档。

5. 发布自动化与半年运行后的真实反馈

5.1 CI 自动构建：把“记得重新跑一下 build”从流程里抹掉

最初 Coursebook 的构建是手动完成的：改完 Markdown 文件，我本地切到目录执行 python build.py，再把 dist/ 目录推上去。这种模式撑了半个学期后我就烦了，因为团队里所有人都可能改内容，但只有我一个人记着构建。这是个典型的工程问题，解决方案直接套用现成的 CI 工具：

这套流水线的核心不是自动化三个字，而是把“检查、构建、发布”绑定成一个完整动作。任何一次对主分支的推送，都会先过质量检查，再重新生成站点，最后部署到静态托管。版本号由 CI 在成功构建后自动打 tag，学生每次访问的都是最新版。老师完全不关心部署流程，只需要知道“我改完提个 commit 就行”。

自动化真正体现价值是在第一个月的某次推送里。check.py 拦截了一篇周计划的日期超出学期范围的问题——有老师把第 6 周的计划写成了春假期间。如果按照旧流程，这个错误大概率要等学生发现“怎么假期还要上课”才会暴露；现在它在上线之前就被无声无息地拦住了。

5.2 老师与学生的反馈里，最意外的增长点是“状态标记”

Coursebook 上线两个学期后，收到的反馈比我预想中坦诚得多。老师这边对工具的需求集中在三处：希望本地预览更快、希望模板可以加自定义模块、希望导出 Word 格式。前两个通过调整脚本和模板解决，第三个我至今没有做。理由在于导出 Word 意味着要维护一套和 HTML 完全不同的格式层，工作量会翻倍，而真实需求往往只是“给教学秘书发一个可编辑的表格”，这个用 HTML 页面直接复制粘贴也能基本满足。

学生侧反馈则集中在对周计划状态标记的认可上。不少学生告诉我，看到某一周状态是 published，会安心地按计划复习；看到 updated，会主动去检查是不是截止时间变了。这个功能最初只是顺手添加的，却意外成为课程手册使用率上升的关键。从这件事我学到的经验是：课程的透明性不体现在多写几段文档上，而在信息结构里显式地刻画出“当前是什么状态”。人天然会对一个处于“未定稿”状态的内容保持警惕，这一点做教育工具时必须尊重。

5.3 下一阶段想补的三个方向

眼下 Coursebook 对我来说，已经从临时脚本变成了每天都在用的基础设施，但它依然有明显的边界。接下来我个人想补三块：

第一，把周计划的 status 状态升级成主动通知。当某周的状态从 published 变成 updated 时，自动在课程群里推一条变更摘要，省得学生反复刷新页面。

第二，支持按单元批量生成。期中结束后，后 8 周的计划模板需要整体刷新，如果能在 build.py 里加一个按范围批量重置的命令，就不用挨个打开文件手工操作了。

第三，给构建脚本加一个 --pdf 参数，调用浏览器的无头模式把单页 HTML 渲染成 PDF。这能彻底解决打印版的自动化生成问题，也顺便把“老师想要 Word”的需求消解掉一大半。

这三块都不是必须本学期完成的事情。它们的意义更多在于验证 Coursebook 这套“结构化内容 + 构建产物”的思路还能长出多少新东西。对一个不过两百行 Python 的项目来说，这个生长空间已经相当够用了。