Documentation++.
This commit is contained in:
parent
0037344424
commit
aa44d6c0da
8 changed files with 48 additions and 24 deletions
|
@ -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.
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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.
|
||||
|
|
|
@ -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
|
||||
|
||||
|
|
|
@ -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.
|
||||
|
|
|
@ -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
|
||||
|
||||
|
|
|
@ -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.
|
||||
|
|
Loading…
Reference in a new issue