@@ -34,8 +34,10 @@ loadBody "posts/foo.markdown" :: Compiler String
35This is all useful if we want to use Hakyll's templating system.
35This is all useful if we want to use Hakyll's templating system.
37−Basic templates
40+### Basic templates
40Let's have a look at a simple template:
42Let's have a look at a simple template:
@@ -48,6 +50,16 @@ character has special meaning: text between dollar signs ("fields") is replaced
48when the template is applied. If you want an actual dollar sign in the output,
50when the template is applied. If you want an actual dollar sign in the output,
53+You usually compile the templates from disk using the aptly named
56+ match "templates/*" $ compile templateCompiler
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.
61+### Templates: Context
51We can easily guess the meaning of `$title$`, `$date$`, and `$body$`, but these
63We can easily guess the meaning of `$title$`, `$date$`, and `$body$`, but these
52are not hard-coded fields: they belong to a certain [Context]. A `Context`
64are not hard-coded fields: they belong to a certain [Context]. A `Context`
53determines how the fields are interpreted. It's a [Monoid] and therefore very
65determines how the fields are interpreted. It's a [Monoid] and therefore very
@@ -89,18 +101,72 @@ context = mconcat
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
94−You usually compile the templates from disk using the aptly named
109+- `$body$` for the body of the page;
95−`templateCompiler`:
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.
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`:
99−Notice the lack of `route` here: this is because we don't need to write the
117+```haskell
100−templates to your `_site` folder, we just want to use them elsewhere.
118+postCtx :: Context String
120+ dateField "date" "%B %e, %Y" `mappend`
124+### Loading and applying templates
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
104−TODO: Full example: load template, apply. Then `loadAndApplyTemplate`.
130+```haskell
132+ tpl <- loadBody "templates/post.html"
133+ pandocCompiler >>= applyTemplate tpl postCtx
136+Loading and then immediately applying a template is so common there's a
141+ pandocCompiler >>= loadAndApplyTemplate "templates/post.html" postCtx
144+## Producing a list of items
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
150+However, this really isn't hard and just uses the things we saw before: loading
151+other items and applying templates.
153+We can reproduce a list of items in the archive using the following code:
157+ posts <- recentFirst <$> loadAll "posts/*"
158+ itemTpl <- loadBody "templates/post-item.html"
159+ applyTemplateList itemTpl postCtx posts
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.
167+recentFirst :: [Item a] -> [Item a]
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`.