@@ -56,6 +56,20 @@ data ContextField
5656
5757
5858--------------------------------------------------------------------------------
59+-- | The 'Context' monoid. Please note that the order in which you
60+-- compose the items is important. For example in
61+--
62+-- > field "A" f1 <> field "A" f2
63+--
64+-- the first context will overwrite the second. This is especially
65+-- important when something is being composed with
66+-- 'metadataField' (or 'defaultContext'). If you want your context to be
67+-- overwritten by the metadata fields, compose it from the right:
68+--
69+-- @
70+-- 'metadataField' \<\> field \"date\" fDate
71+-- @
72+--
5973newtype Context a = Context
6074 { unContext :: String -> Item a -> Compiler ContextField
6175 }
@@ -108,6 +122,17 @@ mapContext f (Context c) = Context $ \k i -> do
108122
109123
110124--------------------------------------------------------------------------------
125+-- | A context that contains (in that order)
126+--
127+-- 1. A @$body$@ field
128+--
129+-- 2. Metadata fields
130+--
131+-- 3. A @$url$@ 'urlField'
132+--
133+-- 4. A @$path$@ 'pathField'
134+--
135+-- 5. A @$title$@ 'titleField'
111136defaultContext :: Context String
112137defaultContext =
113138 bodyField "body" `mappend`