summaryrefslogtreecommitdiff
path: root/web
diff options
context:
space:
mode:
authorJasper Van der Jeugt <m@jaspervdj.be>2012-12-17 00:46:23 +0100
committerJasper Van der Jeugt <m@jaspervdj.be>2012-12-17 00:46:23 +0100
commit21648b8388427003928782d2f1969ab2957b553b (patch)
tree3a671a7e392dc61ad30c208d0ce5dfe677178659 /web
parent918ed3c3fab736bb6b3b72724bdcb07e33d87a0b (diff)
downloadhakyll-21648b8388427003928782d2f1969ab2957b553b.tar.gz
Bit of template docs
Diffstat (limited to 'web')
-rw-r--r--web/tutorials/04-compilers.markdown68
1 files changed, 68 insertions, 0 deletions
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`.