Tags: haskell, hakyll, oss, stack, pandoc, highlighting-kate

The problem

I am consistently aggravated at the lack of Elixir specific language highlighting in my Elixir posts! Surely there is something I can do!

The Background

This site is generated with Hakyll. Hakyll uses Pandoc for converting markdown files to HTML, Pandoc uses highlighting-kate for syntax highlighting, highlighting-kate uses Kate syntax definition files! Whew, thats a stack.

Speaking of stack, I use Stack to ensure reproducible builds and safe dependency upgrades for this site.

So there are a few moving parts to this.

The Investigation

To start this process I did some research to see how others had added custom syntax highlighting to Hakyll. The first article I discovered was a fantastic piece by Jorge Israel Peña about adding a custom pygments pipeline to his site. His solution was to add a pygmentize server and during generation reach out to it from his Haskell code; super super cool stuff but I wanted to keep things within the Haskell ecosystem because I need the practice and education! Next up was a great post from 2013 about adding better Scala syntax highlighting to a Hakyll site. In this approach, the author took advantage of the cabal unpack command, which will take an installed package and “unpack” it into a source code directory at the current path. After unpacking, the author made changes, re-compiled it, re-generated their site with the locally changed version; boom, better highlighting. This approach intrigued me because it does not introduce an additional language dependency to my project. All I needed now was a Kate syntax file.

rubencaro wrote a Kate syntax file back in 2014 which I discovered via the KDE bugtracking system. It looks like rubencaro’s syntax file will make it into Kate and therefore highlighting-kate sometime soon, but I want syntax highlighting now!

The Solution

Now that I had all the pieces figured out, it was just a matter of the doing of the thing. The fact that I am using Stack to manage my builds was a godsend here. Stack also provides an unpack command which does the same thing as the Cabal version. So I did the following:

stack unpack highlighting-kate-0.6.0

This gave me access to the highlighting-kate source. After reading the README and the Makefile for the project, I added rubencaros Elixir syntax file to /xml and ran the following:

stack init

From the Makefile there are a couple extra dependencies for the highlighting-kate project in order to generate the Haskell processors for different languages, so I modified the stack.yml to account for this

then to finish up this process I ran:

stack build
stack runhaskell ParseSyntaxFiles.hs xml/
stack build

Ok, now we are done with highlighting-kate, now on to pandoc!

stack unpack pandoc-

All I need to do with pandoc is make sure that it is being build with the local version of highlighting kate, so I run a:

stack init

and modify the stack.yml to look like:

I make sure that everything built properly, and ran a test markdown file with a code fenced elixir sample and everything worked properly. All that is left to do is make sure that my blog gets built with these local dependencies! So I updated my root stack.yml to look like:

And recompiled the project. As you can see, Elixir code is now properly handled!

A big thanks to rubencaro for writing the Elixir syntax file! All thats left is to open up a PR on highlighting-kate to get these changes in! That’s all for today readers.