CSS Code

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?

Code Snippets

For many years I have utilized Alex Gorbatchov’s SyntaxHighlighter. It served me well through the years, but I started looking at other ways of blogging, namely Markdown.

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 class of 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.

Highlight.js Pros

There are a ton of syntax highlighting options available. I came across highlight.js reading the Completely Unfair Comparison of JavaScript Syntax Highlighters. After looking at various options, I decided to give highlight.js a try within the workflow of working with Markdown.

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.

Highlight.js Cons

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.

Goodbye SyntaxHighlighter

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 language-.

Conclusion

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