From d205f96825d73e0ad7efc97a321333dacfbf9e0c Mon Sep 17 00:00:00 2001 From: Jasper Van der Jeugt Date: Thu, 28 Jan 2010 15:26:20 +0100 Subject: Updated documentation and examples. --- examples/hakyll/hakyll.hs | 13 +++---- examples/hakyll/templates/tutorials.html | 2 +- examples/hakyll/tutorial3.markdown | 66 ++++++++++++++++++-------------- examples/simpleblog/hakyll.hs | 10 ++--- examples/simpleblog/index.html | 2 +- examples/simpleblog/posts.html | 2 +- 6 files changed, 48 insertions(+), 47 deletions(-) diff --git a/examples/hakyll/hakyll.hs b/examples/hakyll/hakyll.hs index 92e52df..b7c40db 100644 --- a/examples/hakyll/hakyll.hs +++ b/examples/hakyll/hakyll.hs @@ -14,14 +14,11 @@ main = hakyll $ do directory static "examples" directory static "reference" - tutorials <- liftIO $ liftM (sort . filter (`matchesRegex` "tutorial[0-9]*.markdown")) $ getDirectoryContents "." - let tutorialList = renderAndConcat ["templates/tutorialitem.html"] - (map createPagePath tutorials) - tutorialPage = createCustomPage "tutorials.html" - ("templates/tutorialitem.html" : tutorials) - [ ("title", Left "Tutorials") - , ("tutorials", Right tutorialList) - ] + tutorials <- liftIO $ liftM (sort . filter (`matchesRegex` "^tutorial[0-9]*.markdown$")) $ getDirectoryContents "." + let tutorialPage = createListing "tutorials.html" + "templates/tutorialitem.html" + (map createPagePath tutorials) + [("title", "Tutorials")] renderChain ["templates/tutorials.html", "templates/default.html"] $ withSidebar tutorialPage mapM_ render' $ [ "about.markdown" diff --git a/examples/hakyll/templates/tutorials.html b/examples/hakyll/templates/tutorials.html index eb0126d..3e01bb7 100644 --- a/examples/hakyll/templates/tutorials.html +++ b/examples/hakyll/templates/tutorials.html @@ -3,5 +3,5 @@ Here is a list of tutorials I've written about hakyll:

