Better tutorial structure

5 files changed, 138 insertions, 105 deletions

diff --git a/web/tutorials/02-basics.markdown b/web/tutorials/02-basics.markdown
index 46d85a6..77bbefc 100644
--- a/web/tutorials/02-basics.markdown
+++ b/web/tutorials/02-basics.markdown
@@ -19,115 +19,26 @@ directories:
 In general, it's only necessary to use `rebuild` when you made changes to your
 `site.hs`, and not when you just made changes to the contents of your website.
 
-Basic rules
------------
+At this point, feel free to change some files, `./site build` and see what
+happens!
 
-Let's take a look at the `site.hs` file.
+Pages and metadata
+------------------
 
-```haskell
-main :: IO ()
-main = hakyll $ do
-    ...
-```
+You might've noticed that the markdown pages all start with a block:
 
-Hakyll configurations are in the `Rules` monad. In order to run them, the
-`hakyll` function is used, so your main function usually starts this way.
-`hakyllWith` is also available, this function allows you specify a custom
-[Configuration].
+    ---
+    title: Contact
+    ---
 
-[Configuration]: /reference/Hakyll-Core-Configuration.html
+    I live...
 
-Some actual rules look like this:
+This is entirely optional, but useful for providing extra information
+("metadata") about items. All items can have metadata: since it's not really
+convenient to add such a header to an image, you can also do this using a
+separate file.
 
