@@ -0,0 +1,84 @@
1+---
2+title: Creating feeds
3+what: adds an rss feed to the simple blog
4+---
5+
6+## Adding Feeds
7+
8+In this tutorial, we're going to add an RSS feed to the blog we wrote in the
9+previous part. Here is a [zip file] containing the source.
10+
11+[zip file]: examples/feedblog.zip
12+
13+You will be glad to hear that Hakyll has native support for RSS as well as Atom
14+feeds[^1]. This simplifies our object a lot.
15+
16+[^1]: Since Hakyll-2.0
17+
18+This is the first time that the absolute URL of your site you have to give to
19+the `hakyll` function actually matters. That's because the specifications of
20+those feed formats dictate you need the full URL of them.
21+
22+## Creating a configuration
23+
24+The first thing to do is creating a configuration for your feed. You could
25+place this code outside of your main function, as is done in the example.
26+
27+~~~~~{.haskell}
28+myFeedConfiguration = FeedConfiguration
29+ { feedUrl = "rss.xml"
30+ , feedTitle = "SimpleBlog RSS feed."
31+ , feedDescription = "Simple demo of a feed created with Hakyll."
32+ , feedAuthorName = "Jasper Van der Jeugt"
33+ }
34+~~~~~
35+
36+Note that we enter the url of the feed in our configuration. So the function
37+to render our feed only takes two arguments, the configuration and a list of
38+items to put in the feed. Let's put the three most recent posts in our feed.
39+
40+~~~~~{.haskell}
41+renderRss myFeedConfiguration (take 3 postPages)
42+~~~~~
43+
44+## But it's not that easy
45+
46+If you look at our generated RSS feed (build the site), you will see
47+`$description` tags appearing in our final render. We don't want that! How
48+did they get there in the first place?
49+
50+To render feeds, Hakyll expects a number of fields in the renderables you put
51+in the feed. They are:
52+
53+- `$title`: Title of the item. This is set in our posts, since we use a `title`
54+ metadata field.
55+- `$url`: Url of the item. This is automatically set by Hakyll, so you shouldn't
56+ worry about it.
57+- `$description`: A description of our item to appear in the feed reader.
58+
59+The latter is obviously the problem: we don't have a description in our posts.
60+In fact, we would like to copy the `$body` key to the `$description` key, so
61+people can read the full post in their feed readers.
62+
63+## Where arrows come in
64+
65+The `Text.Hakyll.ContextManipulations` module contains a number of simple
66+functions that create Arrows for us. One of these functions is `copyValue`,
67+which takes a source and a destination key. So, we need to pass our
68+items through this Arrow first.
69+
70+~~~~~{.haskell}
71+renderRss myFeedConfiguration $
72+ map (>>> copyValue "body" "description") (take 3 postPages)
73+~~~~~
74+
75+And that's that, now our feed gets rendered properly. Exercise for the reader
76+is to add a Atom feed[^2].
77+
78+[^2]: Hint: look around in the [reference]($root/reference.html).
79+
80+## The gist of it
81+
82+- Hakyll has native support for RSS and Atom feeds.
83+- The items must contain `$title` and `$description` fields.
84+- Arrows can be used to copy values in a `Context`.