@@ -13,9 +13,25 @@
1313-- > The novel is set in a post-apocalyptic near future, where the Earth and
1414-- > its populations have been damaged greatly by Nuclear...
1515--
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.
19+--
20+-- An example, the page @posts\/coding\/2010-01-28-hakyll-categories.markdown@
21+-- would be placed under the `coding` category.
22+--
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.
27+--
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.
1732module Text.Hakyll.Tags
18− ( readTagMap
33+ ( TagMap
34+ , readTagMap
1935 , readCategoryMap
2036 , renderTagCloud
2137 , renderTagLinks
@@ -39,13 +55,14 @@ import Text.Hakyll.Internal.Cache
3955import Text.Hakyll.Internal.Template
4056
4157-- | Type for a tag map.
58+--
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.
4262type TagMap = M.Map String [PagePath]
4363
44−-- | Read a tag map. This creates a map from tags to page paths.
45−--
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@.
64+-- | Read a tag map. This is a internally used function that can be used for
65+-- tags as well as for categories.
4966readMap :: (Context -> [String]) -- ^ Function to get tags from a context.
5067 -> String -- ^ Unique identifier for the tagmap.
5168 -> [PagePath]
@@ -66,16 +83,18 @@ readMap getTagsFunction identifier paths = do
6683 addPaths' = flip (M.insertWith (++)) [path]
6784 return $ foldr addPaths' current tags
6885
69−readTagMap :: String
70− -> [PagePath]
86+-- | Read a @TagMap@, using the @tags@ metadata field.
87+readTagMap :: String -- ^ Unique identifier for the map.
88+ -> [PagePath] -- ^ Paths to get tags from.
7189 -> Hakyll TagMap
7290readTagMap = readMap getTagsFunction
7391 where
7492 getTagsFunction = map trim . splitRegex ","
7593 . fromMaybe [] . M.lookup "tags"
7694
77−readCategoryMap :: String
78− -> [PagePath]
95+-- | Read a @TagMap@, using the subdirectories the pages are placed in.
96+readCategoryMap :: String -- ^ Unique identifier for the map.
97+ -> [PagePath] -- ^ Paths to get tags from.
7998 -> Hakyll TagMap
8099readCategoryMap = readMap $ maybeToList . M.lookup "category"
81100