summaryrefslogtreecommitdiff
path: root/web/tutorials/hakyll-3-to-hakyll4-migration-guide.markdown
blob: 2e03f66a51e6d2e54cdf922dd8172d195104af9f (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
---
title: Hakyll 3 to Hakyll 4 migration guide
author: Jasper Van der Jeugt
type: article
---

Introduction
------------

This tutorial gives a quick overview on how you can port your blog/website from
Hakyll 3.X to Hakyll 4. A lot of changes have happened, so it might be useful to
read through the [tutorial series](/tutorials.html) before porting your website.

Arrow becomes Monad
-------------------

In Hakyll 3.X, `Compiler` was an instance of `Arrow`. Since Hakyll 4, `Compiler`
is a `Monad`. This means that previous chains such as:

```haskell
compile $ someCompiler
    >>> someOtherCompiler
    >>> anotherCompiler
```

Now take the general form of:

```haskell
compile $ someCompiler
    >>= someOtherCompiler
    >>= anotherCompiler
```

Page goes away
--------------

The `Page` type in Hakyll 3.X has been removed and replaced by an `Item` type.
`pageCompiler` no longer exists -- where you previously used this, you probably
want to use `pandocCompiler` instead.

`Page`s were manipulated using `setField`/`getField` functions in Hakyll 3.X.
In Hakyll 4, all metadata is completely immutable, so these functions have been
removed. In order to format and add fields, use a `Context` -- see the next
section.

Template changes
----------------

The template format has become slightly more flexible, whereas in Hakyll 3.X
only keys such as this were allowed:

```html
<h1>$title$</h1>
```

we now allow arbitrary strings. This will be really useful in the future.

```html
<h1>$uppercase title$</h1>
```

Some template functions have been renamed:

- `applyTemplateCompiler` becomes: `loadAndApplyTemplate`
- `applySelf` becomes: `applyAsTemplate`

Instead of setting fields in a `Page` before applying a template, we now use a
`Context`. More information on context can be found in
[this tutorial](/tutorials/04-compilers.html). For migration, you basically want
to map every `setField` to a field in a `Context`.

Metacompilers go away
---------------------

For tags, the [Hakyll.Web.Tags] module still provides a solution. In other
cases, the `preprocess` function should be able to compensate for this.

[Hakyll.Web.Tags]: /reference/Hakyll-Web-Tags.html