4.5 KiB
title | author |
---|---|
A Guide to the Hakyll Module Zoo | Brent Yorgey |
The hakyll package contains a bewildering array of modules, and it's hard to know where to look when you are just getting started---especially since many of them are only used by hakyll internally and not that useful to website authors. This guide provides a quick reference to the contents of the most important and useful modules.
Core modules
These are the modules containing the fundamental tools and concepts you need to get started building a site with hakyll.
-
This is one of the modules you should look at first. It defines the fundamental
Compiler
type and has a bunch of documentation explaining how to useCompiler
s and theirArrow
-based interface.It also defines many primitive
Compiler
s as well as several variants onrequire
, which allow you to bring together multiple resources to create a single output. -
Specify where compiled items should go in the output site.
-
Specify which compilers and routes should be used on which resources.
Also has combinators for grouping (necessary if you want to use the same resources for multiple purposes), creating outputs that are not based on any resources, and even dynamically generating compilers.
-
Hakyll.Core.Identifier.Pattern
Combinators for creating patterns, i.e. predicates that pick out a set of resources: filesystem globs, arbitrary predicates, explicit lists, regular expressions, and so on.
-
A
Page
, consisting of some metadata and a body, is one of the most fundamental structures used by hakyll. This module has some documentation explaining how pages work, and defines a number of compilers and utilities for working with them. -
Utilities for manipulating page metadata.
-
Templates specify how to take the content of a
Page
and turn it into HTML output. -
The main
hakyll
function that runs the whole show. There is also ahakyllWith
function which allows for a custom configuration.
Pre-packaged solutions
These modules contain some "pre-packaged" solutions for common situations. They can be used as-is, or their source can be used as inspiration for your own tools.
-
Combine several pages into a list, such as a list of posts, images in a gallery, etc.
-
Create RSS feeds.
-
Work with tags and categories.
Useful utilities
-
Use any unix utility as a compiler.
-
A few utilities for working with arrows, including a constant arrow, unit arrow, and running an entire list of arrows on a single input.
-
Utility functions for working with the file system.
-
A few utility functions for working with
String
s (trim spaces, find and replace, split on regexp). -
Hakyll.Core.Writable.WritableTuple
A utility type covering the situation where you generate some data, some of which you want to write to disk, and some of which you don't want to write but will be needed in order to generate something else later.
Advanced customization
-
The
Writable
class is for resources which can be written to disk as part of the output site. You can specify how to write your own custom types to disk by giving them aWritable
instance. -
Some compilers for running pandoc. Normally they are run automatically as part of, for example,
pageCompiler
; but sometimes it is useful to be able to run pandoc explicitly.