@@ -0,0 +1,129 @@
1+---
2+title: A Guide to the Hakyll Module Zoo
3+author: Brent Yorgey
4+---
5+
6+The hakyll package [contains a bewildering array](/reference/) of
7+modules, and it's hard to know where to look when you are just getting
8+started---especially since many of them are only used by hakyll
9+internally and not that useful to website authors. This guide
10+provides a quick reference to the contents of the most important and
11+useful modules.
12+
13+## Core modules
14+
15+These are the modules containing the fundamental tools and concepts
16+you need to get started building a site with hakyll.
17+
18+* [Hakyll.Core.Compiler](/reference/Hakyll-Core-Compiler.html)
19+
20+ This is one of the modules you should look at first. It defines the
21+ fundamental `Compiler` type and has a bunch of documentation explaining how to
22+ use `Compiler`s and their `Arrow`-based interface.
23+
24+ It also defines many primitive `Compiler`s as well as several
25+ variants on `require`, which allow you to bring together multiple
26+ resources to create a single output.
27+
28+* [Hakyll.Core.Routes](/reference/Hakyll-Core-Routes.html)
29+
30+ Specify where compiled items should go in the output site.
31+
32+* [Hakyll.Core.Rules](/reference/Hakyll-Core-Rules.html)
33+
34+ Specify which compilers and routes should be used on which
35+ resources.
36+
37+ Also has combinators for grouping (necessary if you want to use
38+ the same resources for multiple purposes), creating outputs that
39+ are not based on any resources, and even dynamically generating
40+ compilers.
41+
42+* [Hakyll.Core.Identifier.Pattern](/reference/Hakyll-Core-Identifier-Pattern.html)
43+
44+ Combinators for creating *patterns*, i.e. predicates that pick out
45+ a set of resources: filesystem globs, arbitrary predicates,
46+ explicit lists, regular expressions, and so on.
47+
48+* [Hakyll.Web.Page](/reference/Hakyll-Web-Page.html)
49+
50+ A `Page`, consisting of some metadata and a body, is one of the
51+ most fundamental structures used by hakyll. This module has some
52+ documentation explaining how pages work, and defines a number of
53+ compilers and utilities for working with them.
54+
55+* [Hakyll.Web.Page.Metadata](/reference/Hakyll-Web-Page-Metadata.html)
56+
57+ Utilities for manipulating page metadata.
58+
59+* [Hakyll.Web.Template](/reference/Hakyll-Web-Template.html)
60+
61+ Templates specify how to take the content of a `Page` and turn
62+ it into HTML output.
63+
64+* [Hakyll.Main](/reference/Hakyll-Main.html)
65+
66+ The main `hakyll` function that runs the whole show. There is
67+ also a `hakyllWith` function which allows for a custom
68+ configuration.
69+
70+## Pre-packaged solutions
71+
72+These modules contain some "pre-packaged" solutions for common
73+situations. They can be used as-is, or their source can be used as
74+inspiration for your own tools.
75+
76+* [Hakyll.Web.Page.List](/reference/Hakyll-Web-Page-List.html)
77+
78+ Combine several pages into a list, such as a list of posts, images
79+ in a gallery, etc.
80+
81+* [Hakyll.Web.Feed](/reference/Hakyll-Web-Feed.html)
82+
83+ Create RSS feeds.
84+
85+* [Hakyll.Web.Tags](/reference/Hakyll-Web-Tags.html)
86+
87+ Work with tags and categories.
88+
89+## Useful utilities
90+
91+* [Hakyll.Core.UnixFilter](/reference/Hakyll-Core-UnixFilter.html)
92+
93+ Use any unix utility as a compiler.
94+
95+* [Hakyll.Core.Util.Arrow](/reference/Hakyll-Core-Util-Arrow.html)
96+
97+ A few utilities for working with arrows, including a constant
98+ arrow, unit arrow, and running an entire list of arrows on a
99+ single input.
100+
101+* [Hakyll.Core.Util.File](/reference/Hakyll-Core-Util-File.html)
102+
103+ Utility functions for working with the file system.
104+
105+* [Hakyll.Core.Util.String](/reference/Hakyll-Core-Util-String.html)
106+
107+ A few utility functions for working with `String`s (trim spaces,
108+ find and replace, split on regexp).
109+
110+* [Hakyll.Core.Writable.WritableTuple](/reference/Hakyll-Core-Writable-WritableTuple.html)
111+
112+ A utility type covering the situation where you generate some
113+ data, some of which you want to write to disk, and some of which
114+ you don't want to write but will be needed in order to generate
115+ something else later.
116+
117+## Advanced customization
118+
119+* [Hakyll.Core.Writable](/reference/Hakyll-Core-Writable.html)
120+
121+ The `Writable` class is for resources which can be written to disk
122+ as part of the output site. You can specify how to write your own
123+ custom types to disk by giving them a `Writable` instance.
124+
125+* [Hakyll.Web.Pandoc](/reference/Hakyll-Web-Pandoc.html)
126+
127+ Some compilers for running pandoc. Normally they are run
128+ automatically as part of, for example, `pageCompiler`; but
129+ sometimes it is useful to be able to run pandoc explicitly.