aa44d6c · hakyll · git.iko.soy

git.iko.soy/hakyll

Documentation++.

commitaa44d6c0da442887155a47c77f03209224517af0 authorJasper Van der Jeugt <jaspervdj@gmail.com> dateSun 17 Jan 2010, 12:37 (17 years ago) parent0037344

8 files changed+48−24

compare with master

unifiedsplit

src/Text/Hakyll/Context.hs+1−1 src/Text/Hakyll/File.hs+5−3 src/Text/Hakyll/Hakyll.hs+1−1 src/Text/Hakyll/Page.hs+1−2 src/Text/Hakyll/Render.hs+26−8 src/Text/Hakyll/Render/Internal.hs+5−5 src/Text/Hakyll/Renderables.hs+7−2 src/Text/Hakyll/Tags.hs+2−2

src/Text/Hakyll/Context.hs+1−1

@@ -31,7 +31,7 @@ renderValue src dst f context = case M.lookup src context of

3131 Nothing -> context

3232 (Just value) -> M.insert dst (f value) context

3333

34−-- | When the context has a key called `path` in a `yyyy-mm-dd-title.extension`

34+-- | When the context has a key called @path@ in a @yyyy-mm-dd-title.extension@

3535-- format (default for pages), this function can render the date.

3636renderDate :: String -- ^ Key in which the rendered date should be placed.

3737 -> String -- ^ Format to use on the date.

src/Text/Hakyll/File.hs+5−3

@@ -31,11 +31,11 @@ removeLeadingSeparator path

3131 path' = if "$root" `isPrefixOf` path then drop 5 path

3232 else path

3333

34−-- | Convert a relative filepath to a filepath in the destination (_site).

34+-- | Convert a relative filepath to a filepath in the destination (@_site@).

3535toDestination :: FilePath -> FilePath

3636toDestination path = "_site" </> (removeLeadingSeparator path)

3737

38−-- | Convert a relative filepath to a filepath in the cache (_cache).

38+-- | Convert a relative filepath to a filepath in the cache (@_cache@).

3939toCache :: FilePath -> FilePath

4040toCache path = "_cache" </> (removeLeadingSeparator path)

4141

@@ -100,7 +100,9 @@ directory action dir = do

100100 mapM_ action contents

101101

102102-- | Check if a cache file is still valid.

103−isCacheValid :: FilePath -> [FilePath] -> Hakyll Bool

103+isCacheValid :: FilePath -- ^ The cached file.

104+ -> [FilePath] -- ^ Dependencies of the cached file.

105+ -> Hakyll Bool

104106isCacheValid cache depends = do

105107 exists <- liftIO $ doesFileExist cache

106108 if not exists

src/Text/Hakyll/Hakyll.hs+1−1

@@ -19,6 +19,6 @@ data HakyllConfiguration = HakyllConfiguration

1919-- | Our custom monad stack.

2020type Hakyll = ReaderT HakyllConfiguration IO

2121

22−-- | Simplified "ask" function for the Hakyll monad stack.

22+-- | Simplified @ask@ function for the Hakyll monad stack.

2323askHakyll :: (HakyllConfiguration -> a) -> Hakyll a

2424askHakyll = flip liftM ask

src/Text/Hakyll/Page.hs+1−2

@@ -102,8 +102,7 @@ cachePage page@(Page mapping) = do

102102 destination = toCache $ getURL page

103103

104104-- | Read a page from a file. Metadata is supported, and if the filename

105−-- has a .markdown extension, it will be rendered using pandoc. Note that

106−-- pages are not templates, so they should not contain $identifiers.

105+-- has a @.markdown@ extension, it will be rendered using pandoc.

107106readPage :: FilePath -> Hakyll Page

108107readPage pagePath = do

109108 -- Check cache.

src/Text/Hakyll/Render.hs+26−8

@@ -52,27 +52,45 @@ renderWith manipulation templatePath renderable = do

5252 context <- toContext renderable

5353 return $ fromContext $ pureRenderWith manipulation template context

5454

55−-- | Render each renderable with the given template, then concatenate the

56−-- result.

57−renderAndConcat :: Renderable a => FilePath -> [a] -> Hakyll String

55+-- | Render each renderable with the given templates, then concatenate the

56+-- result. So, basically this function:

57+--

58+-- * Takes every renderable.

59+--

60+-- * Renders every renderable with all given templates. This is comparable

61+-- with a renderChain action.

62+--

63+-- * Concatenates the result.

64+--

65+renderAndConcat :: Renderable a

66+ => [FilePath] -- ^ Templates to apply on every renderable.

67+ -> [a] -- ^ Renderables to render.

68+ -> Hakyll String

5869renderAndConcat = renderAndConcatWith id

5970

60−-- | Render each renderable with the given template, then concatenate the

71+-- | Render each renderable with the given templates, then concatenate the

