Bit of template docs

2 files changed, 72 insertions, 0 deletions

diff --git a/src/Hakyll/Web/Template/Context.hs b/src/Hakyll/Web/Template/Context.hs
index 084a42e..c2ec6bc 100644
--- a/src/Hakyll/Web/Template/Context.hs
+++ b/src/Hakyll/Web/Template/Context.hs
@@ -96,6 +96,7 @@ bodyField key = field key $ return . itemBody
 
 
 --------------------------------------------------------------------------------
+-- | Map any field to its metadata value, if present
 metadataField :: Context String
 metadataField = Context $ \k i -> do
     metadata <- getMetadata $ itemIdentifier i
@@ -103,17 +104,20 @@ metadataField = Context $ \k i -> do
 
 
 --------------------------------------------------------------------------------
+-- | Absolute url to the resulting item
 urlField :: String -> Context a
 urlField key = field key $
     fmap (maybe empty toUrl) . getRoute . itemIdentifier
 
 
 --------------------------------------------------------------------------------
+-- | Filepath of the underlying file of the item
 pathField :: String -> Context a
 pathField key = field key $ return . toFilePath . itemIdentifier
 
 
 --------------------------------------------------------------------------------
+-- | This title field takes the basename of the underlying file by default
 titleField :: String -> Context a
 titleField key = mapContext takeBaseName $ pathField key
 
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`.