This Yak's Name is Hakyll

I originally created this website using Emacs html-helper-mode, and then later, for blogging purposes, switched to a setup that uses Emacs Org-mode and Jekyll.

(Remember “blogging”, kids? It is something we old people used to do in the Internet about fifteen years before from now.)

The Org-mode + Jekyll setup worked like this: you write the site files and blog posts as Org-mode files, and then “publish” the “project” to kind of headless HTML files, which are then processed by Jekyll into the shape of a website with blog posts. This process is described in detail in Org-mode website, in the article “Using org to Blog with Jekyll”. It was fun and novel at the time. Fun and novel for me, anyway.

While Jekyll is nice, and I quite like writing prose in my favorite text editor and kitchen sink, the process of writing in this manner has been far from friction-free.

For example, while writing, I would often run ‘org-publish-project’ or ‘org-publish-current-file’ command from Emacs, in order to preview what stuff I just wrote looks like in HTML. This would send the cursor back to the top of the buffer, breaking my “flow”. Aaargh!

The tedium of that possibly kept me from writing here more often. I have other lame excuses too, but I think I can reasonably claim that this one has been the main one. Thus I have been contemplating moving away from Jekyll, while keeping Org-mode.

I tried using jekyll-org, but it wasn’t really much of an improvement.

I tinkered with Hugo for a bit. Hugo seemed nice: it is fast, popular, and has some useful niceties (such as image re-sizing) that could have been useful. Hugo can also handle Org-mode input!

But it turned out that Hugo’s Org-mode handling is not quite complete: it can’t handle embedded images or tables, for example.

So I gave up, and gave Hakyll a good look again.

I have not written Haskell earnestly in a while now. Even then, with a bit of effort and a lot of fun, I could migrate things from Jekyll. Thanks to Pandoc, Hakyll has excellent Org-mode support that is only surpassed by Emacs itself. I have managed to move old content pretty painlessly, with just some minor changes to Org-mode markup, some directory name changes, and some tweaks to the default site code generated by hakyll-init.

But the best part is this: I no longer have to do the old crufty moves just to write something on this site!

(The old moves were, to rehash: “publish project from Emacs, then preview stuff in web browser, then go back to Emacs, then find the lost cursor position and go back to whatever I was writing, then lose interest, then procrastinate, and then give up.”).

This is a good thing! I do not have that one lame excuse that held me back from writing! I can write more! I can write more often! Even if nobody else reads the stuff I write!

(I suppose we will see about that soon.)

Some notes

The basics of using Hakyll is quite well documented, and that worked well for me. There’s no need of repeating any of that here. But there was one thing that irked me.

Hakyll worked OK in my computer that runs Fedora (GHC 8.4.4, Cabal 2.2.0.1), but gave an error when running preview server in the computer that runs Debian (GHC 8.6.5, Cabal 2.2.0.1) and another that runs macOS (GHC 8.6.5, Cabal 2.4.1.0):

$ cabal new-configure
$ cabal new-build
$ cabal new-exec site watch
PREVIEW SERVER
Initialising...

  Creating store...
The preview server is not enabled in the version of Hakyll. To
  Creating provider...
enable it, set the flag to True and recompile Hakyll.
  Running rules...
Alternatively, use an external tool to serve your site directory.
Checking for out-of-date items
Compiling

It is a weird error message, and it is annoyingly interleaved with a non-error message. I don’t quite know why this happens, and I haven’t really tried to figure out why it happens either, but I have found a simple solution: add a cabal.project.local in the project root directory, and add the below line in that file:

constraints: hakyll +previewserver

And then rebuild things:

$ cabal new-exec site clean
$ cabal new-exec site watch

That should fix it.

I copied other people’s code

While moving things from Jekyll to Hakyll, I copied Hakyll snippets from many other people:

• Mike Limansky’s Pagination with Hakyll for next/previous links.
• Jasper Van der Jeugt’s Main.hs for Atom feed.
• Group Hakyll posts by year for, well, grouping posts by year, used here.
• Andreas Herrmann’s Jekyll Style URLs with Hakyll for preserving old Jekyll-style URLs.

Thank you for sharing the code, folks! Mine is here, posted as a GitLab snippet.