hakyll-4.16.2.0: A static website compiler library

Safe Haskell | Safe-Inferred
Language | Haskell2010

Hakyll.Core.Rules

Contents

- Advanced usage

Description

This module provides a declarative Domain Specific Language (DSL) to generate a static site by specifying transformation `Rules` (although the use case is not limited to static sites). Each rule normally consists of three parts:

1. Source files (like Markdown files) to process (collected with e.g. `match` or `create`).
2. Compilation steps (like Markdown to HTML) to transform files' content to some output content (steps are collected within `Compiler` and executed with `compile`).
3. Routing to determine if and where an output content will be written out. For a static site this determines under which URL the output content will be available (configured with `route` and `Routes`).

A typical usage example looks as follows:

    -- write 'match "posts/**.md"' instead of 'match $ fromGlob "posts/**.md"'
    {-# LANGUAGE OverloadedStrings #-}
    ...

    main = hakyll $ do

        -- Rule 1
        -- Source files: all Markdown files like 'hakyll.md' in the 'posts' directory
        match "posts/**.md" $ do
            -- Routing: Only replace extension, so '<destination-directory>/posts/hakyll.html'.
            route $ setExtension "html"
            -- Compilation step(s): Transform Markdown file content into HTML output.
            compile pandocCompiler

        -- Rule 2
        match "css/*" $ do
            route idRoute
            compile compressCssCompiler
        ...

The order of rules doesn't matter.

See official Hakyll Rules tutorial for other examples.

Synopsis

- data Rules a
- match :: Pattern -> Rules () -> Rules ()
- matchMetadata :: Pattern -> (Metadata -> Bool) -> Rules () -> Rules ()
- create :: [Identifier] -> Rules () -> Rules ()
- version :: String -> Rules () -> Rules ()
- compile :: (Binary a, Typeable a, Writable a) => Compiler (Item a) -> Rules ()
- route :: Routes -> Rules ()
- preprocess :: IO a -> Rules a
- data Dependency
  - = PatternDependency Pattern (Set Identifier)
  - | IdentifierDependency Identifier
  - | AlwaysOutOfDate
- rulesExtraDependencies :: [Dependency] -> Rules a -> Rules a

# Documentation

data Rules a Source #

The monad used to compose rules

#### Instances

Instances details

MonadFail Rules Source # |
Instance details Defined in Hakyll.Core.Rules.Internal Methods fail :: String -> Rules a Source #
Applicative Rules Source # |
Instance details Defined in Hakyll.Core.Rules.Internal Methods pure :: a -> Rules a Source # (<*>) :: Rules (a -> b) -> Rules a -> Rules b Source # liftA2 :: (a -> b -> c) -> Rules a -> Rules b -> Rules c Source # (*>) :: Rules a -> Rules b -> Rules b Source # (<*) :: Rules a -> Rules b -> Rules a Source #
Functor Rules Source # |
Instance details Defined in Hakyll.Core.Rules.Internal Methods fmap :: (a -> b) -> Rules a -> Rules b Source # (<$) :: a -> Rules b -> Rules a Source #
Monad Rules Source # |
Instance details Defined in Hakyll.Core.Rules.Internal Methods (>>=) :: Rules a -> (a -> Rules b) -> Rules b Source # (>>) :: Rules a -> Rules b -> Rules b Source # return :: a -> Rules a Source #
MonadMetadata Rules Source # |
Instance details Defined in Hakyll.Core.Rules.Internal Methods getMetadata :: Identifier -> Rules Metadata Source # getMatches :: Pattern -> Rules [Identifier] Source # getAllMetadata :: Pattern -> Rules [(Identifier, Metadata)] Source #

match Source #

Arguments

:: Pattern | Glob pattern
-> Rules () | Remaining processing parts
-> Rules () | Result

Add a selection of which source files to process (using the given glob pattern) to the given remaining `Rules` value.

The expanded, relative path of the matched source file on disk (relative to the project directory configured with `providerDirectory`) becomes the identifier under which the compilation result is saved to the `Store` (in case you want to `load` it within another rule). See `Identifier` for details.

### Examples

Expand

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`.

matchMetadata Source #

Arguments

:: Pattern | Glob pattern
-> (Metadata -> Bool) | Metadata predicate
-> Rules () | Remaining processing parts
-> Rules () | Result

Add a selection of which source files to process (using the given glob pattern and metadata predicate) to the given remaining `Rules` values. Same as `match` but allows to filter files further based on their (metadata) content (a file is added only when the metadata predicate returns `True`).

The expanded, relative path of the matched source file on disk (relative to the project directory configured with `providerDirectory`) becomes the identifier under which the compilation result is saved to the `Store` (in case you want to `load` it within another rule). See `Identifier` for details.

### Examples

Expand

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 Source #

Arguments

:: [Identifier] | Identifiers to assign to created content in next argument
-> Rules () | Remaining processing parts that must create content
-> Rules () | Resulting rule

Assign (and thereby create) the given identifier(s) to content that has no underlying source file on disk. That content must be created within the `compile` part of the given remaining `Rules` value. The given identifier is the id under which the compilation is saved to the `Store` (in case you want to `load` it within another rule). See `Identifier` for details.

Use this function for example to create an overview page that doesn't have or need its content prepared in a file (unlike blog posts which normally have a corresponding Markdown source file on disk).

### Examples

Expand

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`.

version Source #

Arguments

:: String | Version name to add
-> Rules () | Remaining processing parts
-> Rules () | Result

Add the given version name to the implicit identifier(s) under which the compilation result of the given remaining `Rules` value is saved to the `Store`. See `Identifier` for details.

Use this wrapper function for example when you need to compile the same source file into two or more different results, each with a different version name. The version is needed to distinguish between these different compilation results in the store, otherwise they would get the same conflicting identifier in the store.

Warning: If you add a version name with this function, you need to supply the same name when you `load` the content from the store from within another rule.

### Examples

Expand

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 Source #

Arguments

:: (Binary a, Typeable a, Writable a) |
=> Compiler (Item a) | How to transform content
-> Rules () | Result

Add (or replace) the given compilation steps within the given `Compiler` value to the current `Rules` value. This functions controls HOW the content within a rule is processed (use one of the `match` functions to control WHAT content is processed).

The compilation result is saved to the `Store` under an implicit identifier. See `Identifier` for details.

If there's routing attached to the rule where this function is used, the compilation result is also written out to a file according to that route. See `route` and `Routes` for details.

### Examples

Expand

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.

route Source #

Arguments

:: Routes | Where to output compilation results
-> Rules () | Result

Add (or replace) routing in the current `Rules` value. This functions controls IF and WHERE the compiled results are written out (use one of the `match` functions to control WHAT content is processed and `compile` to control HOW). See `Routes` and `Identifier` for details on how output filepaths are computed.

Hint: If there's no route attached to a rule, the compilation result is not written out. However, the compilation result is saved to the `Store` and can be loaded and used within another rule. This behavior is needed, for example, for templates.

### Examples

Expand

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.

# Advanced usage

preprocess :: IO a -> Rules a Source #

Execute an `IO` action immediately while the rules are being evaluated. This should be avoided if possible, but occasionally comes in useful.

data Dependency Source #

Constructors

PatternDependency Pattern (Set Identifier) |
IdentifierDependency Identifier |
AlwaysOutOfDate |

#### Instances

Instances details

Show Dependency Source # |
Instance details Defined in Hakyll.Core.Dependencies Methods showsPrec :: Int -> Dependency -> ShowS Source # show :: Dependency -> String Source # showList :: [Dependency] -> ShowS Source #
Binary Dependency Source # |
Instance details Defined in Hakyll.Core.Dependencies Methods put :: Dependency -> Put Source # get :: Get Dependency Source # putList :: [Dependency] -> Put Source #

rulesExtraDependencies :: [Dependency] -> Rules a -> Rules a Source #

Advanced usage: add extra dependencies to compilers. Basically this is needed when you're doing unsafe tricky stuff in the rules monad, but you still want correct builds.

A useful utility for this purpose is `makePatternDependency`.