A vector highlighter

Harder than one would expect...

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

resolver: lts-3.9

packages:
- '.'

extra-deps: 
  - hxt-9.3.1.15
  - regex-posix-0.95.2

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-1.15.0.6

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:

resolver: lts-3.9

packages:
- '.'

- location: '../highlighting-kate-0.6'
  extra-dep: true

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:

resolver: lts-3.9
packages:
  - '.'
  - location: './custom-deps/highlighting-kate-0.6/'
    extra-dep: true
  - location: './custom-deps/pandoc-1.15.0.6'
    extra-dep: true

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

defmodule Pharchive.Router do
  use Pharchive.Web, :router

  pipeline :browser do
    plug :accepts, ["html"]
    plug :fetch_session
    plug :fetch_flash
    plug :protect_from_forgery
    plug :put_secure_browser_headers
  end

  scope "/", Pharchive do
    pipe_through :browser # Use the default browser stack
    resources "/manufacturers", ManufacturerController
    resources "/films", FilmController
    resources "/collections", CollectionController
    get "/", PageController, :index
  end
end

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.