New Year, New Changes
You may have noticed a bit of a difference on the Visoft, Inc. Blogs today. I started the first (of hopefully many) changes to the site. The newer code snippets (really old ones have embedded styles, yuck :)) have a new look. What’s going on here?
If you aren’t familiar with Markdown, it is a very simple text-to-HTML conversion tool. Instead of messing with messy HTML tags, you can easily inject things like bold words, italics, or links, seamlessly while typing.
The code snippet needed for SyntaxHighlighter isn’t that complex, it’s simply a
pre tag with a
brush: LANGUAGE. In addition to the
brush, you can do other things, like add line numbers and add highlighting to specific lines. It’s a nice package, albeit a little heavyweight. In addition, the default outputted HTML for a code block with Markdown is
<pre><code></code></pre>. In order to use SyntaxHighlighter, you’d either have to write the code blocks using raw HTML (something you can do in Markdown) or use something on the server side to change the blocks to just
<pre> tags. Not that big of a deal, but I decided to look around for other options.
By default, the
<pre><code> structure emitted by Markdown is what highlight.js highlights. It will also automatically pick up the code’s language without additional attributes. Those were the primary reasons for switching to highlight.js. In addition, highlight.js supports a ton of languages (59 at last count), has lots of built-in styles, and many plugins, mods, and extensions.
Nothing is “perfect.” It’s only fair to point out limitations of highlight.js. The biggest one is the lack of line numbers. According to the project maintainer, it’s a feature. Of course, you may not see it as such. If that’s the case, there are forks of the project that have added line numbers. Also, there is a branch of the main project that includes line numbers, it just isn’t in the master branch.
Comparing highlight.js to SyntaxHighlighter, it doesn’t stripe or highlight lines either. None of these limitations are really a deal-breaker for me. The simplicity of the library is one of its biggest strengths.
Now that we’re moving to a new highlighting library, what do we do with all of the existing code snippets? Remember the SyntaxHighlighter code snippets are just a
pre tag with the brush class, e.g.
<pre class="brush:ruby"></pre>, but highlight.js is looking for
<pre><code></code></pre> (the default code block syntax outputted by Markdown). There are different options for converting the snippets over, but the solution I came up with is to write a WordPress plugin. The plugin makes it easy to move to highlight.js (or another syntax highlighter that uses the
<pre><code> structure) without any permanent changes. The plugin is called, “Goodbye Syntax Highlighter” and is open-source. It simply converts
<pre> tags into the
<pre><code> structure. It also takes the
class="brush:LANGUAGE" and adds it as a hint for highlight.js. So, for example, take the following SyntaxHighlighter snippet:
<pre class="brush:ruby"> puts "Hello World" </pre>
and the plugin would convert that to:
<pre> <code class="language-ruby"> puts "Hello World" </code> </pre>
The class of
language-is the recommended HTML5 syntax highlighting “hint”. This was changed in Goodbye Syntax Highlighter v0.1.1. Version v0.1.0 uses a class of just the language (e.g. class=”ruby”). Both formats work for highlight.js.
Markdown Syntax Sugar
We spoke of how highlight.js automatically detects the language of your code snippets. Due to that, the majority of the time, the language hint (described above) isn’t needed for highlight.js. However, in the case of short snippets, you should really use one since many languages look the same. In the cases where I have short snippets of code, I wanted an elegant way of using Markdown instead of reverting to HTML. I came across the WP-Markdown-Code-Highlight WordPress plugin and liked the idea. Unfortunately, it didn’t work with highlight.js. That encouraged me to write my own plugin, wp-markdown-syntax-sugar.
Usage is simple. Just add a shebang as the first line of your code with the appropriate language, like so:
#!ruby class Foo < Bar def hello puts "Hello World!" end end
The plugin looks for the shebang and translates that into the HTML:
<pre><code class="language-ruby">class Foo < Bar def hello puts "Hello World!" end end</code></pre>
Note: Like v0.1.0 of Goodbye Syntax Highlighter Goodbye Syntax Highlighter , wp-markdown-syntax-sugar uses a class of just the language. v0.1.1 of wp-markdown-syntax-sugar implements the HTML5 recommended class name of
Well, there you have it. I’d be interested in what you think of highlight.js. Do you miss the line numbers? If you decide to make a switch, I’d love feedback on the two WordPress plugins, Goodbye Syntax Highlighter and wp-markdown-syntax-sugar