Syntax Colors For My Blog

As I use the Nikola static site generator for my blog, the first idea was to check Nikolas documentation for syntax coloring. Trying a few search patterns on the Nikola handbook turned up a lead that Nikola provides the listing short code exactly for this purpose. Unfortunately, the documentation is very terse and no hint is given as to what languages can be highlighted. The single example uses "python" and nothing else besides a link into the docs of docutils is provided.

The documentation behind this link thankfully leads us to the enlightening description of the code directive.

Besides mentioning that Pygments is doing the hard work in the background, it also includes a link to the supported languages of the Pygments library. Although the list is impressive, I could not find any candidate for what I was looking for. After all the primary target for my efforts are not source code files but transcripts from shell sessions. In the hope for more precise information I started reading the Pygments documentation itself. After a lot of browsing, I found the Available Lexers page and finally the BashSessionLexer. So with the short name of "console", all it took was to change the ReST example from above into the following example. Again it is followed by its rendering:

This yields better output:

So to add syntax coloring to my ReST posts, all I had to do was to change the double colon "::" at the end of the paragraph before the listing into a single colon ":" and add the code block directive line.

When I started my blog and decided for Nikola as the base for it, the choice to use ReST formatting for the posts was a sane one. The Nikola documentation lists a lot of input languages but most examples and the default settings use ReST. As I used ReST also for other documents, I saw no need to look for alternatives and once I had worked out the basic formatting for posts, things started to settle in. How to use elements like sections, fonts, listing blocks, images and links to other posts, was worked out once and then usually copied forward from older posts where they were known to work.

Even though this served me well for 5 years, gradually I started feeling the pain of ReST, which even after years of usage still feels like an adhoc markup language. A lot of things that I want are pretty difficult to achieve or simply inelegant. With this growing itch and as it was always in the back of my mind as another good choice for a flexible markup, I starting refreshing my knowledge about AsciiDoc.

As Nikola supports blog posts in Asciidoc with a plugin out of the box, I decided to find the Asciidoc correspondences to the markup I use in the ReST posts and give it a try for the next post. Thankfully this was not very difficult and in the process I even found that centering images is a lot easier with this markup than what I used in ReST.

I briefly considered converting the existing posts over into Asciidoc but decided that it was simply not worth the effort. Nothing would change for the reader of the blog but it would take non-trivial effort to do the conversion of a sizable amount of posts. Only costs and no benefits quickly convinced me on giving up on this idea.

So with the syntax colors now working in ReST it was even more important to get the new setup working from Asciidoc also. Sure enough there was only a minor twist to the story. Next to marking the listing blocks with "[source,<language>]" Pygments needs to by enabled at the top of the post with

So with the toolbox to add syntax colors to all of my posts I extended this nice feature to all of my blog posts. I do think the result is much better to read and understand so the required effort was well worth it.

If you are interested, it is very easy to view the source file for a specific post by clicking on the "Source" link just below the title.

Sometimes it is not so straightforward going from a perceived need - "I want the console transcripts to be colored in a similar way to my terminal" - to the actual solution: "enable and use Pygments with one of the many lexers it provides". In such cases it may be required to follow a few leads within the primary documentation. Coupled with a few web searches for the general direction it should then be possible to find a solution due to the vast functionality of Free Software and the ecosystem that has been built on top of it. Having a single solution to do syntax coloring ("Pygments") integrated into a broad application space (ReST and AsciiDoc) is a very elegant way to share the scarce resources of Free Software developers.

Even though the syntax coloring is nice, in a way the total setup is not very efficient. At first the shell (bash in my case) provides the colors but the color information is dropped on copying the output into the plain text blog files. Another piece of software is used to re-add the colors - of course a little bit differently. What I still miss is a way to include output colorized by a functionality beyond what Pygments is capable of. The checksec post shows an example of such an context. I would really like to include the output into posts without taking a screenshot to preserve the colors. Screenshots are more effort and yield non-searchable images instead of text.