@@ -36,3 +36,71 @@ This is all useful if we want to use Hakyll's templating system.
3636
3737Basic templates
3838---------------
39+
40+Let's have a look at a simple template:
41+
42+ <h1>$title$</h1>
43+ <div class="info">Posted on $date$</div>
44+ $body$
45+
46+As you can probably guess, template files just contain text and only the `$`
47+character has special meaning: text between dollar signs ("fields") is replaced
48+when the template is applied. If you want an actual dollar sign in the output,
49+use `$$`.
50+
51+We can easily guess the meaning of `$title$`, `$date$`, and `$body$`, but these
52+are not hard-coded fields: they belong to a certain [Context]. A `Context`
53+determines how the fields are interpreted. It's a [Monoid] and therefore very
54+composable.
55+
56+[Context]: /reference/Hakyll-Web-Template-Context.html
57+[Monoid]: http://learnyouahaskell.com/functors-applicative-functors-and-monoids
58+
59+`field` allows us to create a `Context` for a single field:
60+
61+```haskell
62+field :: String -> (Item a -> Compiler String) -> Context a
63+```
64+
65+Let's try this out. Note that this is for illustration purposes only: you
66+shouldn't have to write complicated fields often. We can implement the `$body$`
67+field like this:
68+
69+```haskell
70+field "body" $ \item -> return (itemBody item) :: Context String
71+```
72+
73+And `$title$` like this:
74+
75+```haskell
76+titleContext :: Context a
77+titleContext :: field "title" $ \item -> do
78+ metadata <- getMetadata (itemIdentifier item)
79+ return $ fromMaybe "No title" $ M.lookup "title" metadata
80+```
81+
82+And compose them using the `Monoid` instance:
83+
84+```haskell
85+context :: Context String
86+context = mconcat
87+ [ titleContext
88+ , field "body" $ return . itemBody
89+ ]
90+```
91+
92+TODO: Write about defaultContext. Extend it with dateField.
93+
94+You usually compile the templates from disk using the aptly named
95+`templateCompiler`:
96+
97+ match "templates/*" $ compile templateCompiler
98+
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.
101+
102+Using them elsewhere is easy: we just use `load`!
103+
104+TODO: Full example: load template, apply. Then `loadAndApplyTemplate`.
105+
106+TODO: Load a list of posts, demonstrate `applyTemplateList`.