@@ -1,3 +1,113 @@
11# Hakyll
22
3−Hakyll is a simple static site generator in Haskell.
3+Hakyll is a simple static site generator in Haskell. It is mostly inspired by
4+[Jekyll](http://github.com/mojombo/jekyll), but I like to believe it is
5+simpler.
6+
7+## Configuration
8+
9+Inspired by [xmonad](http://xmonad.org), a small Haskell program is used as
10+configuration file. In this file, you give instructions on how the site should
11+be generated. In the rest of this document, we will examine a small example.
12+
13+## Static files
14+
15+Static files can be rendered using the `static` command. This command ensures
16+the files will copied when you compile the site.
17+
18+For convenience reasons, there is also a `staticDirectory` command, which works
19+recursively.
20+
21+ main = do
22+ static "favicon.ico"
23+ staticDirectory "images"
24+ staticDirectory "css"
25+
26+## Pages
27+
28+Pages can be written in html or markdown (altough it would be a trivial task
29+to add anything pandoc supports, just ask me if you want anything to be added).
30+They can also contain metadata, which are always key-value mappings.
31+
32+## Templates
33+
34+Templates are rendered using the Haskell `Text.Template` library. This means
35+that in your template, you can use `$identifier`, and it will be replaced by
36+the value of `identifier`.
37+
38+ ---
39+ author: Jasper Van der Jeugt
40+ title: A sample markdown post
41+ ---
42+ # A sample markdown post
43+
44+ This is a sample markdown post. It supports pandoc extensions
45+ like code highlighting. For example:
46+
47+ ~~~~{.haskell}
48+ main = putStrLn "Hello World!"
49+ ~~~~
50+
51+Metadata is always placed in the beginning of a file, and is delimited by a
52+`---` string. The metadata can only contain simple key-value pairs. We can
53+now read in this page using the `Text.Hakyll.Page.readPage` function. This
54+will return a `Page`, which is actually just a `Map String String`. In this
55+example, the map would consist of the following key-value pairs:
56+
57+- `author`: `Jasper Van der Jeugt`
58+- `title`: `A sample markdown post`
59+- `body`: The rest of the file (rendered to html).
60+- `url`: `text.html` (the original filename was `text.markdown`, the extension
61+ was changed to html).
62+
63+## Templates
64+
65+In hakyll, there is a strict separation between pages and templates. Templates,
66+for example, cannot contain metadata.
67+
68+ <h2> $title </h2>
69+ by <strong> $author </title>
70+
71+ $body
72+
73+Is a template we could, for example, render the file we saw in the previous
74+section. It would go like this:
75+
76+ page <- readPage "text.markdown"
77+ render <- renderPage "templates/sample.html" page
78+
79+Now, `render` will be a `Page` containing all metadata from `page`, but the
80+`body` key would be replaced by the substitution. This means we can combine
81+rendering actions. Given another template `templates/default.html`:
82+
83+ <html>
84+ <head>
85+ <title> $title </title>
86+ </head>
87+ <body>
88+ $body
89+ </body>
90+ </html>
91+
92+We can now combine the rendering actions:
93+
94+ page <- readPage "text.markdown"
95+ render <- (renderPage "templates/sample.html" page >>=
96+ renderPage "templates/default.html")
97+
98+Of course, you can't really do anything with the render if you don't write it
99+to a file somewhere. That's why the function `renderAndWrite` exists:
100+
101+ readPage "text.markdown" >>=
102+ renderPage "templates/sample.html" page >>=
103+ renderAndWrite "templates/default.html"
104+
105+Now, where will this file be written? In `_site/text.html`, of course! That's
106+because the page still contains a key called `url`, which the renderAndWrite
107+function uses to determine the file destination.
108+
109+## More advanced things
110+
111+Sometimes, you want to create a `Page` from scratch, without reading from a
112+file. There are functions to do that for you, and I suggest you read the
113+documentation of `Text.Hakyll.Page`.