diff options
| -rw-r--r-- | src/Text/Hakyll/Context.hs | 2 | ||||
| -rw-r--r-- | src/Text/Hakyll/File.hs | 8 | ||||
| -rw-r--r-- | src/Text/Hakyll/Hakyll.hs | 2 | ||||
| -rw-r--r-- | src/Text/Hakyll/Page.hs | 3 | ||||
| -rw-r--r-- | src/Text/Hakyll/Render.hs | 34 | ||||
| -rw-r--r-- | src/Text/Hakyll/Render/Internal.hs | 10 | ||||
| -rw-r--r-- | src/Text/Hakyll/Renderables.hs | 9 | ||||
| -rw-r--r-- | src/Text/Hakyll/Tags.hs | 4 |
8 files changed, 48 insertions, 24 deletions
diff --git a/src/Text/Hakyll/Context.hs b/src/Text/Hakyll/Context.hs index d2c6047..7ea6e70 100644 --- a/src/Text/Hakyll/Context.hs +++ b/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. diff --git a/src/Text/Hakyll/File.hs b/src/Text/Hakyll/File.hs index ed2bbea..0a21638 100644 --- a/src/Text/Hakyll/File.hs +++ b/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 diff --git a/src/Text/Hakyll/Hakyll.hs b/src/Text/Hakyll/Hakyll.hs index c7f6d89..521a348 100644 --- a/src/Text/Hakyll/Hakyll.hs +++ b/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 diff --git a/src/Text/Hakyll/Page.hs b/src/Text/Hakyll/Page.hs index 0c912a9..eec60e9 100644 --- a/src/Text/Hakyll/Page.hs +++ b/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. diff --git a/src/Text/Hakyll/Render.hs b/src/Text/Hakyll/Render.hs index c529d04..47ce287 100644 --- a/src/Text/Hakyll/Render.hs +++ b/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 diff --git a/src/Text/Hakyll/Render/Internal.hs b/src/Text/Hakyll/Render/Internal.hs index 7e5fd37..33ffcdf 100644 --- a/src/Text/Hakyll/Render/Internal.hs +++ b/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. diff --git a/src/Text/Hakyll/Renderables.hs b/src/Text/Hakyll/Renderables.hs index 780f1e4..0fd66b4 100644 --- a/src/Text/Hakyll/Renderables.hs +++ b/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 diff --git a/src/Text/Hakyll/Tags.hs b/src/Text/Hakyll/Tags.hs index 667c2ee..79dcecd 100644 --- a/src/Text/Hakyll/Tags.hs +++ b/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. |