6172-- result. This function allows you to specify a "ContextManipulation" to

6273-- apply on every "Renderable".

6374renderAndConcatWith :: Renderable a

6475 => ContextManipulation

65− -> FilePath

76+ -> [FilePath]

6677 -> [a]

6778 -> Hakyll String

68−renderAndConcatWith manipulation templatePath renderables = do

69− template <- liftIO $ readFile templatePath

79+renderAndConcatWith manipulation templatePaths renderables = do

80+ templates <- liftIO $ mapM readFile templatePaths

7081 contexts <- mapM toContext renderables

71− return $ pureRenderAndConcatWith manipulation template contexts

82+ return $ pureRenderAndConcatWith manipulation templates contexts

7283

7384-- | Chain a render action for a page with a number of templates. This will

7485-- also write the result to the site destination. This is the preferred way

7586-- to do general rendering.

87+--

88+-- > renderChain [ "templates/notice.html"

89+-- > , "templates/default.html"

90+-- > ] $ createPagePath "warning.html"

91+--

92+-- This code will first render @warning.html@ using @templates/notice.html@,

93+-- and will then render the result with @templates/default.html@.

7694renderChain :: Renderable a => [FilePath] -> a -> Hakyll ()

7795renderChain = renderChainWith id

7896

src/Text/Hakyll/Render/Internal.hs+5−5

@@ -21,9 +21,9 @@ import Text.Hakyll.Page

2121import Text.Hakyll.File

2222import Text.Hakyll.Hakyll

2323

24−-- | Substitutes `$identifiers` in the given string by values from the given

24+-- | Substitutes @$identifiers@ in the given string by values from the given

2525-- "Context". When a key is not found, it is left as it is. You can here

26−-- specify the characters used to replace escaped dollars `$$`.

26+-- specify the characters used to replace escaped dollars (@$$@).

2727substitute :: String -> String -> Context -> String

2828substitute _ [] _ = []

2929substitute escaper string context

@@ -60,14 +60,14 @@ pureRenderWith manipulation template context =

6060

6161-- | A pure renderAndConcat function.

6262pureRenderAndConcatWith :: ContextManipulation

63− -> String -- ^ Template to use.

63+ -> [String] -- ^ Templates to use.

6464 -> [Context] -- ^ Different renderables.

6565 -> String

66−pureRenderAndConcatWith manipulation template contexts =

66+pureRenderAndConcatWith manipulation templates contexts =

6767 foldl' renderAndConcat [] contexts

6868 where

6969 renderAndConcat chunk context =

70− let rendered = pureRenderWith manipulation template context

70+ let rendered = pureRenderChainWith manipulation templates context

7171 in chunk ++ fromMaybe "" (M.lookup "body" rendered)

7272

7373-- | A pure renderChain function.

src/Text/Hakyll/Renderables.hs+7−2

@@ -19,10 +19,15 @@ data CustomPage = CustomPage

1919 }

2020

2121-- | Create a custom page.

22+--

23+-- The association list given maps keys to values for substitution. Note

24+-- that as value, you can either give a @String@ or a @Hakyll String@.

25+-- A @Hakyll String@ is preferred for more complex data, since it allows

26+-- dependency checking. A @String@ is obviously more simple to use in some

27+-- cases.

2228createCustomPage :: String -- ^ Destination of the page, relative to _site.

2329 -> [FilePath] -- ^ Dependencies of the page.

24− -> [(String, Either String (Hakyll String))] -- ^ Key - value

25− -- mapping.

30+ -> [(String, Either String (Hakyll String))] -- ^ Mapping.

2631 -> CustomPage

2732createCustomPage = CustomPage

2833

src/Text/Hakyll/Tags.hs+2−2

@@ -19,7 +19,7 @@ import Text.Hakyll.Page

1919import Control.Arrow (second)

2020

2121-- | Read a tag map. This creates a map from tags to page paths. This function

22−-- assumes the tags are located in the `tags` metadata field, separated by

22+-- assumes the tags are located in the @tags@ metadata field, separated by

2323-- commas.

2424readTagMap :: [FilePath] -> Hakyll (M.Map String [FilePath])

2525readTagMap paths = foldM addPaths M.empty paths

@@ -30,7 +30,7 @@ readTagMap paths = foldM addPaths M.empty paths

3030 return $ foldr (\t -> M.insertWith (++) t [path]) current tags

3131

3232-- | Render a tag cloud.

33−renderTagCloud :: M.Map String [FilePath] -- ^ Map as produced by 'readTagMap'.

33+renderTagCloud :: M.Map String [FilePath] -- ^ Map as produced by "readTagMap".

3434 -> (String -> String) -- ^ Function to produce an url for a tag.

3535 -> Float -- ^ Smallest font size, in percent.

3636 -> Float -- ^ Biggest font size, in percent.