diff options
| -rw-r--r-- | examples/hakyll/tutorials/part05.markdown | 84 |
1 files changed, 84 insertions, 0 deletions
diff --git a/examples/hakyll/tutorials/part05.markdown b/examples/hakyll/tutorials/part05.markdown new file mode 100644 index 0000000..8420ef1 --- /dev/null +++ b/examples/hakyll/tutorials/part05.markdown @@ -0,0 +1,84 @@ +--- +title: Creating feeds +what: adds an rss feed to the simple blog +--- + +## Adding Feeds + +In this tutorial, we're going to add an RSS feed to the blog we wrote in the +previous part. Here is a [zip file] containing the source. + +[zip file]: examples/feedblog.zip + +You will be glad to hear that Hakyll has native support for RSS as well as Atom +feeds[^1]. This simplifies our object a lot. + +[^1]: Since Hakyll-2.0 + +This is the first time that the absolute URL of your site you have to give to +the `hakyll` function actually matters. That's because the specifications of +those feed formats dictate you need the full URL of them. + +## Creating a configuration + +The first thing to do is creating a configuration for your feed. You could +place this code outside of your main function, as is done in the example. + +~~~~~{.haskell} +myFeedConfiguration = FeedConfiguration + { feedUrl = "rss.xml" + , feedTitle = "SimpleBlog RSS feed." + , feedDescription = "Simple demo of a feed created with Hakyll." + , feedAuthorName = "Jasper Van der Jeugt" + } +~~~~~ + +Note that we enter the url of the feed in our configuration. So the function +to render our feed only takes two arguments, the configuration and a list of +items to put in the feed. Let's put the three most recent posts in our feed. + +~~~~~{.haskell} +renderRss myFeedConfiguration (take 3 postPages) +~~~~~ + +## But it's not that easy + +If you look at our generated RSS feed (build the site), you will see +`$description` tags appearing in our final render. We don't want that! How +did they get there in the first place? + +To render feeds, Hakyll expects a number of fields in the renderables you put +in the feed. They are: + +- `$title`: Title of the item. This is set in our posts, since we use a `title` + metadata field. +- `$url`: Url of the item. This is automatically set by Hakyll, so you shouldn't + worry about it. +- `$description`: A description of our item to appear in the feed reader. + +The latter is obviously the problem: we don't have a description in our posts. +In fact, we would like to copy the `$body` key to the `$description` key, so +people can read the full post in their feed readers. + +## Where arrows come in + +The `Text.Hakyll.ContextManipulations` module contains a number of simple +functions that create Arrows for us. One of these functions is `copyValue`, +which takes a source and a destination key. So, we need to pass our +items through this Arrow first. + +~~~~~{.haskell} +renderRss myFeedConfiguration $ + map (>>> copyValue "body" "description") (take 3 postPages) +~~~~~ + +And that's that, now our feed gets rendered properly. Exercise for the reader +is to add a Atom feed[^2]. + +[^2]: Hint: look around in the [reference]($root/reference.html). + +## The gist of it + +- Hakyll has native support for RSS and Atom feeds. +- The items must contain `$title` and `$description` fields. +- Arrows can be used to copy values in a `Context`. |