@@ -13,9 +13,25 @@
13-- > The novel is set in a post-apocalyptic near future, where the Earth and
13-- > The novel is set in a post-apocalyptic near future, where the Earth and
14-- > its populations have been damaged greatly by Nuclear...
14-- > its populations have been damaged greatly by Nuclear...
16−-- All the following functions would work with such a format.
16+-- All the following functions would work with such a format. In addition to
17+-- tags, Hakyll also supports categories. The convention when using categories
18+-- is to place pages in subdirectories.
20+-- An example, the page @posts\/coding\/2010-01-28-hakyll-categories.markdown@
21+-- would be placed under the `coding` category.
23+-- Tags or categories are read using the @readTagMap@ and @readCategoryMap@
24+-- functions. Because categories are implemented using tags - categories can
25+-- be seen as tags, with the restriction that a page can only have one
26+-- category - all functions for tags also work with categories.
28+-- When reading a @TagMap@ (which is also used for category maps) using the
29+-- @readTagMap@ or @readCategoryMap@ function, you also have to give a unique
30+-- identifier to it. This identifier is simply for caching reasons, so Hakyll
31+-- can tell different maps apart; it has no other use.
17module Text.Hakyll.Tags
32module Text.Hakyll.Tags
18− ( readTagMap
34+ , readTagMap
19 , readCategoryMap
35 , readCategoryMap
20 , renderTagCloud
36 , renderTagCloud
21 , renderTagLinks
37 , renderTagLinks
@@ -39,13 +55,14 @@ import Text.Hakyll.Internal.Cache
39import Text.Hakyll.Internal.Template
55import Text.Hakyll.Internal.Template
41-- | Type for a tag map.
57-- | Type for a tag map.
59+-- This is a map associating tags or categories to the appropriate pages
60+-- using that tag or category. In the case of categories, each path will only
61+-- appear under one category - this is not the case with tags.
42type TagMap = M.Map String [PagePath]
62type TagMap = M.Map String [PagePath]
44−-- | Read a tag map. This creates a map from tags to page paths.
64+-- | Read a tag map. This is a internally used function that can be used for
45−--
65+-- tags as well as for categories.
46−-- You also have to give a unique identifier for every tagmap. This is for
47−-- caching reasons, so the tagmap will be stored in
48−-- @_cache/_tagmap/identifier@.
49readMap :: (Context -> [String]) -- ^ Function to get tags from a context.
66readMap :: (Context -> [String]) -- ^ Function to get tags from a context.
50 -> String -- ^ Unique identifier for the tagmap.
67 -> String -- ^ Unique identifier for the tagmap.
51 -> [PagePath]
68 -> [PagePath]
@@ -66,16 +83,18 @@ readMap getTagsFunction identifier paths = do
66 addPaths' = flip (M.insertWith (++)) [path]
83 addPaths' = flip (M.insertWith (++)) [path]
67 return $ foldr addPaths' current tags
84 return $ foldr addPaths' current tags
86+-- | Read a @TagMap@, using the @tags@ metadata field.
69−readTagMap :: String
87+readTagMap :: String -- ^ Unique identifier for the map.
70− -> [PagePath]
88+ -> [PagePath] -- ^ Paths to get tags from.
71 -> Hakyll TagMap
89 -> Hakyll TagMap
72readTagMap = readMap getTagsFunction
90readTagMap = readMap getTagsFunction
74 getTagsFunction = map trim . splitRegex ","
92 getTagsFunction = map trim . splitRegex ","
75 . fromMaybe [] . M.lookup "tags"
93 . fromMaybe [] . M.lookup "tags"
95+-- | Read a @TagMap@, using the subdirectories the pages are placed in.
77−readCategoryMap :: String
96+readCategoryMap :: String -- ^ Unique identifier for the map.
78− -> [PagePath]
97+ -> [PagePath] -- ^ Paths to get tags from.
79 -> Hakyll TagMap
98 -> Hakyll TagMap
80readCategoryMap = readMap $ maybeToList . M.lookup "category"
99readCategoryMap = readMap $ maybeToList . M.lookup "category"