[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.yml
in the repo. The first step runscabal 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. -
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 runsmake deploy
which in turn creates a git repo under the generated directory, commits and pushes to the same repo'smaster
branch. -
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.
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 thesource
branch (notmaster
). -
Add
Makefile
andcircle.yml
from 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
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
.