-```haskell
-match "images/*" $ do
-    route   idRoute
-    compile copyFileCompiler
+For a file called `images/foo.png`, you can add an `images/foo.png.metadata`
+file with contents:
 
-match "css/*" $ do
-    route   idRoute
-    compile compressCssCompiler
-
-```
-
-This is a declarative DSL: the order in which you write the rules make little
-difference: Hakyll will use dependency tracking to determine the correct order.
-
-We group the different rules using `match`. The first argument for `match` is a
-[Pattern]. The `OverloadedStrings` extension allows us to just write `String`s
-here, which are interpreted as globs --- all files in the `images/` directory,
-and all files in the `css/` directory.
-
-[Pattern]: /reference/Hakyll-Core-Identifier-Pattern.html
-
-Basic routes
-------------
-
-The `route` function is used for determining the output file. For example, you
-probably want to write the processed contents of `contact.markdown` to
-`_site/contact.html` and not `_site/contact.markdown`.
-
-`idRoute` is a commonly used and just keeps the filename. We use this for e.g.
-the images and CSS files.
-
-`setExtension` is another common route which takes a single argument: the
-extension of the resulting file. In order to route `contact.markdown` to
-`_site/contact.html`, use:
-
-```haskell
-route $ setExtension "html"
-```
-
-`customRoute` is a more advanced higher-order function which allows for even
-more customization. You want to route `contact.markdown` to
-`_site/nwodkram.tcatnoc`? No problem, just use:
-
-```haskell
-customRoute $ reverse . toFilePath
-```
-
-Basic compilers
----------------
-
-More information can be found in the [Routes] module.
-
-[Routes]: /reference/Hakyll-Core-Routes.html
-
-The `compile` function determines how the content is produced for a certain
-item. `compile` takes a value of the type `Compiler (Item a)`. Let's look at
-some common examples:
-
-- `copyFileCompiler` is self-explanatory, the output is exactly the same as the
-  input;
-- `getResourceBody` just gets you the content as a `String`, so you can perform
-  other manipulations afterwards;
-- `compressCssCompiler` performs some simple build-in compression
-  transformations for CSS;
-- `pandocCompiler` reads markdown, reStructuredText, or another input format and
-  renders it as HTML (if you want to pass specific options to pandoc, use
-  `pandocCompilerWith`).
-
-Compilers are very flexible: `Compiler` is a [Monad] and `Item` is a [Functor].
-
-[Monad]: http://learnyouahaskell.com/a-fistful-of-monads
-[Functor]: http://learnyouahaskell.com/functors-applicative-functors-and-monoids
-
-A good example to illustrate the `Monad` instance for `Compiler` is
-
-```haskell
-relativizeUrls :: Item String -> Compiler (Item String)
-```
-
-This compiler traverses your HTML and changes absolute URLs (e.g.
-`/posts/foo.markdown` into relative ones: `../posts/foo.markdown`). This is
-extremely useful if you want to deploy your site in a subdirectory (e.g.
-`jaspervdj.be/hakyll` instead of `jaspervdj.be`). Combining this with the
-`pandocCompiler` gives us:
-
-```haskell
-pandocCompiler >>= relativizeUrls :: Compiler (Item String)
-```
-
-For a real website, you probably also want to use templates in order to give
-your pages produced by pandoc a nice layout. We tackle this in the next
-tutorial.
+    title: An image of a cow
diff --git a/web/tutorials/03-rules-routes-compilers.markdown b/web/tutorials/03-rules-routes-compilers.markdown
new file mode 100644
index 0000000..b3bf4ee
--- /dev/null
+++ b/web/tutorials/03-rules-routes-compilers.markdown
@@ -0,0 +1,117 @@
+---
+title: Rules, routes and compilers
+author: Jasper Van der Jeugt
+---
+
+Basic rules
+-----------
+
+While changing the content is nice, you'll have time for that once your site is
+configured. Configuration is done using the `site.hs` file: let's take a look at
+it!
+
+```haskell
+main :: IO ()
+main = hakyll $ do
+    ...
+```
+
+Hakyll configurations are in the `Rules` monad. In order to run them, the
+`hakyll` function is used, so your main function usually starts this way.
+`hakyllWith` is also available, this function allows you specify a custom
+[Configuration].
+
+[Configuration]: /reference/Hakyll-Core-Configuration.html
+
+Some actual rules look like this:
+
+```haskell
+match "images/*" $ do
+    route   idRoute
+    compile copyFileCompiler
+
+match "css/*" $ do
+    route   idRoute
+    compile compressCssCompiler
+
+```
+
+This is a declarative DSL: the order in which you write the rules make little
+difference: Hakyll will use dependency tracking to determine the correct order.
+
+We group the different rules using `match`. The first argument for `match` is a
+[Pattern]. The `OverloadedStrings` extension allows us to just write `String`s
+here, which are interpreted as globs --- all files in the `images/` directory,
+and all files in the `css/` directory.
+
+[Pattern]: /reference/Hakyll-Core-Identifier-Pattern.html
+
+Basic routes
+------------
+
+The `route` function is used for determining the output file. For example, you
+probably want to write the processed contents of `contact.markdown` to
+`_site/contact.html` and not `_site/contact.markdown`.
+
+`idRoute` is a commonly used and just keeps the filename. We use this for e.g.
+the images and CSS files.
+
+`setExtension` is another common route which takes a single argument: the
+extension of the resulting file. In order to route `contact.markdown` to
+`_site/contact.html`, use:
+
+```haskell
+route $ setExtension "html"
+```
+
+`customRoute` is a more advanced higher-order function which allows for even
+more customization. You want to route `contact.markdown` to
+`_site/nwodkram.tcatnoc`? No problem, just use:
+
+```haskell
+route $ customRoute $ reverse . toFilePath
+```
+
+More information can be found in the [Routes] module.
+
+[Routes]: /reference/Hakyll-Core-Routes.html
+
+Basic compilers
+---------------
+
+The `compile` function determines how the content is produced for a certain
+item. `compile` takes a value of the type `Compiler (Item a)`. Let's look at
+some common examples:
+
+- `copyFileCompiler` is self-explanatory, the output is exactly the same as the
+  input;
+- `compressCssCompiler` performs some simple build-in compression
+  transformations for CSS;
+- `pandocCompiler` reads markdown, reStructuredText, or another input format and
+  renders it as HTML (if you want to pass specific options to pandoc, use
+  `pandocCompilerWith`).
+
+Compilers are very flexible: `Compiler` is a [Monad] and `Item` is a [Functor].
+
+[Monad]: http://learnyouahaskell.com/a-fistful-of-monads
+[Functor]: http://learnyouahaskell.com/functors-applicative-functors-and-monoids
+
+A good example to illustrate the `Monad` instance for `Compiler` is
+
+```haskell
+relativizeUrls :: Item String -> Compiler (Item String)
+```
+
+This compiler traverses your HTML and changes absolute URLs (e.g.
+`/posts/foo.markdown` into relative ones: `../posts/foo.markdown`). This is
+extremely useful if you want to deploy your site in a subdirectory (e.g.
+`jaspervdj.be/hakyll` instead of `jaspervdj.be`). Combining this with the
+`pandocCompiler` gives us:
+
+```haskell
+pandocCompiler >>= relativizeUrls :: Compiler (Item String)
+```
+
+For a real website, you probably also want to use templates in order to give
+your pages produced by pandoc a nice layout. We tackle this in the next
+tutorial.
diff --git a/web/tutorials/03-compilers.markdown b/web/tutorials/04-compilers.markdown
index 953464f..a344c6e 100644
--- a/web/tutorials/03-compilers.markdown
+++ b/web/tutorials/04-compilers.markdown
@@ -31,3 +31,8 @@ Sometimes you just want the *contents* and not the `Item`:
 ```haskell
 loadBody "posts/foo.markdown" :: Compiler String
 ```
+
+This is all useful if we want to use Hakyll's templating system.
+
+Basic templates
+---------------
diff --git a/web/tutorials/04-arrows.markdown b/web/tutorials/05-arrows.markdown
index 3f2e244..3f2e244 100644
--- a/web/tutorials/04-arrows.markdown
+++ b/web/tutorials/05-arrows.markdown
diff --git a/web/tutorials/05-guide.markdown b/web/tutorials/06-guide.markdown
index e8c5800..e8c5800 100644
--- a/web/tutorials/05-guide.markdown
+++ b/web/tutorials/06-guide.markdown