Site 模式是 MoPress 面向进阶用户的使用方式:不再依赖配置文件声明式地配置构建行为,而是直接用 MoonBit 代码描述“哪些文件该被如何处理”。这一整套设计思路继承自 Hakyll 的可组合编译器理念——把构建流程拆解为一系列可以自由组合的小函数,而不是一个只能通过配置项开关的黑盒。
如果是以下任意一种情况,Book 模式的配置项可能已经无法满足需求,这时候可以考虑切换到 Site 模式:
需求目标为通用的静态网站生成,而非书籍文档网站。
需要对不同文件采用完全不同的处理逻辑(如某些 Markdown 文件要走特殊的渲染流程,其他的走默认流程)。
需要在构建过程中引入自定义的、无法通过外部命令表达的处理逻辑。
需要让一个源文件产出多个目标文件(如同时生成一份 HTML 页面和一份对应的 JSON 数据,参见输出格式)。
单纯地更喜欢用代码而非配置文件来描述构建逻辑。
反过来,如果目前的需求就是“写 Markdown、套模板、生成站点”请优先使用 Book 模式——Site 模式提供的灵活性是有对应的学习成本的,没有必要为了用不到的灵活性而增加心智负担。
Site 模式的整套 API 建立在三个核心抽象之上,这里先给出一个最简版本的直觉,具体细节将在后续章节展开。
Item[T] 是流经整条构建管线的数据载体。一个 Item[T] 携带三样东西:类型为 T 的数据本身(可能是原始文本、解析后的语法树,或渲染完成的 HTML)、一组模板变量,以及最终的输出路径。
Step 是形如 (Item[T]) -> Item[R] 的函数——它接收一个 Item,做一些处理,产出另一个(可能是不同类型的)Item。MoPress 提供了一整套现成的 step(解析 Markdown、渲染模板、注入资源等),可以把它们像管道一样拼接起来,也可以编写自己的 step 插入其中。
Rule 描述“哪些文件应该被匹配到、并以何种方式处理”:用 Glob 匹配文件路径,并指定一种处理方式(Handler)——可以是“当作文本读入当作文本读入、跑一串 step、写出结果”,可以是“当作二进制读入”,也可以是“直接输出原样复制”。
一份最简单的构建脚本,本质上就是声明一组 Rule,然后让它们跑起来。完整的最小示例请参见开始一节。
值得强调的是,Book 模式不是一套独立于 Site 模式的实现——负责 Book 模式的构建流程,本身就是用 Site 模式底层提供的这套 Item、Rule、Step 机制拼接而成的。这意味着,如果想在 Book 模式的基础上做局部的自定义,完全可以参考甚至直接复用这部分逻辑,而不需要从零开始重新实现一遍。