@@ -0,0 +1,95 @@
1+---
2+title: Using teasers in Hakyll
3+author: Ivan Veselov
4+---
5+
6+## Introduction
7+
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.
11+
12+You can do this in Hakyll by using "teasers" functionality.
13+
14+## Marking teasers in posts
15+
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):
19+
20+``` markdown
21+---
22+title: My teasering post
23+---
24+In this post I'll try to explain how to use teasers.
25+
26+<!--more-->
27+
28+And here I am proceeding with the explanation.
29+
30+```
31+
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.
34+
35+## Referring to teasers in templates
36+
37+Now, we want to refer to the teaser in the template. We can do this
38+pretty intuitively by using `$teaser$` key:
39+
40+``` html
41+<li class="post_item">
42+ $date$ - $title$
43+ <p>Teaser: $teaser$</p>
44+ <a href="$url$">Read more</a>
45+</li>
46+```
47+
48+## Gluing together
49+
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:
57+
58+``` haskell
59+match "posts/*" $ do
60+ route $ setExtension ".html"
61+ compile $
62+ pandocCompiler
63+ -- save immediately after pandoc, but before the templates are applied
64+ >>= saveSnapshot "content"
65+ >>= loadAndApplyTemplate "templates/post.html" defaultContext
66+ ...
67+```
68+
69+You can read more about snapshots in
70+[Snapshots tutorial](/tutorials/05-snapshots-feeds.html).
71+
72+Then we use this snapshot while generating teasers using
73+`teaserContext` function:
74+
75+``` haskell
76+ loadAndApplyTemplate
77+ "template/postitem.html"
78+ (teaserContext "content" <> defaultContext)
79+ item
80+```
81+
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).
85+
86+## Known issues
87+
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:
92+
93+``` html
94+<div></div><!--more-->
95+```