diff options
| -rw-r--r-- | data/example/posts/2012-10-07-rosa-rosa-rosam.markdown | 1 | ||||
| -rw-r--r-- | data/example/posts/2012-12-07-tu-quoque.markdown | 1 | ||||
| -rw-r--r-- | data/example/templates/post.html | 7 | ||||
| -rw-r--r-- | web/releases.markdown | 25 | ||||
| -rw-r--r-- | web/tutorials/04-compilers.markdown | 128 |
5 files changed, 147 insertions, 15 deletions
diff --git a/data/example/posts/2012-10-07-rosa-rosa-rosam.markdown b/data/example/posts/2012-10-07-rosa-rosa-rosam.markdown index 01afcdb..bbda8fd 100644 --- a/data/example/posts/2012-10-07-rosa-rosa-rosam.markdown +++ b/data/example/posts/2012-10-07-rosa-rosa-rosam.markdown @@ -1,5 +1,6 @@ --- title: Rosa Rosa Rosam +author: Ovidius --- Suspendisse pharetra ullamcorper sem et auctor. Suspendisse vitae tellus eu diff --git a/data/example/posts/2012-12-07-tu-quoque.markdown b/data/example/posts/2012-12-07-tu-quoque.markdown index 16c12ec..bdf2ea4 100644 --- a/data/example/posts/2012-12-07-tu-quoque.markdown +++ b/data/example/posts/2012-12-07-tu-quoque.markdown @@ -1,5 +1,6 @@ --- title: Tu Quoque +author: Julius --- Vestibulum leo turpis, dignissim quis ultrices sit amet, iaculis ac ligula. diff --git a/data/example/templates/post.html b/data/example/templates/post.html index 4b39962..bf0f826 100644 --- a/data/example/templates/post.html +++ b/data/example/templates/post.html @@ -1,3 +1,8 @@ -<div class="info">Posted on $date$</div> +<div class="info"> + Posted on $date$ + $if(author)$ + by $author$ + $endif$ +</div> $body$ diff --git a/web/releases.markdown b/web/releases.markdown index 2c76812..7ee5aa2 100644 --- a/web/releases.markdown +++ b/web/releases.markdown @@ -4,6 +4,31 @@ title: Releases # Releases +## Hakyll 4.3.0.0 + +- Add conditionals, partials and for loops to the template system (includes a + contribution by Ivan N. Veselov) + +- Improvements to the preview functionality on windows (contribution by Jorge + Israel Peña) + +- Add pagination support (contribution by Anton Dubovik) + +- Slight speedup for the Hakyll cache (contribution by justnoxx) + +- Add teaser functionality (contribution by Ivan N. Veselov) + +- Make `./site check` work with scheme-relative URLs (contribution by Simonas + Kazlauskas) + +- The `./site deploy` command can now be customized with Haskell code + (contribution by Samuel Tardieu) + +- Use `hsnotify` for proper polling instead of sleep loop on all platforms + (contribution by Simonas Kazlauskas) + +- More useful debug info available + ## Hakyll 4.2.2.0 - Fix issue with `Alternative` instance of `Compiler` diff --git a/web/tutorials/04-compilers.markdown b/web/tutorials/04-compilers.markdown index cdc8eb0..ee46a0c 100644 --- a/web/tutorials/04-compilers.markdown +++ b/web/tutorials/04-compilers.markdown @@ -145,25 +145,108 @@ compile $ pandocCompiler >>= loadAndApplyTemplate "templates/post.html" postCtx ``` -## Producing a list of items +Control flow in templates +------------------------- + +Sometimes string interpolation does not suffice, and you want a little more +control over how your templates are layed out. Hakyll provides a few control +structures for this. The syntax for these structures was based on the syntax +used in pandoc templates, since Hakyll already has tight integration with +pandoc. + +### Conditionals + +In `templates/post.html` of the example site we generated using `hakyll-init`, +we see an example of a conditional: + +```html +<div class="info"> + Posted on $date$ + $if(author)$ + by $author$ + $endif$ +</div> +``` + +This example should be pretty straightforward. One important thing to notice is +that `$if(foo)$` **does not** check the truth value of `$foo$`: it merely checks +if such a key is present. + +Note that an if-else form is supported as well: + +```html +<div class="info"> + Posted on $date$ + $if(author)$ + by $author$ + $else$ + by some unknown author + $endif$ +</div> +``` + +### Partials + +Partials allow you to [DRY] up your templates by putting repetitive actions into +separate template files. You can then include them using +`$partial("filename.html")$. + +[DRY]: http://en.wikipedia.org/wiki/Don%27t_repeat_yourself + +An example can be found in `templates/archive.html`: + +```html +Here you can find all my previous posts: +$partial("templates/post-list.html")$ +``` + +This partial is just another template and uses the same syntax. Note that in +order to use something like this, we also need to load the partial template in +our `site.hs`: + +```haskell +match "templates/post-list.html" $ compile templateCompiler +``` + +Fortunately, we usually don't need to add this since we already have: + +```haskell +match "templates/*" $ compile templateCompiler +``` + +### Producing a list of items: for At this point, everything in the example site we generated should be clear to you, except for how we produce the list of posts in `archive.html` and -`index.html`. +`index.html`. Let's look at the `templates/post-list.html` template: + +```html +<ul> + $for(posts)$ + <li> + <a href="$url$">$title$</a> - $date$ + </li> + $endfor$ +</ul> +``` -However, this really isn't hard and just uses the things we saw before: loading -other items and applying templates. +This uses the `$for(foo)$` construct. This construct allows you loop over a +list, in this case, `$posts$`. Inside the body of this for loop, all fields +refer to the current post, e.g.: `$url$`, `$title$` and `$date$`. -We can reproduce a list of items in the archive using the following code: +Of course, $posts$ does not magically appear. We have to specify this in +`site.hs`. Let's look at how `archive.html` is generated: ```haskell -compile $ do - posts <- recentFirst =<< loadAll "posts/*" - itemTpl <- loadBody "templates/post-item.html" - list <- applyTemplateList itemTpl postCtx posts - makeItem list +posts <- recentFirst =<< loadAll "posts/*" +let archiveCtx = + listField "posts" postCtx (return posts) `mappend` + constField "title" "Archives" `mappend` + defaultContext ``` +We discussed `loadAll` earlier in this tutorial. + `recentFirst` sorts items by date. This relies on the convention that posts are always named `YYYY-MM-DD-title.extension` in Hakyll -- or that the date must be present in the metadata. @@ -172,7 +255,24 @@ present in the metadata. recentFirst :: [Item a] -> Compiler [Item a] ``` -After loading and sorting the items, we load a template for the posts. -`applyTemplateList` applies this template to every post and concatenates the -result, which is a simple `String`. After that, we need `makeItem` to wrap the -returned `String` to `Item String`. +After loading and sorting the items, we use `listField` to create the `$posts$` +key. + +```haskell +listField :: String -> Context a -> Compiler [Item a] -> Context b +``` + +The first parameter is simply the name of the key (`"posts"`). Secondly we have +a `Context` with which all items should be rendered -- for our example site, we +already wrote such a `Context` for posts: `postCtx`. Lastly, we have a +`Compiler` which loads the items. We already loaded the items so we can just use +`return posts`. + +The following snippet would produce the same result: + +```haskell +let archiveCtx = + listField "posts" postCtx (recentFirst =<< loadAll "posts/*") `mappend` + constField "title" "Archives" `mappend` + defaultContext +``` |