hakyll.md

Using Hakyll with CircleCi and GitHub Pages

[Posted April 24, 2015; restored here for reference]

Today I switched this site from Jekyll to Hakyll, a Haskell library for generating static sites. It is still hosted in GitHub Pages, which only supports Jekyll. Therefore I had to find a Continuous Delivery service (CD) that will perform and connect the "missing piece," the stage that generates the HTML pages — in between a git push and pushing to GitHub pages. Here is how I did it.

The architecture

1. For CD, we use CircleCI which hooks into the GitHub repo and monitors for any pushes. When a commit or more is pushed it will start the build per the configuration defined in cirle.yml in the repo. The first step runs cabal install which installs the Hakyll dependencies (including pandoc). This step takes a while — and the CircleCI UI provides excellent feedback on the whole process — but the good news is that Circle will cache the assets and re-use them the next time.

2. The "test" step of Circle is what runs hakyll to generate the static pages.

3. Once the static pages are generated, Circle runs the deploy hook specified in circle.yml. In our case, this runs make deploy which in turn creates a git repo under the generated directory, commits and pushes to the same repo's master branch.

4. GitHub Pages monitors pushes to the master branch of the <yourname>.github.io repo and updates the final hosted version.

With this setup, I can just use the GitHub web interface to manage the blog (adding posts, editing posts, etc.), and everything else will automatically be taken care of. There is little noticeable delay as both Hakyll and CircleCI are efficient at what they do.

Doing this for your own site

If you are interested in adopting this approach for your own Hakyll powered site, follow the below steps. Just note that there are some minor limitations with this setup compared to using Jekyll.

1. Create a GitHub repo named <yourname>.github.io, and push your Hakyll source tree to the source branch (not master).

2. Add Makefile and circle.yml from my repo to your source tree, and modify the first two lines of the Makefile to point to your repo and site.

3. Sign-up for a CircleCI account, and add your repo to it.

4. Wait for CircleCI to build your site and push the generated files to the master branch of the same repo. The first run will take a while – about 15 minutes – while CircleCI runs cabal to fetch and cache the huge list of dependencies.

Your site will now be running at the CNAME specified in the Makefile.