@@ -34,8 +34,10 @@ loadBody "posts/foo.markdown" :: Compiler String
3434
3535This is all useful if we want to use Hakyll's templating system.
3636
37−Basic templates
38−---------------
37+Templates
38+---------
39+
40+### Basic templates
3941
4042Let's have a look at a simple template:
4143
@@ -48,6 +50,16 @@ character has special meaning: text between dollar signs ("fields") is replaced
4850when the template is applied. If you want an actual dollar sign in the output,
4951use `$$`.
5052
53+You usually compile the templates from disk using the aptly named
54+`templateCompiler`:
55+
56+ match "templates/*" $ compile templateCompiler
57+
58+Notice the lack of `route` here: this is because we don't need to write the
59+templates to your `_site` folder, we just want to use them elsewhere.
60+
61+### Templates: Context
62+
5163We can easily guess the meaning of `$title$`, `$date$`, and `$body$`, but these
5264are not hard-coded fields: they belong to a certain [Context]. A `Context`
5365determines how the fields are interpreted. It's a [Monoid] and therefore very
@@ -89,18 +101,72 @@ context = mconcat
89101 ]
90102```
91103
92−TODO: Write about defaultContext. Extend it with dateField.
104+Obviously, it would be tedious to implement things like `titleContext` over and
105+over again for different websites and different fields. This is why hakyll
106+provides `defaultContext`. `defaultContext` is a composed `Context` and allows
107+you to use:
93108
94−You usually compile the templates from disk using the aptly named
95−`templateCompiler`:
109+- `$body$` for the body of the page;
110+- `$url$` for the destination URL of the page;
111+- `$path$` for the original filepath of the page;
112+- `$foo$` where foo is specified in the metadata.
96113
97− match "templates/*" $ compile templateCompiler
114+`$date$` is not provided by default, you can see how we add it in the definition
115+of `postCtx` in `site.hs`:
98116
99−Notice the lack of `route` here: this is because we don't need to write the
100−templates to your `_site` folder, we just want to use them elsewhere.
117+```haskell
118+postCtx :: Context String
119+postCtx =
120+ dateField "date" "%B %e, %Y" `mappend`
121+ defaultContext
122+```
123+
124+### Loading and applying templates
101125
102−Using them elsewhere is easy: we just use `load`!
126+Now we know about templates, context and how to load arbitrary items. This gives
127+us enough background information in order to understand you can apply a
128+template:
103129
104−TODO: Full example: load template, apply. Then `loadAndApplyTemplate`.
130+```haskell
131+compile $ do
132+ tpl <- loadBody "templates/post.html"
133+ pandocCompiler >>= applyTemplate tpl postCtx
134+```
135+
136+Loading and then immediately applying a template is so common there's a
137+shorthand function:
138+
139+```haskell
140+compile $
141+ pandocCompiler >>= loadAndApplyTemplate "templates/post.html" postCtx
142+```
143+
144+## Producing a list of items
145+
146+At this point, everything in the example site we generated should be clear to
147+you, except for how we produce the list of posts in `archive.html` and
148+`index.html`.
149+
150+However, this really isn't hard and just uses the things we saw before: loading
151+other items and applying templates.
152+
153+We can reproduce a list of items in the archive using the following code:
154+
155+```haskell
156+compile $ do
157+ posts <- recentFirst <$> loadAll "posts/*"
158+ itemTpl <- loadBody "templates/post-item.html"
159+ applyTemplateList itemTpl postCtx posts
160+```
161+
162+`recentFirst` sorts items by date. This relies on the convention that posts are
163+always named `YYYY-MM-DD-title.extension` in Hakyll -- if you use some other
164+format, you'll have to write some other sorting method.
165+
166+```haskell
167+recentFirst :: [Item a] -> [Item a]
168+```
105169
106−TODO: Load a list of posts, demonstrate `applyTemplateList`.
170+After loading and sorting the items, we load a template for the posts.
171+`applyTemplateList` applies this template to every post and concatenates the
172+result, which is a simple `String`.