WpPygments Plugin

This plugin is the source code colorization plugin which uses great Pygments library.

Download: http://wordpress.org/extend/plugins/wppygments/

Why another colorization?

There’s 1 major solution available for WordPress at the moment: SyntaxHighlighter Evolved, and a number of pure JS packages that can simply be included into each WordPress page, like highlight.js.

So, why another one?

Well, primarily I just needed CoffeeScript support. This is a new JS-based language, and these libraries do not support it. Obvious solution? Read their docs, create your own parser (actually, lexer) based on the existing sample, plug it into their infrastructure.

I tried. But it appeared to be not so obvious. More difficult than writing WordPress plugin using PHP (which I don’t like and didn’t know) and WordPress API (which I didn’t know and don’t like).

So, the idea behind the plugin is using probably the best available syntax highlighting library out there – Pygments.

Pros and Cons

JS libraries

Pros:

• Work on client side – raw code is shown instantly,
• Have useful tools like copy to clipboard, print the code, etc.

Cons:

• Work every time the user views the page,
• Have limited (see below) number of supported languages,
• Some of them require special BB-style markup, which won’t gracefully degrade if the plugin fails or is switched off,
• Hard to add custom languages (at least to me ).

WpPygments

Pros:

• Caches its results, and only runs when the code snippet (not the page itself, the specific code snippet) is created or updated,
• Has the same useful tools,
• Works with the most common and reasonable way of embedding code snippets into HTML (thus, if the plugin is switched off, your code snippet still shows well without any changes)
• Has great number of supported languages, and quite big number of beautiful styles.

Cons:

• Works before the page is loaded
  

  Why? Making it called from JS would be a better solution, but Ajax cross-domain calls are normally prohibited (see below for the explanation of how the plugin works)

Comparing Numbers

Library	Supported langs #	Default styles #
Alex Gorbatchev’s library (the one behind SyntaxHighlighter Evolved)	23	7
highlight.js	40	13
Pygments (the one behind WpPygments’ service)	197 (including combinations like CSS+Django)	18

How to use it

The best way to include your code snippets into HTML is using <pre><code>...</code></pre> construct. It makes your snippet shown in monospace font, and whitespace are preserved.

Actually, this is everything you need since WpPygments plugin is activated. But one more thing is highly recommended — set the lang attribute on code element.

Only code elements inside pre are colorized.

See the list of supported codes. Be careful: language codes are in the second column, and they are case-sensitive.

Prevent colorization for the specific element

To prevent specific code from being colorized set class="nocolor" on the code element.

Where is it working

In your posts, in your WordPress pages, and in comments — everywhere where you put your code inside <pre><code lang="yourlang">...</code></pre>.

How it works

Every time you edit your post, or view it, all codes that are inside of pre (and don’t have class="nocolor") are picked. If lang attribute is set, it's read, otherwise language will be supposed by Pygments library.

Your WordPress DB is then checked if it already has colorization cache for each code snippet (checked based on the snippet hash). If cache doesn’t exist, the code is submitted to the http://pygmentizer.appspot.com service. Resultant code is then included into your post page, and also saved in the DB cache table.