Documentation++.

src/Text/Hakyll/Context.hs

@@ -31,7 +31,7 @@ renderValue src dst f context = case M.lookup src context of
     Nothing      -> context
     (Just value) -> M.insert dst (f value) context
 
--- | When the context has a key called `path` in a `yyyy-mm-dd-title.extension`
+-- | When the context has a key called @path@ in a @yyyy-mm-dd-title.extension@
 --   format (default for pages), this function can render the date.
 renderDate :: String -- ^ Key in which the rendered date should be placed.
            -> String -- ^ Format to use on the date.

src/Text/Hakyll/File.hs

@@ -31,11 +31,11 @@ removeLeadingSeparator path
     path' = if "$root" `isPrefixOf` path then drop 5 path
                                          else path
 
--- | Convert a relative filepath to a filepath in the destination (_site).
+-- | Convert a relative filepath to a filepath in the destination (@_site@).
 toDestination :: FilePath -> FilePath
 toDestination path = "_site" </> (removeLeadingSeparator path)
 
--- | Convert a relative filepath to a filepath in the cache (_cache).
+-- | Convert a relative filepath to a filepath in the cache (@_cache@).
 toCache :: FilePath -> FilePath
 toCache path = "_cache" </> (removeLeadingSeparator path)
 
@@ -100,7 +100,9 @@ directory action dir = do
     mapM_ action contents
 
 -- | Check if a cache file is still valid.
-isCacheValid :: FilePath -> [FilePath] -> Hakyll Bool
+isCacheValid :: FilePath -- ^ The cached file.
+             -> [FilePath] -- ^ Dependencies of the cached file.
+             -> Hakyll Bool
 isCacheValid cache depends = do
     exists <- liftIO $ doesFileExist cache
     if not exists

src/Text/Hakyll/Hakyll.hs

@@ -19,6 +19,6 @@ data HakyllConfiguration = HakyllConfiguration
 -- | Our custom monad stack.
 type Hakyll = ReaderT HakyllConfiguration IO
 
--- | Simplified "ask" function for the Hakyll monad stack.
+-- | Simplified @ask@ function for the Hakyll monad stack.
 askHakyll :: (HakyllConfiguration -> a) -> Hakyll a
 askHakyll = flip liftM ask

src/Text/Hakyll/Page.hs

@@ -102,8 +102,7 @@ cachePage page@(Page mapping) = do
     destination = toCache $ getURL page
 
 -- | Read a page from a file. Metadata is supported, and if the filename
---   has a .markdown extension, it will be rendered using pandoc. Note that
---   pages are not templates, so they should not contain $identifiers.
+--   has a @.markdown@ extension, it will be rendered using pandoc.
 readPage :: FilePath -> Hakyll Page
 readPage pagePath = do
     -- Check cache.

src/Text/Hakyll/Render.hs

@@ -52,27 +52,45 @@ renderWith manipulation templatePath renderable = do
     context <- toContext renderable
     return $ fromContext $ pureRenderWith manipulation template context
 
--- | Render each renderable with the given template, then concatenate the
---   result.
-renderAndConcat :: Renderable a => FilePath -> [a] -> Hakyll String
+-- | Render each renderable with the given templates, then concatenate the
+--   result. So, basically this function:
+--
+--   * Takes every renderable.
+--
+--   * Renders every renderable with all given templates. This is comparable
+--     with a renderChain action.
+--
+--   * Concatenates the result.
+--
+renderAndConcat :: Renderable a
+                => [FilePath] -- ^ Templates to apply on every renderable.
+                -> [a] -- ^ Renderables to render.
+                -> Hakyll String
 renderAndConcat = renderAndConcatWith id
 
--- | Render each renderable with the given template, then concatenate the
+-- | Render each renderable with the given templates, then concatenate the
 --   result. This function allows you to specify a "ContextManipulation" to
 --   apply on every "Renderable".
 renderAndConcatWith :: Renderable a
                     => ContextManipulation
-                    -> FilePath
+                    -> [FilePath]
                     -> [a]
                     -> Hakyll String
