@@ -1,6 +1,22 @@
11-- | A Module that allows easy rendering of RSS feeds. If you use this module,
22-- you must make sure you set the `absoluteUrl` field in the main Hakyll
33-- configuration.
4+--
5+-- Apart from that, the main rendering functions (@renderRss@,
6+-- @renderRssWith@, @renderAtom@ all @renderAtomWith@) all assume that you
7+-- pass the list of @Renderable@s so that the most recent entry in the feed is
8+-- the first item in the list.
9+--
10+-- Also note that the @Renderable@s should have (at least) the following
11+-- fields to produce a correct feed:
12+--
13+-- - @$title@: Title of the item.
14+--
15+-- - @$description@: Description to appear in the feed.
16+--
17+-- - @$url@: URL to the item - this is usually set automatically.
18+--
19+-- Furthermore, the feed will not validate if an empty list is passed.
420module Text.Hakyll.Feed
521 ( FeedConfiguration (..)
622 , renderRss
@@ -77,17 +93,8 @@ renderFeedWith manipulation configuration renderables template itemTemplate = do
7793 renderChain [] renderFeedWith'
7894
7995-- | Render an RSS feed with a number of items.
80−--
81−-- Note that the @Renderable@s should have the following fields:
82−--
83−-- - @$title@: Title of the item.
84−--
85−-- - @$description@: Description to appear in the feed.
86−--
87−-- - @$url@: URL to the item - this is usually set automatically.
88−--
8996renderRss :: FeedConfiguration -- ^ Feed configuration.
90− -> [Renderable] -- ^ Items to include in the feed.
97+ -> [Renderable] -- ^ Items to include in the RSS feed.
9198 -> Hakyll ()
9299renderRss = renderRssWith id
93100
@@ -105,14 +112,19 @@ renderRssWith manipulation configuration renderables =
105112 where
106113 manipulation' = manipulation . renderRssDate
107114
115+-- | @ContextManipulation@ that renders a date to RSS format.
108116renderRssDate :: ContextManipulation
109−renderRssDate = renderDate "timestamp" "%a, %d %b %Y %H:%M:%S UT" "No date found."
117+renderRssDate = renderDate "timestamp" "%a, %d %b %Y %H:%M:%S UT"
118+ "No date found."
110119
120+-- | Render an Atom feed with a number of items.
111121renderAtom :: FeedConfiguration
112122 -> [Renderable]
113123 -> Hakyll ()
114124renderAtom = renderAtomWith id
115125
126+-- | A version of @renderAtom@ that allows you to specify a manipulation to
127+-- apply on the @Renderable@s.
116128renderAtomWith :: ContextManipulation -- ^ Manipulation to apply on the items.
117129 -> FeedConfiguration -- ^ Feed configuration.
118130 -> [Renderable] -- ^ Items to include in the feed.
@@ -123,5 +135,6 @@ renderAtomWith manipulation configuration renderables =
123135 where
124136 manipulation' = manipulation . renderAtomDate
125137
138+-- | Render a date to Atom format.
126139renderAtomDate :: ContextManipulation
127140renderAtomDate = renderDate "timestamp" "%Y-%m-%dT%H:%M:%SZ" "No date found."