git.iko.soy/hakyll
on master help sign in
Bit of template docs
21648b8Jasper Van der Jeugt
src/Hakyll/Web/Template/Context.hs+4
compare with master
unifiedsplit
@@ -96,6 +96,7 @@ bodyField key = field key $ return . itemBody
96
96
97
97
98--------------------------------------------------------------------------------
98--------------------------------------------------------------------------------
99+-- | Map any field to its metadata value, if present
99metadataField :: Context String
100metadataField :: Context String
100metadataField = Context $ \k i -> do
101metadataField = Context $ \k i -> do
101 metadata <- getMetadata $ itemIdentifier i
102 metadata <- getMetadata $ itemIdentifier i
@@ -103,17 +104,20 @@ metadataField = Context $ \k i -> do
103
104
104
105
105--------------------------------------------------------------------------------
106--------------------------------------------------------------------------------
107+-- | Absolute url to the resulting item
106urlField :: String -> Context a
108urlField :: String -> Context a
107urlField key = field key $
109urlField key = field key $
108 fmap (maybe empty toUrl) . getRoute . itemIdentifier
110 fmap (maybe empty toUrl) . getRoute . itemIdentifier
109
111
110
112
111--------------------------------------------------------------------------------
113--------------------------------------------------------------------------------
114+-- | Filepath of the underlying file of the item
112pathField :: String -> Context a
115pathField :: String -> Context a
113pathField key = field key $ return . toFilePath . itemIdentifier
116pathField key = field key $ return . toFilePath . itemIdentifier
114
117
115
118
116--------------------------------------------------------------------------------
119--------------------------------------------------------------------------------
120+-- | This title field takes the basename of the underlying file by default
117titleField :: String -> Context a
121titleField :: String -> Context a
118titleField key = mapContext takeBaseName $ pathField key
122titleField key = mapContext takeBaseName $ pathField key
119
123
web/tutorials/04-compilers.markdown+68
@@ -36,3 +36,71 @@ This is all useful if we want to use Hakyll's templating system.
36
36
37Basic templates
37Basic templates
38---------------
38---------------
39+
40+Let's have a look at a simple template:
41+
42+ <h1>$title$</h1>
43+ <div class="info">Posted on $date$</div>
44+ $body$
45+
46+As you can probably guess, template files just contain text and only the `$`
47+character has special meaning: text between dollar signs ("fields") is replaced
48+when the template is applied. If you want an actual dollar sign in the output,
49+use `$$`.
50+
51+We can easily guess the meaning of `$title$`, `$date$`, and `$body$`, but these
52+are not hard-coded fields: they belong to a certain [Context]. A `Context`
53+determines how the fields are interpreted. It's a [Monoid] and therefore very
54+composable.
55+
56+[Context]: /reference/Hakyll-Web-Template-Context.html
57+[Monoid]: http://learnyouahaskell.com/functors-applicative-functors-and-monoids
58+
59+`field` allows us to create a `Context` for a single field:
60+
61+```haskell
62+field :: String -> (Item a -> Compiler String) -> Context a
63+```
64+
65+Let's try this out. Note that this is for illustration purposes only: you
66+shouldn't have to write complicated fields often. We can implement the `$body$`
67+field like this:
68+
69+```haskell
70+field "body" $ \item -> return (itemBody item) :: Context String
71+```
72+
73+And `$title$` like this:
74+
75+```haskell
76+titleContext :: Context a
77+titleContext :: field "title" $ \item -> do
78+ metadata <- getMetadata (itemIdentifier item)
79+ return $ fromMaybe "No title" $ M.lookup "title" metadata
80+```
81+
82+And compose them using the `Monoid` instance:
83+
84+```haskell
85+context :: Context String
86+context = mconcat
87+ [ titleContext
88+ , field "body" $ return . itemBody
89+ ]
90+```
91+
92+TODO: Write about defaultContext. Extend it with dateField.
93+
94+You usually compile the templates from disk using the aptly named
95+`templateCompiler`:
96+
97+ match "templates/*" $ compile templateCompiler
98+
99+Notice the lack of `route` here: this is because we don't need to write the
100+templates to your `_site` folder, we just want to use them elsewhere.
101+
102+Using them elsewhere is easy: we just use `load`!
103+
104+TODO: Full example: load template, apply. Then `loadAndApplyTemplate`.
105+
106+TODO: Load a list of posts, demonstrate `applyTemplateList`.