Courses

Courses 是一个用 Rust 编写的互动内容发布系统。它主要针对与代码相关的学习资源，包括书籍、课程材料和博客。

文档页面

重要：该项目处于非常早期的开发阶段，在发布第一个稳定版本之前，其范围或功能可能会发生重大变化。

特性

• 支持交互式源文件（Jupyter 笔记本）以及常规标记（Markdown）。
• 直接在源文件中定义任务及其解决方案。Courses 是专门为学习资源而设计的。
• 使用类似模板的简单语法（短代码）来应用内置和自定义组件，包括图表和注意事项。

目的

Courses 的创建是为了解决类似 Jupyterbook 和 Quarto 等工具未涵盖的一组特定问题。这些工具基于大型生态系统来执行发布过程。相比之下，courses 轻量级、自包含，并且可高度定制和扩展。

集成格式定义练习。

大多数现代学习材料以某种形式使用练习或任务。对于涉及代码的技术材料，随着项目规模的扩大，跟踪解决方案和任何学生提供的代码变得越来越复杂且容易出错。将解决方案版本分开保存的简单方法是有问题的，因为它还需要复制练习定义。因此，对其中一个版本的任何更改都必须手动复制到另一个版本。此外，没有简单的方法来测试发布版本（即没有解决方案）。

在 courses 中，可以使用简单语法在同一个源文件中定义练习定义和解决方案（在内容文件或代码文件中），例如指定解决方案部分。无需手动跟踪更改，工具使用完整的定义来测试解决方案并构建带有占位符的输出。使用此方法创建新练习很容易。您从解决方案开始，只需标记出不应在发布输出中可见的部分。

示例代码块

#| << CODE
# print("this is the placeholder and will be shown in the published output")
#| >> SOLUTION <<
print("this is the solution which is removed in the published version")
#| >> END_CODE

请注意，额外的语法隐藏在注释中，因此不会干扰底层实现语言。解决方案是唯一没有注释的部分，因此可以在开发过程中运行。

短代码

这是一个简单且通用的语法，用于扩展基本Markdown格式的功能。

这些语法在很大程度上受到Hugo的启发，尤其受到Zola的启发（Zola使用与Courses相同的模板引擎Tera）。

速度是一个特性

Courses足够快，可以实现实时编辑的工作流程。内置的自动重建和重新加载机制使得任何对源文件的更改几乎可以立即在浏览器中显示出来。即使是完整构建，通常也只需不到一秒钟即可完成，即使对于大型项目也是如此。

你应该能够专注于写作内容。一个更快的工具会为你清除障碍，并在你做出更改时提供反馈。

类似的项目

Courses绝非是唯一一个用于将学习资源和科学材料发布到网络上的工具。根据你的用例，这些工具可能更适合你。

如果你选择 courses

• 重视自动和几乎即时的重建，以便实时查看更改。
• 编写包含练习的材料，这些练习将从自动化测试和解决方案处理中受益。
• 想要一个简单的二进制文件，它只需运行，无需依赖环境设置或其他工具。
• 想要一个用于发布你工作的全能工具。 courses 不是
• 想要一个可扩展的工具
• 可以接受使用一个非常新、可能不稳定且肯定不受支持的项目。

如果你选择Jupyterbook或Quarto

• 主要使用Python或R生态系统，并且不想与HTML和模板打交道
• 只想将你的笔记本放到网上
• 需要与Jupyterhub集成
• 需要在你的内容中包含成熟的交互组件

Jupyterbook

该项目高度关注与Jupyter Notebook生态系统和格式的紧密集成。它特别适合允许使用现有技术（如JupyterHub）与笔记本进行交互。它是一个相当成熟的项目，建立在非常成熟的基础上，包括用于文档处理的Sphinx和当然还有用于交互的Jupyter。然而，它所支持的大量特性使得它比类似 courses 的东西要复杂得多。由于整个项目都是用Python构建的，构建速度较慢。此外，没有方便的自动重新加载功能。

Quarto

静态网站生成器（例如Hugo，Jekyll）

这些工具非常通用，允许自定义发布网页的几乎所有方面。Hugo也非常快，并且被广泛使用。然而，这些工具不支持Jupyter Notebooks或一般性的交互式内容（至少不是直接支持），它们也没有支持自动化测试或练习处理。

我非常考虑将 courses 创建为这些系统之一的扩展，但最终没有这么做，因为额外的预处理和后处理会增加太多的复杂性和混乱。

合作者和开发

Courses最初是为在哥本哈根IT大学的一门课程中使用而开发的，我现在在那里工作（网页链接）。该项目是为了解决Jupyterbook项目的一些缺点而开发的（详细信息请参见上一节）。这个工具的开发是在我的业余时间进行的，但合作提供了宝贵的反馈，并导致了几个关键特性的开发。