Create a small blog using hakyll-contrib
Published on June 22, 2011 under the tag haskell
One of my side projects is Hakyll, a static site generator written in Haskell. Altough the name is a play on Jekyll, Hakyll bears more resemblance to nanoc.
The resemblance is there because nanoc’s author Denis is a good friend of mine, who also lives close to me, and we’ve had a number of interesting discussions on static site generators.
Both nanoc and Hakyll offer a lot of flexibility, behaving more like a web publishing API/library than a simple tool. This brings me to (in my opinion) the key feature of Jekyll: it is simple. You can get started with a website by not much more than simply throwing a bunch of text files in a directory and running the tool.
Today, I’ve released a package hakyll-contrib which allows just that. The rest of this blogpost is a tutorial, which is also included in the Haddock documentation.
The idea is that you don’t have to write your configuration yourself: you just follow some conventions, and Hakyll does the rest. Start by installing the tool:
cabal install hakyll-contrib
You can generate a site which will serve as a good starting point by running the command-line tool:
small-blog is the template used – I might add more templates later. Hakyll
will generate a simple example site for you. The necessary configuration is
placed in the
small-blog.hs file. Compile and run it to create the demo site:
ghc --make small-blog.hs ./small-blog build ./small-blog preview
Then, visit the site in your browser.
Images should be placed in the
img/ folder. The are copied
directly. Other static files (but not images) can be placed in
favicon.ico file is an exception, it is just placed in the
CSS files should be placed in
Then, we arrive at pages. You can create any number of pages on your site: just
create files in one of the documents pandoc supports (
.lhs…) in the top-level directory.
These pages may use a number of preconfigured
$recentPosts$: A list of recent posts, displayed from most recent to oldest. By default, 3 posts are shown, altough this can be configured using the ‘numberOfRecentPosts’ field.
$allPosts$: A list of all posts, displayed from most recent to oldest. This is very useful for creating an archive page.
$chronologicalPosts$: Similar to
$allPosts$, but displays the posts in chronological order.
For example usage, look at the example site we generated using
Now, one can wonder where these posts come from. Simple: all pages in the
posts/ directory are considered posts. Note that a naming format of
is mandatory. An example:
This allows Hakyll to parse the date easily, among other things. Again, look at the example site for some example posts.
Additionaly, there is the
templates/ folder. This folder holds the
templates for your site. For a
small-blog configuration, your site should
have exactly three templates:
templates/default.html: The main template. This should contain your HTML doctype, head, etc.
templates/post.html: A template which is applied to every post before it is rendered using the default template.
templates/post-item.html: A template which is applied to posts in listings (e.g.
Again, the example should clarify things.
This configuration should be enough to create a small personal website. But, we have only touched the surface of what is possible with Hakyll. For more information, check out the tutorials.