diff --git a/examples/hakyll/tutorial3.markdown b/examples/hakyll/tutorial3.markdown index 36a4b1b..28636d9 100644 --- a/examples/hakyll/tutorial3.markdown +++ b/examples/hakyll/tutorial3.markdown @@ -72,7 +72,7 @@ we want to show a few recent posts on the index page. ## Custom Pages -Currently, there are 3 renderable datatypes in Hakyll: +Currently, there are 4 renderable datatypes in Hakyll: - `Page`: The result of any rendering action. It is generally not recommended to use pages a lot, because they cannot check dependencies (and therefore, @@ -82,6 +82,8 @@ Currently, there are 3 renderable datatypes in Hakyll: and works on a higher level. - `CustomPage`: Basically the name says it - the preferred way of creating custom pages in Hakyll. +- `CombinedRenderable`: A way of combining two other `Renderable`s - this is + explained in tutorial 2. We will use a `CustomPage` here. Basically, all `Renderable` datatypes are in the end just `key: value` mappings. A CustomPage is created using the @@ -107,8 +109,23 @@ which type to use for the value: result in a String. However - this action _will not be executed_ when the file in `_site` is up-to-date. -First, let us define this `Hakyll String` for our index page. We want to render -every post using a simple template: +However, in this specific case - a list of posts - there is an easier, and more +high-level approach[^1]. Let's look at the signature of `createListing`: + +~~~~~{.haskell} +createListing :: (Renderable a) + -> String + -> FilePath + -> [a] + -> [(String, String)] +~~~~~ + +[^1]: Since Hakyll-1.3 onwards. + +The first argument is the destination url. For our blog, this is of course +`index.html`. The second argument is a template to render _each renderable_ +with. We use `templates/postitem.html` here. This is, as you can see, a simple +template: ~~~~~{.html}
  • @@ -117,41 +134,32 @@ every post using a simple template:
    • ~~~~~ -When every post is rendered with this template, we then want to concatenate the -result. Since rendering and concatenating is pretty common, Hakyll provides us -with a high-level function to do this. +We then give a list of renderables. For our index, these are the 3 last posts. +The last argument of the `createListing` functions lets you specify additional +key-value pairs. We use this to set the title of our page. So, we create our +index page using: ~~~~~{.haskell} -let recentPosts = renderAndConcat ["templates/postitem.html"] - (take 3 renderablePosts) +let index = createListing "index.html" + "templates/postitem.html" + (take 3 renderablePosts) + [("title", "Home")] ~~~~~ -Now, creating our custom page is fairly straight-forward: - -~~~~~{.haskell} -createCustomPage "index.html" - ("templates/postitem.html" : take 3 postPaths) - [ ("title", Left "All posts") - , ("posts", Right recentPosts) - ] -~~~~~ +The result of this will be a `CustomPage`. The body of this page will contain +a concatenation of all the renderables, rendered with the +`templates/postitem.html` template. -You can see our three arguments here. We're rendering `index.html`, then we tell -Hakyll on what files it depends - here the `templates/postitem.html` template -and the latest 3 posts. Finally, we give a `title` value to substitute in the -template, and the result of our concatenation. Of course, we also need to render -this custom page: +Now, we only have to render it: first using the `index.html` template, then +using the `templates/default.html` template. ~~~~~{.haskell} -renderChain ["index.html", "templates/default.html"] $ - createCustomPage "index.html" - ("templates/postitem.html" : take 3 postPaths) - [ ("title", Left "All posts") - , ("posts", Right recentPosts) - ] +renderChain ["index.html", "templates/default.html"] index ~~~~~ -Note that the `index.html` in the `renderChain` list is also a template. +Note that the `index.html` in the `renderChain` list is also a template. Now, +take your time to read the `index.html` template and the other files in the zip +so you understand what is going on here. ## That's that diff --git a/examples/simpleblog/hakyll.hs b/examples/simpleblog/hakyll.hs index bdcb3fe..8b53215 100644 --- a/examples/simpleblog/hakyll.hs +++ b/examples/simpleblog/hakyll.hs @@ -4,7 +4,7 @@ import Text.Hakyll (hakyll) import Text.Hakyll.Render import Text.Hakyll.Context import Text.Hakyll.File (getRecursiveContents, directory) -import Text.Hakyll.Renderables (createPagePath, createCustomPage) +import Text.Hakyll.Renderables (createPagePath, createCustomPage, createListing) import Data.List (sort) import Control.Monad (mapM_, liftM) import Control.Monad.Reader (liftIO) @@ -19,16 +19,12 @@ main = hakyll $ do let renderablePosts = map createPagePath postPaths -- Render index, including recent posts. - let recentPosts = renderAndConcat ["templates/postitem.html"] $ take 3 renderablePosts renderChain ["index.html", "templates/default.html"] $ - createCustomPage "index.html" ("templates/postitem.html" : take 3 postPaths) - [("title", Left "Home"), ("posts", Right recentPosts)] + createListing "index.html" "templates/postitem.html" (take 3 renderablePosts) [("title", "Home")] -- Render all posts list. - let postItems = renderAndConcat ["templates/postitem.html"] $ renderablePosts renderChain ["posts.html", "templates/default.html"] $ - createCustomPage "posts.html" ("templates/postitem.html" : postPaths) - [("title", Left "All posts"), ("posts", Right postItems)] + createListing "posts.html" "templates/postitem.html" renderablePosts [("title", "All posts")] -- Render all posts. liftIO $ putStrLn "Generating posts..." diff --git a/examples/simpleblog/index.html b/examples/simpleblog/index.html index 201cc18..88cc0a2 100644 --- a/examples/simpleblog/index.html +++ b/examples/simpleblog/index.html @@ -1,7 +1,7 @@

    Recent posts

    All posts...
    diff --git a/examples/simpleblog/posts.html b/examples/simpleblog/posts.html index bc1741b..7db1a59 100644 --- a/examples/simpleblog/posts.html +++ b/examples/simpleblog/posts.html @@ -1,4 +1,4 @@

    All posts

    -- cgit v1.2.3