Hakyll 项目从3.X版本迁移到4.X版本指南

前言

Hakyll 是一个基于Haskell的静态网站生成器，4.X版本相对于3.X版本进行了多项重大改进。本指南将详细介绍如何将现有项目从Hakyll 3.X迁移到4.X版本，帮助开发者顺利完成升级过程。

核心变化概述

Hakyll 4.X版本的主要架构变化集中在编译器和模板系统上，这些变化带来了更强大的功能和更清晰的代码结构。

编译器(Compiler)的范式转变

在Hakyll 3.X中，Compiler类型实现了Arrow类型类，开发者使用箭头符号(>>>)来组合不同的编译器。而在4.X版本中：

1. Compiler现在是一个Monad实例
2. 组合方式从箭头变为单子绑定

迁移示例：

-- Hakyll 3.X风格
compile $ someCompiler
    >>> someOtherCompiler
    >>> anotherCompiler

-- Hakyll 4.X风格
compile $ someCompiler
    >>= someOtherCompiler
    >>= anotherCompiler

这种变化使得编译器组合更加灵活，可以更好地处理复杂的编译逻辑。

Page类型的移除

Hakyll 4.X移除了Page类型，取而代之的是更通用的Item类型：

1. pageCompiler已被移除，大多数情况下应使用pandocCompiler
2. 不再支持setField和getField等可变操作
3. 所有元数据现在都是不可变的

模板系统改进

Hakyll 4.X对模板系统进行了显著增强：

模板语法扩展

新版本支持更丰富的模板表达式：

<!-- Hakyll 3.X仅支持简单变量 -->
<h1>$title$</h1>

<!-- Hakyll 4.X支持函数应用 -->
<h1>$uppercase title$</h1>

函数重命名

几个关键模板函数名称发生了变化：

• applyTemplateCompiler → loadAndApplyTemplate
• applySelf → applyAsTemplate

上下文(Context)系统

取代了3.X版本中通过Page设置字段的方式，4.X引入了Context概念：

1. 所有模板变量现在通过上下文提供
2. 字段在应用模板前就必须完全确定
3. 每个setField调用都应转换为上下文中的一个字段

元编译器(Metacompilers)的移除

Hakyll 4.X移除了元编译器概念：

1. 标签功能现在由Hakyll.Web.Tags模块提供
2. 其他场景可以使用preprocess函数替代

迁移步骤建议

1. 逐步替换编译器组合：先将所有>>>操作符替换为>>=
2. 更新页面处理：将pageCompiler替换为pandocCompiler
3. 重构模板应用：使用新的模板函数名称和上下文系统
4. 处理特殊功能：如标签等，使用新模块提供的方案

总结

Hakyll 4.X版本通过引入单子编译器、不可变元数据和增强的模板系统，提供了更强大、更一致的开发体验。虽然迁移需要一些工作，但新架构为未来的扩展奠定了更好的基础。建议开发者在迁移前充分理解这些概念变化，并参考官方文档中的详细教程。