@@ -72,7 +72,7 @@ we want to show a few recent posts on the index page.
7272
7373## Custom Pages
7474
75−Currently, there are 3 renderable datatypes in Hakyll:
75+Currently, there are 4 renderable datatypes in Hakyll:
7676
7777- `Page`: The result of any rendering action. It is generally not recommended
7878 to use pages a lot, because they cannot check dependencies (and therefore,
@@ -82,6 +82,8 @@ Currently, there are 3 renderable datatypes in Hakyll:
8282 and works on a higher level.
8383- `CustomPage`: Basically the name says it - the preferred way of creating
8484 custom pages in Hakyll.
85+- `CombinedRenderable`: A way of combining two other `Renderable`s - this is
86+ explained in tutorial 2.
8587
8688We will use a `CustomPage` here. Basically, all `Renderable` datatypes are in
8789the end just `key: value` mappings. A CustomPage is created using the
@@ -107,8 +109,23 @@ which type to use for the value:
107109 result in a String. However - this action _will not be executed_ when the file
108110 in `_site` is up-to-date.
109111
110−First, let us define this `Hakyll String` for our index page. We want to render
111−every post using a simple template:
112+However, in this specific case - a list of posts - there is an easier, and more
113+high-level approach[^1]. Let's look at the signature of `createListing`:
114+
115+~~~~~{.haskell}
116+createListing :: (Renderable a)
117+ -> String
118+ -> FilePath
119+ -> [a]
120+ -> [(String, String)]
121+~~~~~
122+
123+[^1]: Since Hakyll-1.3 onwards.
124+
125+The first argument is the destination url. For our blog, this is of course
126+`index.html`. The second argument is a template to render _each renderable_
127+with. We use `templates/postitem.html` here. This is, as you can see, a simple
128+template:
112129
113130~~~~~{.html}
114131<li>
@@ -117,41 +134,32 @@ every post using a simple template:
117134</li>
118135~~~~~
119136
120−When every post is rendered with this template, we then want to concatenate the
121−result. Since rendering and concatenating is pretty common, Hakyll provides us
122−with a high-level function to do this.
137+We then give a list of renderables. For our index, these are the 3 last posts.
138+The last argument of the `createListing` functions lets you specify additional
139+key-value pairs. We use this to set the title of our page. So, we create our
140+index page using:
123141
124142~~~~~{.haskell}
125−let recentPosts = renderAndConcat ["templates/postitem.html"]
126− (take 3 renderablePosts)
143+let index = createListing "index.html"
144+ "templates/postitem.html"
145+ (take 3 renderablePosts)
146+ [("title", "Home")]
127147~~~~~
128148
129−Now, creating our custom page is fairly straight-forward:
130−
131−~~~~~{.haskell}
132−createCustomPage "index.html"
133− ("templates/postitem.html" : take 3 postPaths)
134− [ ("title", Left "All posts")
135− , ("posts", Right recentPosts)
136− ]
137−~~~~~
149+The result of this will be a `CustomPage`. The body of this page will contain
150+a concatenation of all the renderables, rendered with the
151+`templates/postitem.html` template.
138152
139−You can see our three arguments here. We're rendering `index.html`, then we tell
140−Hakyll on what files it depends - here the `templates/postitem.html` template
141−and the latest 3 posts. Finally, we give a `title` value to substitute in the
142−template, and the result of our concatenation. Of course, we also need to render
143−this custom page:
153+Now, we only have to render it: first using the `index.html` template, then
154+using the `templates/default.html` template.
144155
145156~~~~~{.haskell}
146−renderChain ["index.html", "templates/default.html"] $
147− createCustomPage "index.html"
148− ("templates/postitem.html" : take 3 postPaths)
149− [ ("title", Left "All posts")
150− , ("posts", Right recentPosts)
151− ]
157+renderChain ["index.html", "templates/default.html"] index
152158~~~~~
153159
154−Note that the `index.html` in the `renderChain` list is also a template.
160+Note that the `index.html` in the `renderChain` list is also a template. Now,
161+take your time to read the `index.html` template and the other files in the zip
162+so you understand what is going on here.
155163
156164## That's that
157165