Noteworth：使用 Typst 的教育文档框架，能生成学术教科书、讲义和技术文档

Noteworthy 是一个基于 Typst 的强大框架，专为创建美观和具有主题性的教育文档而设计，能非常高效的生成大规模和复杂的学术教科书、讲义和技术文档。Noteworthy 提供了一个完整的生态系统，包括一个拥有 13+ 预设且易于定制的色彩主题系统、一个用于定义、定理、示例、证明和解决方案等内容的预设样式内容块库，以及一个支持高级 2D/3D 绘图、矢量图和几何构造的绘图引擎。Noteworthy 具备自动化的目录、章节封面和页面页眉管理功能，通过 JSON 配置层和增量编译、自动 PDF 合并的构建系统，实现了高度的灵活性和生产效率。Noteworthy 提供了一个交互式的文本用户界面 (TUI)，允许用户直观地管理配置、章节层级、主题方案和代码片段，最后制作出精美的数学排版和个性化文档，已被用于实际教育材料的制作中。

Noteworthy核心功能与组件

结构化布局

自动生成章节、小节和封面，无需手动调整格式，文档结构清晰规整，节省排版时间。

主题化组件

内置预设样式的模块，涵盖定义、定理、示例、证明、解决方案等常见学术内容形式，直接调用即可使用。

高级绘图能力

支持 2D、3D 绘图，还能绘制向量图和几何图形，满足数学、物理等学科的可视化需求。

可自定义主题

提供 13 种以上预设配色方案，主题切换简单，也能根据需求自行调整，可用于不同使用场景和个人偏好。

文档结构支持

自动生成目录、章节封面和页面页眉，让文档层次分明，查阅起来更加方便。

配置层

通过 templates/config/ 目录下的 JSON 文件进行设置，配置方式灵活，上手难度低。

构建系统

支持增量编译，还能自动合并 PDF 文件，避免重复编译耗时，提升文档制作效率。

交互式编辑器

提供基于 TUI 的编辑器，可用于配置文件、章节结构、配色方案和代码片段的编辑，还有专门的前言编辑器。

安装和使用 Noteworthy

前置依赖

1、Typst（v0.12.0 及以上版本）：需提前安装

2、Python 3：构建系统运行必需

3、Poppler（提供 pdfinfo 用于页面计数）

macOS：执行 brew install poppler 安装

Linux：执行 apt-get install poppler-utils 安装

Windows：从 Poppler 发布页面下载并添加到系统路径

4、PDF 工具（用于合并文件和添加元数据）

macOS：执行 brew install pdftk-java 安装

Linux：执行 apt-get install pdftk 安装

Windows：从 pdftk 发布页面下载

备选方案：Ghostscript（macOS 和 Linux 通常预装，Windows 需单独下载）

pdftk 是添加 PDF 元数据（标题、作者等）和可点击书签/大纲的必需工具，这些功能能让 PDF 阅读器侧边栏显示导航内容，方便查阅。

安装步骤

1、创建项目目录并进入

mkdir project
cd project

2、创建内容目录

mkdir content

3、下载核心脚本

curl -O https://raw.githubusercontent.com/sihooleebd/noteworthy/master/noteworthy.py

使用 Noteworthy

1、在项目中添加所需内容

2、运行构建脚本，设置向导会引导完成配置

python3 noteworthy.py

3、首次运行时，模板会自动加载必需的模板文件，后续可根据提示完成初始化、配置和构建操作

TUI 功能说明

• 章节选择：可单独切换各章节/小节的编译状态

• 功能按键

d：调试模式（输出详细日志）

f：选择是否包含前言内容（封面、引言、目录）

l：合并后保留单个 PDF 文件

c：配置自定义 Typst 标志（例如 --font-path）

e：打开配置编辑器

• 编辑器菜单（按 e 键进入）

配置编辑器：设置文档标题、作者、主题等信息

层级编辑器：添加/删除章节/页面结构

方案编辑器：创建/删除配色主题

代码片段编辑器：自定义宏命令

前言编辑器：编辑前言内容

• 操作控制：方向键导航，空格键切换选项，回车键开始构建，q 键退出

• 构建进度：实时显示编译状态，按 v 键可切换 Typst 日志显示

• 模板完整性检查：自动验证模板文件是否损坏，若有问题可自动修复

单文件编译

如需单独编译特定小节，可执行以下命令：

typst compile templates/parser.typ --input target=01.01 section.pdf