git.iko.soy/hakyll
on master help sign in
Start writing migration guide
282f0e2Jasper Van der Jeugt
web/tutorials/hakyll-3-to-hakyll4-migration-guide.markdownnew file+77
compare with master
unifiedsplit
@@ -0,0 +1,77 @@
1+---
2+title: Hakyll 3 to Hakyll 4 migration guide
3+author: Jasper Van der Jeugt
4+---
5+
6+Introduction
7+------------
8+
9+This tutorial gives a quick overview on how you can port your blog/website from
10+Hakyll 3.X to Hakyll 4. A lot of changes have happened, so it might be useful to
11+read through the [tutorial series](/tutorials.html) before porting your website.
12+
13+Arrow becomes Monad
14+-------------------
15+
16+In Hakyll 3.X, `Compiler` was an instance of `Arrow`. Since Hakyll 4, `Compiler`
17+is a `Monad`. This means that previous chains such as:
18+
19+```haskell
20+compile $ someCompiler
21+ >>> someOtherCompiler
22+ >>> anotherCompiler
23+```
24+
25+Now take the general form of:
26+
27+```haskell
28+compile $ someCompiler
29+ >>= someOtherCompiler
30+ >>= anotherCompiler
31+```
32+
33+Page goes away
34+--------------
35+
36+The `Page` type in Hakyll 3.X has been removed and replaced by an `Item` type.
37+`pageCompiler` no longer exists -- where you previously used this, you probably
38+want to use `pandocCompiler` instead.
39+
40+`Page`s where manipulated using `setField`/`getField` functions in Hakyll 3.X.
41+In Hakyll 4, all metadata is completely immutable, so these functions have been
42+removed. In order to format and add fields, use a `Context` -- see the next
43+section.
44+
45+Template changes
46+----------------
47+
48+The template format has become slightly more flexible, whereas in Hakyll 3.X
49+only keys such as this were allowed:
50+
51+```html
52+<h1>$title$</h1>
53+```
54+
55+we now allow arbitrary strings. This will be really useful in the future.
56+
57+```html
58+<h1>$uppercase title$</h1>
59+```
60+
61+Some template functions have been renamed:
62+
63+- `applyTemplateCompiler` becomes: `loadAndApplyTemplate`
64+- `applySelf` becomes: `applyAsTemplate`
65+
66+Instead of setting fields in a `Page` before applying a template, we now use a
67+`Context`. More information on context can be found in
68+[this tutorial](/tutorials/04-compilers.html). For migration, you basically want
69+to map every `setField` to a field in a `Context`.
70+
71+Metacompilers go away
72+---------------------
73+
74+For tags, the [Hakyll.Web.Tags] module still provides a solution. In other
75+cases, the `preprocess` function should be able to compensate for this.
76+
77+[Hakyll.Web.Tags]: /reference/Hakyll-Web-Tags.html