@@ -19,115 +19,26 @@ directories:
1919In general, it's only necessary to use `rebuild` when you made changes to your
2020`site.hs`, and not when you just made changes to the contents of your website.
2121
22−Basic rules
23−-----------
22+At this point, feel free to change some files, `./site build` and see what
23+happens!
2424
25−Let's take a look at the `site.hs` file.
25+Pages and metadata
26+------------------
2627
27−```haskell
28−main :: IO ()
29−main = hakyll $ do
30− ...
31−```
28+You might've noticed that the markdown pages all start with a block:
3229
33−Hakyll configurations are in the `Rules` monad. In order to run them, the
34−`hakyll` function is used, so your main function usually starts this way.
35−`hakyllWith` is also available, this function allows you specify a custom
36−[Configuration].
30+ ---
31+ title: Contact
32+ ---
3733
38−[Configuration]: /reference/Hakyll-Core-Configuration.html
34+ I live...
3935
40−Some actual rules look like this:
36+This is entirely optional, but useful for providing extra information
37+("metadata") about items. All items can have metadata: since it's not really
38+convenient to add such a header to an image, you can also do this using a
39+separate file.
4140
42−```haskell
43−match "images/*" $ do
44− route idRoute
45− compile copyFileCompiler
41+For a file called `images/foo.png`, you can add an `images/foo.png.metadata`
42+file with contents:
4643
47−match "css/*" $ do
48− route idRoute
49− compile compressCssCompiler
50−
51−```
52−
53−This is a declarative DSL: the order in which you write the rules make little
54−difference: Hakyll will use dependency tracking to determine the correct order.
55−
56−We group the different rules using `match`. The first argument for `match` is a
57−[Pattern]. The `OverloadedStrings` extension allows us to just write `String`s
58−here, which are interpreted as globs --- all files in the `images/` directory,
59−and all files in the `css/` directory.
60−
61−[Pattern]: /reference/Hakyll-Core-Identifier-Pattern.html
62−
63−Basic routes
64−------------
65−
66−The `route` function is used for determining the output file. For example, you
67−probably want to write the processed contents of `contact.markdown` to
68−`_site/contact.html` and not `_site/contact.markdown`.
69−
70−`idRoute` is a commonly used and just keeps the filename. We use this for e.g.
71−the images and CSS files.
72−
73−`setExtension` is another common route which takes a single argument: the
74−extension of the resulting file. In order to route `contact.markdown` to
75−`_site/contact.html`, use:
76−
77−```haskell
78−route $ setExtension "html"
79−```
80−
81−`customRoute` is a more advanced higher-order function which allows for even
82−more customization. You want to route `contact.markdown` to
83−`_site/nwodkram.tcatnoc`? No problem, just use:
84−
85−```haskell
86−customRoute $ reverse . toFilePath
87−```
88−
89−Basic compilers
90−---------------
91−
92−More information can be found in the [Routes] module.
93−
94−[Routes]: /reference/Hakyll-Core-Routes.html
95−
96−The `compile` function determines how the content is produced for a certain
97−item. `compile` takes a value of the type `Compiler (Item a)`. Let's look at
98−some common examples:
99−
100−- `copyFileCompiler` is self-explanatory, the output is exactly the same as the
101− input;
102−- `getResourceBody` just gets you the content as a `String`, so you can perform
103− other manipulations afterwards;
104−- `compressCssCompiler` performs some simple build-in compression
105− transformations for CSS;
106−- `pandocCompiler` reads markdown, reStructuredText, or another input format and
107− renders it as HTML (if you want to pass specific options to pandoc, use
108− `pandocCompilerWith`).
109−
110−Compilers are very flexible: `Compiler` is a [Monad] and `Item` is a [Functor].
111−
112−[Monad]: http://learnyouahaskell.com/a-fistful-of-monads
113−[Functor]: http://learnyouahaskell.com/functors-applicative-functors-and-monoids
114−
115−A good example to illustrate the `Monad` instance for `Compiler` is
116−
117−```haskell
118−relativizeUrls :: Item String -> Compiler (Item String)
119−```
120−
121−This compiler traverses your HTML and changes absolute URLs (e.g.
122−`/posts/foo.markdown` into relative ones: `../posts/foo.markdown`). This is
123−extremely useful if you want to deploy your site in a subdirectory (e.g.
124−`jaspervdj.be/hakyll` instead of `jaspervdj.be`). Combining this with the
125−`pandocCompiler` gives us:
126−
127−```haskell
128−pandocCompiler >>= relativizeUrls :: Compiler (Item String)
129−```
130−
131−For a real website, you probably also want to use templates in order to give
132−your pages produced by pandoc a nice layout. We tackle this in the next
133−tutorial.
44+ title: An image of a cow