从教学设计到工程实践：用Markdown与Git构建可持续迭代的课程书工作流

1. Coursebook 不是电子书：先理解它到底在解决什么问题

聊到“coursebook”这个词，很多人的第一反应是“电子教材”“在线课件”之类的东西。但我在实际折腾课程资料整理的头两年里，最大的教训恰恰是：coursebook 不是把 Word 讲义转成 PDF 就算完成了，它真正要解决的问题，是让一门课的知识资产从“散落在个人电脑里的零碎文件”变成“一套可持续迭代的结构化产物”。

这么说可能有点抽象。回忆一下大多数人备课的常见状态：一个课程文件夹里躺着十几个版本的 PPT、三五份 Word 讲义、若干次更新的习题答案、历年试卷和参考答案混在一起，文件名后缀从“最终版”到“最终版2”再到“真的最终版”。我见过不少同行，光是找一份去年用过的案例材料就要翻五分钟，更别提把一门课完整交给另一位老师时那种交接灾难。

coursebook 的核心价值，恰恰是把这门课当成一个有生命的工程产品来管理：大纲、正文、案例、习题、评估标准、版本记录，全部以统一格式沉淀下来，每学期迭代一次而不是推倒重做一次。它不一定要用特别复杂的工具，但一定要改变你组织课程内容的方式。

这几年我把手头两门核心课完全迁移到了这套思路里，踩了不少坑，也沉淀了一些很顺手的做法。这篇文章就把整套工作流和踩坑过程完整写出来，适合正在教课、想做在线课程、或者单纯想把手头零散教学内容整理成体系的人。无论你是独立讲师、高校老师，还是企业内部培训负责人，这套方法论都能直接搬过去用。

1.1 从“讲义+PPT”到“单一事实来源”

传统备课的信息流通常是这样的：先写大纲，然后做 PPT，再根据 PPT 写讲稿，最后把案例、习题、参考链接散落在各个地方。问题在于，同一门课的同一知识点，可能在 PPT 里是一个讲法，在讲义里是另一个详略程度，在习题答案里又是第三个版本。学生问起来的时候，你自己都不确定哪个才是“标准说法”。

coursebook 要求你建立单一事实来源（Single Source of Truth）：知识点的完整解释、案例、图表、习题，全部先写在课程正文里，PPT 和课堂演示只是从这份正文中抽取出来的“切片”，而不是独立存在的另一套内容。这个转变听起来不难，实际上需要很强的克制力——因为做 PPT 的时候，你总想临时改个说法、加个例子，改完又不同步回正文，久而久之单一来源就名存实亡了。

我的做法是给每门课立一条规矩：一切内容先入课程书，PPT 必须是课程书的子集。课堂上临时发挥的内容，课后 24 小时内补回对应章节，否则它就不算数。坚持一个学期之后，课程资料的混乱程度会肉眼可见地下降。

1.2 谁需要这门手艺

如果你只是教一门两三个月的短期课，那或许不需要上这套系统。课程书工作流的收益和课程的生命周期强相关：同一门课要开三学期以上，或者内容更新频率较快，或者需要多名老师协作授课，或者想把课程打包成产品对外输出——满足任意两条，就值得认真研究 coursebook 的搭建方法。

我见过一个极端的正面案例：有位做企业培训的朋友，把一门销售技巧课拆成了七个模块、一百多个知识点，每个知识点都配了案例库和对应的练习。新讲师入职后对着 coursebook 跟读两周就能上台，客户定制课件时直接从模块库中组合，三天交付一套定制版。那已经不是备课了，那是在经营一套课程资产。这套逻辑放到高校教学、在线教育、技术训练营里，同样成立。

2. 设计层：用模块化思维拆解课程结构

很多人一上来就急着写内容，这是 coursebook 项目最大的坑。课程书不是教材的简单搬运，它首先是一个信息架构问题：你想让学生在走出课堂时带走什么？哪些知识必须形成长期记忆，哪些只需要混个脸熟？这些问题的答案，应该决定目录，而不是倒过来。

2.1 先写结果，再写过程：从学习目标反推目录

拿到一门课，我做的第一件事是写“课程结果清单”。比如一门数据分析入门课，结果清单可能是：

• 学生能独立完成一份包含数据清洗、可视化、结论陈述的分析报告
• 学生能解释常见统计指标的适用条件和局限性
• 学生能识别实际案例中 3 类以上典型的分析误导手法

这些结果写清楚之后，课程的每个章节才有了存在理由。章节不是为了“知识的系统性”而存在，而是为了让学习者最终能做到这几点。这个逻辑听起来像教育学的老生常谈，但真正落实到目录层面的人少之又少。

