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.
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.ymlin the repo. The first step runs
cabal installwhich 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.
The "test" step of Circle is what runs hakyll to generate the static pages.
Once the static pages are generated, Circle runs the deploy hook specified in
circle.yml. In our case, this runs
make deploywhich in turn creates a git repo under the generated directory, commits and pushes to the same repo's
GitHub Pages monitors pushes to the
masterbranch of the
<yourname>.github.iorepo 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.
Create a GitHub repo named
<yourname>.github.io, and push your Hakyll source tree to the
circle.ymlfrom my repo to your source tree, and modify the first two lines of the Makefile to point to your repo and site.
Sign-up for a CircleCI account, and add your repo to it.
Wait for CircleCI to build your site and push the generated files to the
masterbranch 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