@@ -0,0 +1,95 @@
2+title: Using teasers in Hakyll
8+Sometimes it is convenient to have an excerpt of a post displayed on
9+the index page along with a "Read more..." link to encourage your
10+readers to read the rest of the post.
12+You can do this in Hakyll by using "teasers" functionality.
14+## Marking teasers in posts
16+First, you have to put a tag in your post which separates the teaser
17+from the rest of the article. We use `<!--more-->` for this to mimic
18+the [WordPress convention](http://codex.wordpress.org/Customizing_the_Read_More):
22+title: My teasering post
24+In this post I'll try to explain how to use teasers.
28+And here I am proceeding with the explanation.
32+This is an HTML comment, so it doesn't have any visual impact on the
33+post, it is there solely for semantic purposes.
35+## Referring to teasers in templates
37+Now, we want to refer to the teaser in the template. We can do this
38+pretty intuitively by using `$teaser$` key:
41+<li class="post_item">
43+ <p>Teaser: $teaser$</p>
44+ <a href="$url$">Read more</a>
50+The only thing left is to glue those things together. An important
51+question here is on what stage of the compilation we want to extract a
52+teaser. Usually, we want to use pandoc output, i.e. raw HTML without
53+any templates applied (since we do not want some surrounding
54+JavaScript or common text from the templates to be included in the
55+teaser). We can specify this by using snapshots: we save the snapshot
56+during compilation and load it to resolve `$teaser$` key later:
60+ route $ setExtension ".html"
63+ -- save immediately after pandoc, but before the templates are applied
64+ >>= saveSnapshot "content"
65+ >>= loadAndApplyTemplate "templates/post.html" defaultContext
69+You can read more about snapshots in
70+[Snapshots tutorial](/tutorials/05-snapshots-feeds.html).
72+Then we use this snapshot while generating teasers using
73+`teaserContext` function:
77+ "template/postitem.html"
78+ (teaserContext "content" <> defaultContext)
82+Here, we've just added a new context which knows how to handle
83+`$teaser$` key to the default context (note that we passed the same
84+snapshot name `"content"` which we used while saving).
88+Since we use an HTML comment `<!--more-->` to separate the teaser,
89+sometimes `pandoc` can "eat" the comment while converting (for example
90+this happens with literate Haskell source). In order to overcome this
91+problem you may try to use something like this as a separator:
94+<div></div><!--more-->