Pandoc syntax highlighting in Sublime Text 3

This post is a bit specific, but hopefully useful for anyone who uses pandoc and happens to use Sublime Text as their text editor of choice.

I bought Sublime Text a few years ago when I was first trying to pick up Python. It was as a sort of nerdy motivation since it’s overkill (and kind of expensive) for someone just learning basic programming. I had also wanted to try to structure my work around simple plain text files as much as possible, and I had a notion that taking the time to master a professional text editor would be useful in many different scenarios. Truthfully, this has paid many dividends, from writing proposals, to (admittedly light) programming, to managing Gaussian output files, to simple things like formatting lists of e-mail addresses.

Up until recently, I was using a lightly modified version of the Pandoc Academic Sublime Text plugin to handle syntax highlighting of my pandoc documents. It was working well, but there were some minor annoyances. For example, I like to hard wrap my text files (i.e., add actual line breaks at the ends of lines). This may sound ridiculous in 2016, but it’s trivially easy with Sublime’s Wrap Plus plugin and it allows me to exceed the line character limit when needed (helpful for tables or long URLs, for example). The problem was that Pandoc Academic’s syntax support would not catch, for example, bold/italic formatting that extended over multiple lines. This isn’t a big deal, but it always bugged me a little.

The most recent version of Sublime Text 3 (still technically in beta but it’s been completely useable for years now) introduced a new specification for syntax highlighting based on a simple YAML format. I had played with the tmLanguage format used previously (and still supported), just enough to realize that I wasn’t very good at it, but this new format seemed clear enough and powerful enough that I thought I’d try building a pandoc syntax file from the ground up.

The result of this little project is PandocSyntax, a syntax definition that I’ve posted on GitHub. The code’s not too complex (and my regex skills are ok at best), but here’s the end result:


PandocSyntax is designed to be used with the Monokai Extended color scheme, which is a nice extension to the default Sublime Text color scheme (Monokai) that has much better Markdown support. I’m sure it would be pretty easy to adapt to other color schemes by taking a few minutes to adjust the scope definitions. The screenshot above is taken using a slightly modified version of Monokai Extended that removes the coloring for bold/italic formatting.

I’ve tried to keep as close to the pandoc Markdown flavor as possible. Most features are implemented, although I can’t for the life of me figure out a way to support Setext style headers. Some of pandoc’s special requirements are enforced (e.g., headings and lists must follow blank lines). Overall, I’ve tried to keep the coloring consistent with Monokai Extended’s Markdown implementation. I’ve chosen to color the control characters as comments, which I think improves overall readability. Many features (bold/italics, figure captions, etc.) can be broken over multiple lines.

Leave a Reply

Your email address will not be published. Required fields are marked *