Fork me on GitHub

Tutorial: Producing multiple versions of a single file

Basics

Suppose that you want to make your writings available in raw markdown format, in addition to the HTML available on your website. Is this possible using Hakyll?

In the previous tutorial, we explained how you can use snapshots to store an item while it’s being processed. However, this does not allow you to route it to a different location.

Instead, we must use version in order to do this. The type signature of version does not reveal much:

version :: String -> Rules () -> Rules ()

So let’s look at an example:

match "posts/*" $ do
    route $ setExtension "html"
    compile $ pandocCompiler
        >>= loadAndApplyTemplate "templates/post.html"    postCtx
        >>= loadAndApplyTemplate "templates/default.html" postCtx
        >>= relativizeUrls

match "posts/*" $ version "raw" $ do
    route   idRoute
    compile getResourceBody

Here, you can see how we produce two versions of each item in posts/*: one "raw" version, and the default version.

Attention: patterns and versions

However, there is one important thing to note: suppose you use Patterns for a function such as loadAll, e.g. to create an index page with all blogposts.

loadAll "posts/*" :: Compiler [Item String]

is valid code, but probably not what you want to do: this will select all posts/* items, meaning, both your HTML posts, and the raw versions. In order to fix this, use any of the following:

loadAll ("posts/*" .&&. hasNoVersion) :: Compiler [Item String]

for the default versions, i.e. the HTML pages, and:

loadAll ("posts/*" .&&. hasVersion "raw") :: Compiler [Item String]

for the raw versions.

Other tutorials

Find links to other tutorials.

Documentation inaccurate or out-of-date? Found a typo?

Hakyll is an open source project, and one of the hardest parts is writing correct, up-to-date, and understandable documentation. Therefore, the authors would really appreciate it if you would give feedback about the tutorials, and especially report errors or difficulties you encountered. If you have a github account, you can use the issue system. Thanks! If you run into any problems, all questions are welcome in the above google group, or you could try the IRC channel, #hakyll on irc.libera.chat (we do not have a channel on Freenode anymore).