具体到 coursebook 的设计上，我会把目录做成两层嵌套。第一层是模块（Module），对应课程的一个能力目标；第二层是课时（Lesson），对应一次可以独立完成的学习单元。每个课时内部再拆成若干个知识点（Topic）。这样三层结构的好处是：调整任何一层都不会牵动全局，换学期、换班级时只增删模块，而不用重写全书。

2.2 模块、课时、知识点的三层切分

给你看一个实际例子。一门“Python 编程基础”课，模块层是四块：语言基础、数据处理、程序组织、项目实战。每个模块下分四到五课时，比如“程序组织”模块下分为函数、模块与包、异常处理、调试技巧四堂课。

课时层往下，才是真正写内容的地方。每个知识点通常不超过 3 页阅读量，配套一个案例或一道题。我给自己定的标准是：一个知识点只讲一件小事，说透、配例、练习题直接锚定这个知识点。这样做教学设计和内容编排都非常舒服，因为粒度足够细，后期重组课程的灵活性远大于传统“一章接一章”的教材结构。

阶段性地看，这个三层拆解本身也是在帮老师做减法。很多课程内容冗余的根源不是老师讲得太多，而是没有统一的知识点粒度标准——有些地方三页讲一个概念，有些地方一个例子占了三页。统一粒度之后，哪些内容可以压缩、哪些需要扩充，对比非常直观。

2.3 关于“最小可发布单元”的取舍

在课程书设计里，我强烈建议定义清楚“最小可发布单元”。最短粒度太细，比如精确到某个代码片段，会导致发布频率失控；太粗，比如整个模块，又不利于快速交付阶段性成果。以大多数高校和企业培训课程来看，一次课时（Lesson）作为最小可发布单元是比较合适的选择。

为什么不是整章或者整个模块？因为一次课时通常对应一到两周的学习节奏，内容量适中，能独立形成一个完整的“输入→练习→输出”闭环，也方便做版本历史记录。这个粒度定的好处是，哪怕某学期临时停掉半个模块，已经发布的部分依然可以正常使用，不会出现“教材只写了一半”的尴尬。

设计层的最后一个建议：所有模块描述都写成“学生能做什么”，而不是“老师讲什么”。我在早期版本里写得全是“本章介绍 Python 的基本数据类型”，后来发现这种描述对后续迭代没有任何指导意义。改成“学生能根据数据类型特性选择合适的容器存储数据”之后，配套习题和案例的编写方向立刻清晰了很多。

3. 工程层：纯文本工作流的真正威力

如果说设计层决定了 coursebook 的“骨架”，工程层就是决定它能不能长期运转的“血脉”。这里涉及一个核心选型问题：到底用什么工具来承载课程内容？我个人的答案是：放弃 Word，全面转向纯文本 + Markdown。这个选择在介绍完工程细节之后，你可能才会真正理解背后的逻辑。

3.1 为什么选择 Markdown 而不是 Word

Word 最大的问题不在于不好用，而在于它是“排版思维”而非“结构思维”。你在 Word 里写二级标题和三级标题，靠的是肉眼判断和手动格式刷；而同一份内容换到 Markdown 里，一级标题就是 #，二级标题就是 ##，结构一目了然，程序也能准确解析。

Markdown 的优点具体来说有三点：

• 格式与内容分离：相同的 .md 源文件，可以通过不同模板导出为 PDF、网页、EPUB 甚至幻灯片，排版问题交给模板而不是手工处理。
• 版本差异透明：因为源文件是纯文本，对比两个版本之间到底改了什么，是极其自然的事情，这一点后面讲 Git 协作时会体现出巨大价值。
• 长期可读性：Markdown 本质是带少量标记的纯文本文件，十年后哪怕工具生态全变了，文件依然可以用任何文本编辑器打开并保留全部内容。

当然，Markdown 也不是没有问题。表格处理相对麻烦，大量复杂公式的排版不如 LaTeX 优雅。这两个问题后面会专门聊。但就课程书的绝大多数场景而言，Markdown 的收益远大于付出。

3.2 目录与文件命名规范

工程层最容易被忽略却又最能体现体系感的，是文件组织方式。我目前用的目录结构长这样：

这里有几条不成文的规矩：

1. 模块文件夹用数字前缀，确保排序稳定，加新模块时不用重排所有编号。
2. 文件名用小写字母 + 连字符，避免空格和中文文件名带来的跨平台路径问题。
3. 大纲文档独立于正文，单独放在 00-plan 下，因为它是规划的产物，不是课程内容的组成部分。
4. 所有图片和附件统一放进 assets 目录，正文中只引用相对路径。

