@@ -1,42 +1,8 @@
2−title: Tutorial
2+title: The basics
8−Modern web frameworks make it easy to create huge dynamic websites. Why would
9−anyone still care about a static website?
11−- Static websites are fast, because it's simply files served directly from the
13−- Static websites are secure. Nobody has ever found an SQL injection in static
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.
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.
27−[Haskell]: http://haskell.org/
28−[pandoc]: http://johnmacfarlane.net/pandoc/
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;
38−Let's get started!
5+## Let's get started!
41We're going to discuss a small brochure site to start with. You can find all
7We're going to discuss a small brochure site to start with. You can find all
42code and files necessary to build this site
8code and files necessary to build this site
@@ -83,7 +49,7 @@ look in the directory you cloned or downloaded.
84[brochure-hakyll.hs]: http://github.com/jaspervdj/hakyll-examples/blob/master/brochure/hakyll.hs
50[brochure-hakyll.hs]: http://github.com/jaspervdj/hakyll-examples/blob/master/brochure/hakyll.hs
86−### Images
52+## Images
88Let's start of with the `images/haskell-logo.png` file, because the processing
54Let's start of with the `images/haskell-logo.png` file, because the processing
89of this file is very simple: it is simply copied to the output directory. Let's
55of 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.
123[copyFileCompiler]: /reference/Hakyll-Core-Writable-CopyFile.html#v:copyFileCompiler
89[copyFileCompiler]: /reference/Hakyll-Core-Writable-CopyFile.html#v:copyFileCompiler
127If we look at how the two CSS files are processed, we see something which looks
93If we look at how the two CSS files are processed, we see something which looks
128very familiar:
94very familiar:
@@ -154,7 +120,7 @@ We can wonder what Hakyll does with the resulting `String`. Well, it simply
154writes this to the file specified in the `route`! As you can see, routes and
120writes this to the file specified in the `route`! As you can see, routes and
155compilers work together to produce your site.
121compilers work together to produce your site.
157−### Templates
123+## Templates
159Next, we can see that the templates are compiled:
125Next, we can see that the templates are compiled:
@@ -168,12 +134,12 @@ good impression:
171− <title>Hakyll Example - $title$</title>
137+ <title>Hakyll Example - $$title$$</title>
174− <h1>$title$</h1>
140+ <h1>$$title$$</h1>
@@ -181,7 +147,7 @@ good impression:
181A template is a text file to lay our some content. The content it lays out is
147A template is a text file to lay our some content. The content it lays out is
182called a page -- we'll see that in the next section. The syntax for templates is
148called a page -- we'll see that in the next section. The syntax for templates is
183intentionally very simplistic. You can bind some content by referencing the name
149intentionally 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.
186You might have noticed how we specify a compiler (`compile`), but we don't set
152You might have noticed how we specify a compiler (`compile`), but we don't set
187any `route`. Why is this?
153any `route`. Why is this?
@@ -200,7 +166,7 @@ directory! We want to use it to lay out other items -- so we need to load
201By using the `templates/*` pattern, we compile all templates in one go.
167By using the `templates/*` pattern, we compile all templates in one go.
203−### Pages
169+## Pages
205The code for pages looks suspiciously more complicated:
171The code for pages looks suspiciously more complicated:
@@ -267,9 +233,9 @@ How should we process these pages? [pageCompiler] is the default compiler for
267pages. [pageCompiler] does a few things:
233pages. [pageCompiler] does a few things:
269- It parses the page into body and metadata
235- It parses the page into body and metadata
270−- It adds some extra metadata fields such as `$url$` and `$path$` (you shouldn't
236+- It adds some extra metadata fields such as `$$url$$` and `$$path$$` (you
271− worry about these for now)
237+ shouldn't worry about these for now)
272−- It fill in possible `$key$`'s in it's own body
238+- It fill in possible `$$key$$`'s in it's own body
273- It renders the page using pandoc
239- It renders the page using pandoc
275Which basically means that we end up with a `Page` that has the HTML content we
241Which 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
326More tutorials are in the works...
292More tutorials are in the works...
328−Various tips and tricks
329−-----------------------
331−### Syntax highlighting
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
336− [jasper@phoenix] cabal install --reinstall -fhighlighting pandoc
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.
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
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.
356−### regex-pcre dependency on Mac OS
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:
362− cabal install --extra-include-dirs=/usr/local/include regex-pcre
366− cabal install --extra-include-dirs=/opt/local/include regex-pcre
368−...and proceed to install Hakyll the regular way.
370−[regex-pcre]: http://hackage.haskell.org/package/regex-pcre
371−[pcre]: http://www.pcre.org/
373−### "File name does not match module name" on Mac OS
376− File name does not match module name:
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`.