From 21648b8388427003928782d2f1969ab2957b553b Mon Sep 17 00:00:00 2001
From: Jasper Van der Jeugt <m@jaspervdj.be>
Date: Mon, 17 Dec 2012 00:46:23 +0100
Subject: Bit of template docs

---
 web/tutorials/04-compilers.markdown | 68 +++++++++++++++++++++++++++++++++++++
 1 file changed, 68 insertions(+)

(limited to 'web')

diff --git a/web/tutorials/04-compilers.markdown b/web/tutorials/04-compilers.markdown
index a344c6e..8f79b46 100644
--- a/web/tutorials/04-compilers.markdown
+++ b/web/tutorials/04-compilers.markdown
@@ -36,3 +36,71 @@ This is all useful if we want to use Hakyll's templating system.
 
 Basic templates
 ---------------
+
+Let's have a look at a simple template:
+
+    <h1>$title$</h1>
+    <div class="info">Posted on $date$</div>
+    $body$
+
+As you can probably guess, template files just contain text and only the `$`
+character has special meaning: text between dollar signs ("fields") is replaced
+when the template is applied. If you want an actual dollar sign in the output,
+use `$$`.
+
+We can easily guess the meaning of `$title$`, `$date$`, and `$body$`, but these
+are not hard-coded fields: they belong to a certain [Context]. A `Context`
+determines how the fields are interpreted. It's a [Monoid] and therefore very
+composable.
+
+[Context]: /reference/Hakyll-Web-Template-Context.html
+[Monoid]: http://learnyouahaskell.com/functors-applicative-functors-and-monoids
+
+`field` allows us to create a `Context` for a single field:
+
+```haskell
+field :: String -> (Item a -> Compiler String) -> Context a
+```
+
+Let's try this out. Note that this is for illustration purposes only: you
+shouldn't have to write complicated fields often.  We can implement the `$body$`
+field like this:
+
+```haskell
+field "body" $ \item -> return (itemBody item) :: Context String
+```
+
+And `$title$` like this:
+
+```haskell
+titleContext :: Context a
+titleContext :: field "title" $ \item -> do
+    metadata <- getMetadata (itemIdentifier item)
+    return $ fromMaybe "No title" $ M.lookup "title" metadata
+```
+
+And compose them using the `Monoid` instance:
+
+```haskell
+context :: Context String
+context = mconcat
+    [ titleContext
+    , field "body" $ return . itemBody
+    ]
+```
+
+TODO: Write about defaultContext. Extend it with dateField.
+
+You usually compile the templates from disk using the aptly named
+`templateCompiler`:
+
+    match "templates/*" $ compile templateCompiler
+
+Notice the lack of `route` here: this is because we don't need to write the
+templates to your `_site` folder, we just want to use them elsewhere.
+
+Using them elsewhere is easy: we just use `load`!
+
+TODO: Full example: load template, apply. Then `loadAndApplyTemplate`.
+
+TODO: Load a list of posts, demonstrate `applyTemplateList`.
-- 
cgit v1.2.3