这套规范一旦定下来，基本上就是终身使用，尽量少改动。我在中途改过一轮命名规则，结果维护脚本和已发布版本的链接全部受影响，耗时比省下来的还多。所以这里也给一个实操建议：文件命名规范尽量一次想清楚，哪怕前期多花半天都值得。

3.3 用 Pandoc 一键导出 PDF/EPUB/网页

纯文本工作流最重要的基础设施就是导出管线。我选的是 Pandoc，它能读 Markdown 源文件，输出 PDF、docx、EPUB、HTML、LaTeX 等多种格式。核心逻辑是：源文件永远只有一套，输出物全部是临时产物，随用随生成。

一个非常常用的命令大概是这样的：

这条命令会把整本课程书编译成带目录的 PDF，中文字体用 Noto Serif CJK SC，页面边距 2.5 厘米。XeLaTeX 引擎是我用下来对中文支持最稳定的方案，第一次配置有点折腾，但配好之后就是一条命令的事。

导出 EPUB 的用途则在于学生可以在平板、手机、阅读器上查看，阅读体验比 PDF 在手机上缩放更好。

网页端我一般用静态站点生成器搭配一个简易的主题，比如 MkDocs 或 VuePress，配置一个入口文件指向 Markdown 目录，就能自动生成带侧边栏导航的在线课程网页。学生端体验和翻书完全不一样，方便按关键词检索，这对大篇幅的课程书来说很重要。当然，这个生产链路不是万能钥匙。涉及大量复杂公式的课程，我目前还是保留 LaTeX 作为最终排版方案：Markdown 源文件里嵌入 LaTeX 数学公式，Pandoc 负责把公式正确翻译到 PDF 中。这个方案兼容性很好，我两门理工科课程都跑的这条管线。

3.4 图表与公式的处理建议

课程书里没有配图，阅读体验会很干。但工程上图片管理恰恰是最容易翻车的一环。我强烈建议：所有图片必须存放在 assets 目录中，用相对路径引用，且命名要有语义化。拒绝“图1.png”这类命名，因为两轮迭代之后你根本不知道它是什么。

画流程图的方案上，我推荐使用代码绘图的文本化方案。之所以这么做，是因为图形一旦以位图形式保存，改一处文字就得重新画整张图；而文本化描述图改起来就非常方便。硬件设备之间的接线关系、软件模块之间的调用关系、教学过程中的步骤流程，用文本化描述都能表达得很好。

公式处理上，因为课程跨度中有不少数理内容，我的习惯是统一用 LaTeX 语法写行内和块级公式。这两个语法规则完全可以提前给老师们发一页速查表，几天就上手了。真正难的地方在于处理公式在导出 PDF 时偶尔出现的渲染错位——这时用 --mathjax 参数导出网页版基本能绕开这类问题。

4. 迭代层：版本控制与多人协作

课程书不是写完就完的静态文档，它每一学期都在更新。传统方式里，“更新”意味着另存为一个新文件，而真正科学的做法是引入版本控制。看到这里可能有人会打退堂鼓：我又不是程序员，搞什么 Git？但说句实话，版本管理是整个 coursebook 体系最值得投入的环节。

4.1 Git 不是程序员的专利

Git 确实诞生于程序员社区，但它本质上是跟踪文本文件修订历史的工具，而课程书恰恰是结构化的文本文件集合。把人话翻译成结论就是：每当你修改课程书的某个知识点，Git 都会记录这一行是从哪一条旧行改过来的，什么时间、谁改的、为什么改，全部有迹可循。

我举一个具体到能让每个老师都心动的例子：上学期期末，一位选课学生发邮件指出第八章有一道习题的题干表述存在歧义导致他理解偏差。你翻开习题原文，确实有歧义，于是修改。这时候还需要保留一份修改前版本吗？传统思路是另存一个“第八章修改版2.docx”，而用了 Git 之后，你只需要在改完后写一句提交说明“修订第八章习题题干歧义”，旧版本就永久保留在历史记录里，随时可以查看。这还没提课程遭遇到“学生说他用的是另一版讲义”这类纠纷时，版本记录可以直接作为依据。

Git 的基本工作流极其简单，日常只需要记住几件事：

• 改文件
• git add .
• git commit -m "描述这次的改动是什么"
• git push 推到远程备份

就这么多。分支和合并属于进阶操作，用到的时候再学也来得及。

