git.iko.soy/hakyll
on master help sign in
Add tutorial on versions
34e6ad4Jasper Van der Jeugt
web/tutorials/06-versions.markdownnew file+67
compare with master
unifiedsplit
@@ -0,0 +1,67 @@
1+---
2+title: Producing multiple versions of a single file
3+author: Jasper Van der Jeugt
4+---
5+
6+Basics
7+------
8+
9+Suppose that you want to make your writings available in raw markdown format, in
10+addition to the HTML available on your website. Is this possible using Hakyll?
11+
12+In the [previous tutorial], we explained how you can use snapshots to store an
13+item while it's being processed. However, this does not allow you to route it to
14+a different location.
15+
16+[previous tutorial]: /tutorials/05-snapshots-feeds.html
17+
18+Instead, we must use `version` in order to do this. The type signature of
19+`version` does not reveal much:
20+
21+```haskell
22+version :: String -> Rules () -> Rules ()
23+```
24+
25+So let's look at an example:
26+
27+```haskell
28+match "posts/*" $ do
29+ route $ setExtension "html"
30+ compile $ pandocCompiler
31+ >>= loadAndApplyTemplate "templates/post.html" postCtx
32+ >>= loadAndApplyTemplate "templates/default.html" postCtx
33+ >>= relativizeUrls
34+
35+match "posts/*" $ version "raw" $ do
36+ route idRoute
37+ compile getResourceBody
38+```
39+
40+Here, you can see how we produce two versions of each item in `posts/*`: one
41+`"raw"` version, and the default version.
42+
43+Attention: patterns and versions
44+--------------------------------
45+
46+However, there is one important thing to note: suppose you use `Pattern`s for a
47+function such as `loadAll`, e.g. to create an index page with all blogposts.
48+
49+```haskell
50+loadAll "posts/*" :: Compiler [Item String]
51+```
52+
53+is valid code, but **probably not** what you want to do: this will select all
54+`posts/*` items, meaning, both your HTML posts, and the raw versions. In order
55+to fix this, use any of the following:
56+
57+```haskell
58+loadAll (noVersion "posts/*") :: Compiler [Item String]
59+```
60+
61+for the default versions, i.e. the HTML pages, and:
62+
63+```haskell
64+loadAll ("posts/*" `withVersion` "raw") :: Compiler [Item String]
65+```
66+
67+for the raw versions.