-renderAndConcatWith manipulation templatePath renderables = do
-    template <- liftIO $ readFile templatePath
+renderAndConcatWith manipulation templatePaths renderables = do
+    templates <- liftIO $ mapM readFile templatePaths
     contexts <- mapM toContext renderables
-    return $ pureRenderAndConcatWith manipulation template contexts
+    return $ pureRenderAndConcatWith manipulation templates contexts
 
 -- | Chain a render action for a page with a number of templates. This will
 --   also write the result to the site destination. This is the preferred way
 --   to do general rendering.
+--
+--   > renderChain [ "templates/notice.html"
+--   >             , "templates/default.html"
+--   >             ] $ createPagePath "warning.html"
+--
+--   This code will first render @warning.html@ using @templates/notice.html@,
+--   and will then render the result with @templates/default.html@.
 renderChain :: Renderable a => [FilePath] -> a -> Hakyll ()
 renderChain = renderChainWith id
 

src/Text/Hakyll/Render/Internal.hs

@@ -21,9 +21,9 @@ import Text.Hakyll.Page
 import Text.Hakyll.File
 import Text.Hakyll.Hakyll
 
--- | Substitutes `$identifiers` in the given string by values from the given
+-- | Substitutes @$identifiers@ in the given string by values from the given
 --   "Context". When a key is not found, it is left as it is. You can here
---   specify the characters used to replace escaped dollars `$$`.
+--   specify the characters used to replace escaped dollars (@$$@).
 substitute :: String -> String -> Context -> String 
 substitute _ [] _ = []
 substitute escaper string context 
@@ -60,14 +60,14 @@ pureRenderWith manipulation template context =
 
 -- | A pure renderAndConcat function.
 pureRenderAndConcatWith :: ContextManipulation
-                        -> String -- ^ Template to use.
+                        -> [String] -- ^ Templates to use.
                         -> [Context] -- ^ Different renderables.
                         -> String
-pureRenderAndConcatWith manipulation template contexts =
+pureRenderAndConcatWith manipulation templates contexts =
     foldl' renderAndConcat [] contexts
   where
     renderAndConcat chunk context =
-        let rendered = pureRenderWith manipulation template context
+        let rendered = pureRenderChainWith manipulation templates context
         in chunk ++ fromMaybe "" (M.lookup "body" rendered)
 
 -- | A pure renderChain function.

src/Text/Hakyll/Renderables.hs

@@ -19,10 +19,15 @@ data CustomPage = CustomPage
     }
 
 -- | Create a custom page.
+--   
+--   The association list given maps keys to values for substitution. Note
+--   that as value, you can either give a @String@ or a @Hakyll String@.
+--   A @Hakyll String@ is preferred for more complex data, since it allows
+--   dependency checking. A @String@ is obviously more simple to use in some
+--   cases.
 createCustomPage :: String -- ^ Destination of the page, relative to _site.
                  -> [FilePath] -- ^ Dependencies of the page.
-                 -> [(String, Either String (Hakyll String))] -- ^ Key - value 
-                                                              --   mapping.
+                 -> [(String, Either String (Hakyll String))] -- ^ Mapping.
                  -> CustomPage
 createCustomPage = CustomPage
 

src/Text/Hakyll/Tags.hs

@@ -19,7 +19,7 @@ import Text.Hakyll.Page
 import Control.Arrow (second)
 
 -- | Read a tag map. This creates a map from tags to page paths. This function
---   assumes the tags are located in the `tags` metadata field, separated by
+--   assumes the tags are located in the @tags@ metadata field, separated by
 --   commas.
 readTagMap :: [FilePath] -> Hakyll (M.Map String [FilePath])
 readTagMap paths = foldM addPaths M.empty paths
@@ -30,7 +30,7 @@ readTagMap paths = foldM addPaths M.empty paths
         return $ foldr (\t -> M.insertWith (++) t [path]) current tags
 
 -- | Render a tag cloud.
-renderTagCloud :: M.Map String [FilePath] -- ^ Map as produced by 'readTagMap'.
+renderTagCloud :: M.Map String [FilePath] -- ^ Map as produced by "readTagMap".
                -> (String -> String) -- ^ Function to produce an url for a tag.
                -> Float -- ^ Smallest font size, in percent.
                -> Float -- ^ Biggest font size, in percent.