4.2 分支策略：教材的“学期分支”怎么开

很多老师把 Git 学了基础操作之后就停了，但我建议多做一步：为每个学期建立独立分支。这个策略能解决一个很实际的问题——春季学期和秋季学期的课程内容不可能完全一样，但往往是在同一门课基础上微调。

我的保留做法是维护两条长期分支：

• main 分支：始终保存最新、最完整的课程书版本
• 以学期命名的分支，如 2025-spring：保存该学期的实际授课版本

当学期结束时，把该分支合并回 main，然后再从 main 拉一个新分支开始下学期的备课。这样的话，每个学期的历史版本都被完整保留，而 main 分支永远是当前最优状态的课程内容。合并过程中出现的冲突往往是课程结构调整的线索——同一个知识点，老的学期版和大纲版改了不同的地方，说明你对这个内容的态度确实发生了变化，值得停下来想想哪个版本更符合新的教学设计。

4.3 审校流程：讲师、助教、学生三条反馈通道

有了一整套版本控制框架，审校协作就能真正运转起来了。我在课程迭代中运行着三条反馈通道，它们的节奏和主体完全不同：

• 讲师自审：每学期开课前，逐章阅读课程书，重点不是找错别字，而是看内容顺序和学习坡度是否合适。自审的提交信息一般写“调整某模块顺序”“补充某知识点的前置说明”。
• 助教回看：助教是最熟悉学生真实卡点的人，他们的反馈核心来自作业和答疑记录中反复出现的问题。这些问题的答案如果能直接补充到课程书对应章节，下学期的答疑压力会小很多。
• 学生反馈：学期末组织专门的“课程书找茬”活动，用匿名表单收集意见。重点收集两类内容：哪里读不懂，哪里读不下去。前者是清晰度问题，后者是节奏和篇幅问题，处理方式完全不同。

这套三条通道走下来之后，课程书的每一轮迭代都不是拍脑袋决定的，而是有明确的问题来源和修改目标。我个人经验是，坚持两个学期之后，学生提出的“教材看不懂”类反馈会明显减少，因为反复出问题的知识点已经被反复打磨过了。

5. 使用层：把教材真正推进课堂

课程书搭好之后，下一个问题是怎么让它在真实教学中发挥作用，而不是变成一个“老师自嗨的文档仓库”。我在实践中发现，课程书的使用方式直接决定了学生和老师是否愿意持续维护它。

5.1 预习-课堂-复习三段式中的课程书角色

课程书最合理的定位不是“老师讲到哪里看到哪里”，而是贯穿课前、课中、课后的完整学习链路。

• 课前预习：学生阅读对应课时的知识点正文，完成文末的“课前自测”3 到 5 题。这些题目的作用是暴露理解缺口，不需要计分，但要求学生在课前看到问题后先自己思考，把卡住的地方带到课堂上。
• 课堂使用：老师讲课时只提取课程书中的重点案例做深度展开，不再让学生现场抄板书。我从前用来写一黑板推导过程的时间，现在可以用来做实时演练和分组讨论。
• 课后复习：学生回看课程书对应部分，完成文末的“课后练习”和“自查清单”。自查清单是我后加的，每章末尾用列表形式列出“学完本章，你应该能解释/解决/复现什么”，学生对照自查，效果比单纯的阅读好很多。

这套三段式最核心的转变是：老师的课堂不再承担“传输知识的全部功能”，而是变成对知识点的深化和应用练习。学生不在场时也能通过预习和复习获得大部分基础信息，课堂的价值因此从“讲一个他们完全没见过的知识”变成了“带他们用一遍”。

5.2 习题与案例如何与正文联动

课程书里的习题和案例，我强烈建议不要独立存成“题库”文件，而是紧跟在对应知识点正文后面。相比于独立的题库文件，这种方式对阅读者友好：读到一个概念立刻看到对应的应用问题，形成“概念→样例→尝试”的微循环。维护上也很方便，每个知识点相对独立，改题目不会牵动其他大文件。

习题本身也要有层次。我的做法是每课时至少配两类题：

• 基础巩固题：直接用同一知识点解决，简单直接，目标是建立信心。
• 应用变式题：把同一个知识点换一个场景，让学生识别“这其实还是那个知识点”。

案例库则独立放在每个模块的末尾。同一案例可以被多个知识点引用。这个设计对于案例的重用率提升是决定性的。比如我在数据库课里有一个“图书馆借阅系统”的贯穿案例，开篇介绍表结构时引用它，讲查询优化时还能提到它，学生不需要每次接触新的业务背景，认知负担小很多。

