@@ -1,7 +1,7 @@
11module Text.Hakyll.Render
22 ( depends,
3− render,
43 writePage,
4+ render,
55 renderAndConcat,
66 renderChain,
77 static,
@@ -20,12 +20,27 @@ import Text.Hakyll.Page
2020import Text.Hakyll.Renderable
2121import Text.Hakyll.Util
2222
23−depends :: FilePath -> [FilePath] -> IO () -> IO ()
23+-- | Execute an IO action only when the cache is invalid.
24+depends :: FilePath -- ^ File to be rendered or created.
25+ -> [FilePath] -- ^ Files the render depends on.
26+ -> IO () -- ^ IO action to execute when the file is out of date.
27+ -> IO ()
2428depends file dependencies action = do
2529 valid <- isCacheValid (toDestination file) dependencies
2630 unless valid action
2731
28−render :: Renderable a => FilePath -> a -> IO Page
32+-- | Write a page to the site destination.
33+writePage :: Page -> IO ()
34+writePage page = do
35+ let destination = toDestination $ getURL page
36+ makeDirectories destination
37+ B.writeFile destination (getBody page)
38+
39+-- | Render to a Page.
40+render :: Renderable a
41+ => FilePath -- ^ Template to use for rendering.
42+ -> a -- ^ Renderable object to render with given template.
43+ -> IO Page -- ^ The body of the result will contain the render.
2944render templatePath renderable = do
3045 handle <- openFile templatePath ReadMode
3146 templateString <- liftM B.pack $ hGetContents handle
@@ -34,12 +49,8 @@ render templatePath renderable = do
3449 let body = substitute templateString context
3550 return $ fromContext (M.insert (B.pack "body") body context)
3651
37−writePage :: Page -> IO ()
38−writePage page = do
39− let destination = toDestination $ getURL page
40− makeDirectories destination
41− B.writeFile destination (getBody page)
42−
52+-- | Render each renderable with the given template, then concatenate the
53+-- result.
4354renderAndConcat :: Renderable a => FilePath -> [a] -> IO B.ByteString
4455renderAndConcat templatePath renderables = foldM concatRender' B.empty renderables
4556 where concatRender' :: Renderable a => B.ByteString -> a -> IO B.ByteString
@@ -48,6 +59,9 @@ renderAndConcat templatePath renderables = foldM concatRender' B.empty renderabl
4859 let body = getBody rendered
4960 return $ B.append chunk $ body
5061
62+-- | Chain a render action for a page with a number of templates. This will
63+-- also write the result to the site destination. This is the preferred way
64+-- to do general rendering.
5165renderChain :: Renderable a => [FilePath] -> a -> IO ()
5266renderChain templates renderable =
5367 depends (getURL renderable) (getDependencies renderable ++ templates) $
@@ -55,12 +69,15 @@ renderChain templates renderable =
5569 result <- foldM (flip render) (fromContext initialPage) templates
5670 writePage result
5771
72+-- | Mark a certain file as static, so it will just be copied when the site is
73+-- generated.
5874static :: FilePath -> IO ()
5975static source = do
6076 makeDirectories destination
6177 copyFile source destination
6278 where destination = toDestination source
6379
80+-- | Mark a whole directory as static.
6481staticDirectory :: FilePath -> IO ()
6582staticDirectory dir =
6683 getRecursiveContents dir >>= mapM_ static