@@ -35,23 +35,25 @@ Features include:
3535- modules for common items such as tags and feeds;
3636- easily extensible.
3737
38−A simple brochure site
39−----------------------
38+Let's get started!
39+------------------
4040
4141We're going to discuss a small brochure site to start with. You can find all
4242code and files necessary to build this site [right here](/examples/brochure.zip)
4343-- feel free to look to them as we go trough the tutorial. There's a number of
4444files we will use:
4545
46− about.rst A simple page written in RST format
47− code.lhs Another page with some code (which can be highlighted)
48− css Directory for CSS files
49− |- default.css The main CSS file
50− \- syntax.css CSS file for code syntax highlighting
51− hakyll.hs Our code to generate the site
52− index.markdown A simple page in markdown format
53− templates Directory for templates
54− \- default.html The main template for the site
46+ about.rst A simple page written in RST format
47+ code.lhs Another page with some code (which can be highlighted)
48+ css Directory for CSS files
49+ |- default.css The main CSS file
50+ \- syntax.css CSS file for code syntax highlighting
51+ hakyll.hs Our code to generate the site
52+ images Directory for images
53+ \- haskell-logo.png The logo of my favorite programming language
54+ index.markdown A simple page in markdown format
55+ templates Directory for templates
56+ \- default.html The main template for the site
5557
5658By default, hakyll will compile everything to the `_site` directory. We can try
5759this like this:
@@ -59,9 +61,85 @@ this like this:
5961 [jasper@phoenix] ghc --make hakyll.hs
6062 [jasper@phoenix] ./hakyll build
6163
64+Instead of using `build`, we can also use `preview`, which will fire up a
65+webserver serving the `_site` directory, so have a look!
66+
67+All files have been compiled, and their output has been placed in the `_site`
68+directory as illustrated in this diagram:
69+
6270
6371
64−### The two layers
72+No magic is involved at all -- we will precisely study how and why our items are
73+compiled like that. All of this is specified in the `hakyll.hs` file.
74+
75+### Images
76+
77+Let's start of with the `images/haskell-logo.png` file, because the processing
78+of this file is very simple: it is simply copied to the output directory. Let's
79+look at the relevant lines in the `hakyll.hs` file:
80+
81+~~~~~{.haskell}
82+match "images/*" $ do
83+ route idRoute
84+ compile copyFileCompiler
85+~~~~~
86+
87+The first line specifies we will describe the process for compiling everything
88+in the `images/` folder: hakyll uses globs for this [^pattern].
89+
90+[^pattern]: A little caveat is that these globs are not `String`s but
91+ `Pattern`s, so you need the `OverloadedStrings` extension.
92+
93+We can see two simple rules next: `route` and `compile`.
94+
95+- `route` determines how the input file(s) get mapped to the output files.
96+ `route` only deals with file names -- not with the actual content!
97+- `compile`, on the other hand, determines how the file content is processed.
98+
99+In this case, we select the `idRoute`: which means the file name will be kept
100+the same (`_site` will always be prepended automatically). This explains the
101+name of `idRoute`: much like the `id` function in Haskell, it also maps values
102+to themselves.
103+
104+For our compiler, we use `copyFileCompiler`, meaning that we don't process the
105+content at all, we just copy the file.
106+
107+### CSS
108+
109+If we look at how the two CSS files are processed, we see something which looks
110+very familiar:
111+
112+~~~~~{.haskell}
113+match "css/*" $ do
114+ route idRoute
115+ compile compressCssCompiler
116+~~~~~
117+
118+Indeed, the only difference with the images is that have now chosen for
119+`compressCssCompiler` -- a compiler which *does* process the content. Let's have
120+a quick look at the type of `compressCssCompiler`:
121+
122+~~~~~{.haskell}
123+compressCssCompiler :: Compiler Resource String
124+~~~~~
125+
126+Intuitively, we can see this as a process which takes a `Resource` and produces
127+a `String`.
128+
129+- A `Resource` is simply the Hakyll representation of an item -- usually just a
130+ file on the disk.
131+- The produced string is the processed CSS.
132+
133+We can wonder what Hakyll does with the resulting `String`. Well, it simply
134+writes this to the file specified in the `route`! As you can see, routes and
135+compilers work together to produce your site.
136+
137+### Pages
138+
139+TODO
140+
141+Old tutorial
142+------------
65143
66144Hakyll consists of two important layers:
67145