5.3 学生反馈的采集与回流

你可能会发现，课程书的最大改进动力其实来自学生的反馈，而学生愿不愿意认真反馈，取决于他们能否看到反馈的“回流”。我采用的机制是学期初公开一个课程书的公共仓库，学生可以提 Issue 或直接提修改建议。学期中期向全班展示已经根据反馈完成的修改：某章增加了红色字体标注的关键结论、某章习题新增了提示框、某章的术语表增加了英文对照。学生看到自己的反馈被采纳，后面给的反馈质量会明显上升。

个别学生提的优秀建议，我会在课程书致谢部分列出姓名（经同意）。这个激励看似不起眼，但对学生而言是“我的意见被认真对待”的直接证据，参与意愿有了质的提升。

6. 避坑实录：我在这套流程里踩过的真实问题

最后一部分，挑几个我实际踩过的坑，按“现象 → 原因 → 处理方案 → 现在的预防措施”这个顺序写出来。这些坑如果你不做 coursebook，可能永远遇不到；但一旦做，基本都会遇到。

6.1 章节编号自动化的陷阱

一开始我用 Markdown 手写章节编号，比如“## 4.3”这种。第一个学期没出问题，第二个学期，我在第二章中间插入了一节，结果从插的位置往后的所有章节编号全部需要手动改一遍。那一次我花了一个多小时改编号、改交叉引用，改到怀疑人生。

现在我的做法是：源文件里所有章节标题一律不写编号，导出的时候通过模板参数自动生成编号。Pandoc 支持 --number-sections，MkDocs 也支持配置自动编号。这样一来，插入和删除章节只需要处理顺序，编号和引用位置全自动生成，彻底根除了这个问题。

6.2 图片资源在不同平台间漂移

刚迁移到 Markdown 时，我干过一件很蠢的事：直接把 PPT 里的图片复制粘贴进 Typora，图片是显示正常了，但源文件里存的是一段本地绝对路径或嵌入的数据流。结果整个目录换电脑打开时，图片全部失效。更麻烦的是导出 PDF 的时候，图片路径有时能解析有时不能，完全看运气。

正确的姿势是：所有素材先放进 assets/images/，正文通过相对路径引用，比如 ![数据流程图](../assets/images/data-flow.png)。这里给你一个排查效率工具：在 book.toml 或构建脚本里加一个链接检查步骤，输出所有无法解析的图片路径，比人工翻文件快得多。

6.3 大纲改动后引用关系断裂

课程书内容多起来之后，章节之间会有互相引用。有一段时间我频繁调整模块顺序，结果正文里那些“参见 3.2 节”“详细内容见第 5 章”的引用全部错乱。这种错误一直到学生反馈才被发现，非常尴尬。

现在我的预防措施是：一切内部引用尽量用标签法，而不是写死章节号。在 Pandoc 里可以给章节加自定义标识，引用时使用该标识。导出时系统根据标识自动填充正确的章节号。在纯 Markdown 环境下，我会在引用处使用描述性文字而不是数字，比如“详细内容见‘数据清洗’课时”。这样无论章节顺序怎么变动，引用含义都不会丢失。

6.4 被忽略的阅读排版细节

最后这个坑几乎人人都踩过，但很少被人当回事：课程书在手机上的阅读体验。学生很多时候是用手机看课程书的，而我在早期版本里没有适配移动端。表格在手机上挤成一团，长代码没有横向滚动，公式渲染超出屏幕，阅读体验相当糟糕。

针对表格，我的做法是：绝不在 Markdown 里写超过 5 列的宽表格，必须用宽表时，把表格拆分成多个窄表或转成列表描述。针对代码块，确认所有导出模板都开启了横向滚动，并且代码换行策略为“保留缩进、横向滚动”而不是强制折叠。至于公式，最省心的方案是网页端使用 MathJax 渲染，它能够自动根据屏幕宽度换行，PDF 端则靠 XeLaTeX 的自动断行规则兜底。你现在看到的很多优质开源教材，之所以阅读体验好，就是这些细节被系统性地照顾到了。

整个 coursebook 流程走到这一步，基本已经循环过一轮：设计、工程化、迭代、使用、排坑。我在实际推进中的最大体会是，任何一次技术选型和流程调整，都要以这门课未来 3 到 5 年的使用寿命作为决策基准，而不是只顾眼前这一个学期。课程书的收益不是立竿见影的，但坚持两三轮迭代之后，你会明显感到备课不再是每个学期从零开始的重复劳动，而是一个越滚越厚、越用越顺的长期积累。