Select all markdown files within a directory (but without subdirectories)

-- Match all Markdown files in the immediate 'posts' directory
-- e.g. '<project-directory>/posts/hakyll.md'
-- but NOT  '<project-directory>/posts/haskell/monad.md'
match "posts/*.md" $ do
    route $ setExtension "html"
    compile pandocCompiler

Select all markdown files within a directory (including subdirectories recursively)

-- Match all Markdown files in the 'posts' directory and any subdirectory
-- e.g. '<project-directory>/posts/hakyll.md'
-- and  '<project-directory>/posts/haskell/monad.md'
match "posts/**.md" $ do
    route $ setExtension "html"
    compile pandocCompiler

See Pattern or search "glob patterns" online for more details. To control where the compilation result will be written out, use routing functions like setExtension.

Select all markdown files with enabled draft flag within a directory

matchMetadata "posts/*.md" (\meta -> maybe False (=="true") $ lookupString "draft" meta) $ do
    route $ setExtension "html"
    compile pandocCompiler

For example, the following 'posts/hakyll.md' file with draft: true metadata would match:

---
draft: true
title: Hakyll Post
...
---
In this blog post we learn about Hakyll ...

Note that files that have draft: false or no such draft field at all, would not match. You can use helper functions like lookupString to access a specific metadata field, and maybe to work with Maybe. To control where the compilation result will be written out, use routing functions like setExtension.

Create a webpage without an underlying source file

-- saved with implicit identifier 'index.html' to Store
create ["index.html"] $ do

    -- compilation result is written to '<destination-directory>/index.html'
    route idRoute

    -- create content without a source file from disk
    compile $ makeItem ("<h1>Hello World</h1>" :: String)

Note how you can use makeItem to create content inline (to be processed as a Compiler value) as if that content was loaded from a file (as it's the case when using match). To control where the compilation result will be written out, use routing functions like idRoute.

Compile source file into differently versioned outputs and load both

-- e.g. file on disk: 'posts/hakyll.md'

-- saved with implicit identifier ('posts/hakyll.md', no-version)
match "posts/*" $ do
    route $ setExtension "html"
    compile pandocCompiler

-- saved with implicit identifier ('posts/hakyll.md', version 'raw')
match "posts/*" $ version "raw" $ do
    route idRoute
    compile getResourceBody

-- use compilation results from rules above
create ["index.html"] $ do
    route idRoute
    compile $ do
        -- load no-version version
        compiledPost <- load (fromFilePath "posts/hakyll.md")
        -- load version 'raw'
        rawPost <- load . setVersion (Just "raw") $ fromFilePath "posts/hakyll.md"
        ...

Note how a version name is needed to distinguish the unversioned and the "raw" version when loading the Hakyll post for the index.html page. To control where the compilation result will be written out, use routing functions like idRoute and setExtension.

Compile Markdown to HTML

-- Select all Markdown files in 'posts' directory
match "posts/**.md" $ do

    route $ setExtension "html"

    -- use pandoc to transform Markdown to HTML in a single step
    compile pandocCompiler

Note how we set the content to be processed with pandocCompiler. The content comes implicitly from the matched Markdown files on disk. We don't have to pass that content around manually. Every file is processed the same way within this one rule.

To control where the compilation result will be written out, use routing functions like setExtension. Here the compilation result of a file like posts/hakyll.md is written out to posts/hakyll.html.

Compile Markdown to HTML and embed it in a template

-- Select all Markdown files in 'posts' directory
match "posts/**.md" $ do
    route $ setExtension "html"
    compile $
        pandocCompiler >>=
          loadAndApplyTemplate "templates/post.html" defaultContext

-- To Hakyll templates are just plain files that have to be processed
-- and placed into the store like any other file (but without routing).
-- e.g. file on disk: 'templates/post.html'
match "templates/*" $ compile templateBodyCompiler

Note how a Markdown post that is compiled to HTML using pandocCompiler in a first step and then embedded into a HTMl Template in a second step by using loadAndApplyTemplate. We can use templates to control the design and layout of a webpage. A template may look as follows:

<h1>$title$</h1>
$body$

See Hakyll.Web.Template to see examples of the templating syntax.

Rules with and without routing

-- e.g. file on disk: 'templates/post.html'

-- Rule 1 (without routing)
match "templates/*" $ do
    -- compilation result saved to store with implicit identifier, e.g. 'templates/post.html'
    compile templateCompiler

-- Rule 2 (with routing)
match "posts/**.md" $ do
    route $ setExtension "html"
    compile $ do
       -- load compiled result of other rule with explicit identifier.
       postTemplate <- loadBody "templates/post.html"
       pandocCompiler >>= applyTemplate postTemplate defaultContext

Note that we don't set a route in the first rule to avoid writing out our compiled templates. However, we can still load (or loadBody) the compiled templates to apply them in a second rule. The content for templateCompiler comes implicitly from the matched template files on disk. We don't have to pass that content around manually. See match and compile for details.

To control where a compilation result will be written out (as done in the second rule), use routing functions like setExtension.

See Hakyll.Web.Template for examples of templates and the templating syntax.