I am consistently aggravated at the lack of Elixir specific language highlighting in my Elixir posts! Surely there is something I can do!
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.
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!
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:
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-220.127.116.11 - 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-18.104.22.168
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:
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-22.214.171.124' 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.