@@ -1,42 +1,8 @@
11---
2−title: Tutorial
2+title: The basics
33---
44
5−Why static websites?
6−--------------------
7−
8−Modern web frameworks make it easy to create huge dynamic websites. Why would
9−anyone still care about a static website?
10−
11−- Static websites are fast, because it's simply files served directly from the
12− hard disk.
13−- Static websites are secure. Nobody has ever found an SQL injection in static
14− pages.
15−- Static websites are easy to deploy. Just copy them to your webhost using
16− (S)FTP/rsync/scp and you are done. They work on all webhosts: no CGI or extra
17− modules needed for the web server.
18−
19−Why Hakyll?
20−-----------
21−
22−Hakyll is a [Haskell] library meant for creating small-to-medium sized static
23−websites. It is a powerful publishing tool, precisely because of the power of
24−Haskell. By using the awesome [pandoc] library, it is able to create your
25−website from a large variety of input formats.
26−
27−[Haskell]: http://haskell.org/
28−[pandoc]: http://johnmacfarlane.net/pandoc/
29−
30−Features include:
31−
32−- easy templating system;
33−- a simple HTTP server for previewing and compiling your website on the go;
34−- powerful syntax highlighting;
35−- modules for common items such as tags and feeds;
36−- easily extensible.
37−
38−Let's get started!
39−------------------
5+## Let's get started!
406
417We're going to discuss a small brochure site to start with. You can find all
428code and files necessary to build this site
@@ -83,7 +49,7 @@ look in the directory you cloned or downloaded.
8349
8450[brochure-hakyll.hs]: http://github.com/jaspervdj/hakyll-examples/blob/master/brochure/hakyll.hs
8551
86−### Images
52+## Images
8753
8854Let's start of with the `images/haskell-logo.png` file, because the processing
8955of this file is very simple: it is simply copied to the output directory. Let's
@@ -122,7 +88,7 @@ content at all, we just copy the file.
12288
12389[copyFileCompiler]: /reference/Hakyll-Core-Writable-CopyFile.html#v:copyFileCompiler
12490
125−### CSS
91+## CSS
12692
12793If we look at how the two CSS files are processed, we see something which looks
12894very familiar:
@@ -154,7 +120,7 @@ We can wonder what Hakyll does with the resulting `String`. Well, it simply
154120writes this to the file specified in the `route`! As you can see, routes and
155121compilers work together to produce your site.
156122
157−### Templates
123+## Templates
158124
159125Next, we can see that the templates are compiled:
160126
@@ -168,12 +134,12 @@ good impression:
168134~~~~~
169135<html>
170136 <head>
171− <title>Hakyll Example - $title$</title>
137+ <title>Hakyll Example - $$title$$</title>
172138 </head>
173139 <body>
174− <h1>$title$</h1>
140+ <h1>$$title$$</h1>
175141
176− $body$
142+ $$body$$
177143 </body>
178144</html>
179145~~~~~
@@ -181,7 +147,7 @@ good impression:
181147A template is a text file to lay our some content. The content it lays out is
182148called a page -- we'll see that in the next section. The syntax for templates is
183149intentionally very simplistic. You can bind some content by referencing the name
184−of the content *field* by using `$field$`, and that's it.
150+of the content *field* by using `$$field$$`, and that's it.
185151
186152You might have noticed how we specify a compiler (`compile`), but we don't set
187153any `route`. Why is this?
@@ -200,7 +166,7 @@ directory! We want to use it to lay out other items -- so we need to load
200166
201167By using the `templates/*` pattern, we compile all templates in one go.
202168
203−### Pages
169+## Pages
204170
205171The code for pages looks suspiciously more complicated:
206172
@@ -267,9 +233,9 @@ How should we process these pages? [pageCompiler] is the default compiler for
267233pages. [pageCompiler] does a few things:
268234
269235- It parses the page into body and metadata
270−- It adds some extra metadata fields such as `$url$` and `$path$` (you shouldn't
271− worry about these for now)
272−- It fill in possible `$key$`'s in it's own body
236+- It adds some extra metadata fields such as `$$url$$` and `$$path$$` (you
237+ shouldn't worry about these for now)
238+- It fill in possible `$$key$$`'s in it's own body
273239- It renders the page using pandoc
274240
275241Which basically means that we end up with a `Page` that has the HTML content we
@@ -324,59 +290,3 @@ at `example.com` and `example.com/subdir` without changing a single line of
324290code.
325291
326292More tutorials are in the works...
327−
328−Various tips and tricks
329−-----------------------
330−
331−### Syntax highlighting
332−
333−Syntax highlighting is enabled by default in Hakyll. However, you also need to
334−enable it in pandoc. If no syntax highlighting shows up, try
335−
336− [jasper@phoenix] cabal install --reinstall -fhighlighting pandoc
337−
338−### When to rebuild
339−
340−If you execute a `./hakyll build`, Hakyll will build your site incrementally.
341−This means it will be very fast, but it will not pick up _all_ changes.
342−
343−- In case you edited `hakyll.hs`, you first want to compile it again.
344−- It is generally recommended to do a `./hakyll rebuild` before you deploy your
345− site.
346−
347−After rebuilding your site, all files will look as "modified" to the filesystem.
348−This means that when you upload your site, it will usually transfer all files --
349−this can generate more traffic than necessary, since it is possible that some
350−files were not actually modified. If you use `rsync`, you can counter this using
351−the `--checksum` option.
352−
353−Problems
354−--------
355−
356−### regex-pcre dependency on Mac OS
357−
358−Hakyll requires [regex-pcre], which might fail to build on Mac OS. To solve
359−this problem, make sure the [pcre] C library is installed (via homebrew or
360−macports). Then install [regex-pcre] using:
361−
362− cabal install --extra-include-dirs=/usr/local/include regex-pcre
363−
364−or
365−
366− cabal install --extra-include-dirs=/opt/local/include regex-pcre
367−
368−...and proceed to install Hakyll the regular way.
369−
370−[regex-pcre]: http://hackage.haskell.org/package/regex-pcre
371−[pcre]: http://www.pcre.org/
372−
373−### "File name does not match module name" on Mac OS
374−
375− Hakyll.hs:1:1:
376− File name does not match module name:
377− Saw: `Main'
378− Expected: `Hakyll'
379−
380−Is an error encountered on Mac OS when `hakyll.hs` is located on a
381−case-insensitive filesystem. A workaround is to rename it to something that
382−isn't the name of the module, for example, `site.hs`.