@@ -19,115 +19,26 @@ directories:
19In general, it's only necessary to use `rebuild` when you made changes to your
19In general, it's only necessary to use `rebuild` when you made changes to your
20`site.hs`, and not when you just made changes to the contents of your website.
20`site.hs`, and not when you just made changes to the contents of your website.
22−Basic rules
22+At this point, feel free to change some files, `./site build` and see what
23−-----------
23+happens!
25−Let's take a look at the `site.hs` file.
25+Pages and metadata
27−```haskell
28+You might've noticed that the markdown pages all start with a block:
33−Hakyll configurations are in the `Rules` monad. In order to run them, the
30+ ---
34−`hakyll` function is used, so your main function usually starts this way.
31+ title: Contact
35−`hakyllWith` is also available, this function allows you specify a custom
32+ ---
38−[Configuration]: /reference/Hakyll-Core-Configuration.html
34+ I live...
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
42−```haskell
41+For a file called `images/foo.png`, you can add an `images/foo.png.metadata`
43−match "images/*" $ do
42+file with contents:
45− compile copyFileCompiler
47−match "css/*" $ do
44+ title: An image of a cow
49− compile compressCssCompiler
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.
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.
61−[Pattern]: /reference/Hakyll-Core-Identifier-Pattern.html
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`.
70−`idRoute` is a commonly used and just keeps the filename. We use this for e.g.
71−the images and CSS files.
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:
78−route $ setExtension "html"
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:
86−customRoute $ reverse . toFilePath
92−More information can be found in the [Routes] module.
94−[Routes]: /reference/Hakyll-Core-Routes.html
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
100−- `copyFileCompiler` is self-explanatory, the output is exactly the same as the
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`).
110−Compilers are very flexible: `Compiler` is a [Monad] and `Item` is a [Functor].
112−[Monad]: http://learnyouahaskell.com/a-fistful-of-monads
113−[Functor]: http://learnyouahaskell.com/functors-applicative-functors-and-monoids
115−A good example to illustrate the `Monad` instance for `Compiler` is
118−relativizeUrls :: Item String -> Compiler (Item String)
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:
128−pandocCompiler >>= relativizeUrls :: Compiler (Item String)
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