Rack Middleware for Code Highlighting

Why one should use middleware (filter) for code highlighting? The short answer is: because it is unobtrusive.

In pre-Rack applications era the possible approaches were:

pure javascript

Ruby tips from me, your idol: I can not tell you how much time I’ve wasted trying to add in some cool feature into rails. I would dig into the rails internals, override methods, do all kinds of tricky stuff. I thought I was awesome. A month later rails comes out with some cool new feature, I update rails and everything explodes.

Code must be html-escaped.

gems (ok) + conection (obtrusive)

To install it, run:

sudo gem install wbzyl-rack-codehighlighter -s http://gems.github.com

Analyze Syntax Highlighting packages from the The Ruby Toolbox page.

Exisitng practice is obtrusive:

http://carboni.ca/projects/harsh/  
  unless HAML is used
http://redclothcoderay.rubyforge.org/  
http://github.com/augustl/redcloth-with-coderay
  how to use with Rails
  does't degrade to html: new source tag
http://github.com/arya/tm_syntax_highlighting/
  how to connect to rails/sinatra?

Pure Javascript highlighters:

In Ruby on Rails (redcloth)

Add censored method/example.

Using with Rack application

Rack::Codehighlighter can be used with any Rack application, for example with a Sinatra application. If your application includes a rackup file or uses Rack::Builder to construct the application pipeline, simply require and use as follows:

gem 'wbzyl-rack-codehighlighter'
require 'rack/codehighlighter'

gem 'ultraviolet'
require 'uv'

use Rack::Codehighlighter, :ultraviolet
run app

Instead of ultraviolet you can use other supported highlighters: syntax, coderay, prettify.

Include in the layout one of provided stylesheets.

Using with Rails

In order to use include the following in a Rails application config/environment.rb file:

require 'rack/codehighlighter'

Rails::Initializer.run do |config|  
  config.gem 'wbzyl-rack-codehighlighter'
  config.middleware.use Rack::Codehighlighter, :ultraviolet
end

Check the Rack configuration:

rake middleware

More configuration options: see below.

Ruby tips from me, your idol: Think about what you are doing, try to understand it, come up with a better solution, etc. Is it Rack a cool feature?

Configuration options

Markup your code with:

<pre><code>:::ruby
...
</code></pre>

Quick Sinatra example

Example (incomplete html, needs a layout file with link to css):

# file example.rb

require 'rubygems'
require 'sinatra'

gem 'coderay'
require 'coderay'

gem 'wbzyl-rack-codehighlighter'
require 'rack/codehighlighter'

use Rack::Codehighlighter, :coderay

get "/" do
  erb :hello
end

__END__

Run the above example with:

ruby example.rb

More Sinatra examples

The default markup:

If the first line begins with three colons, the text following the colons identifies the language (ruby in the example). The first line is removed from the code block before processing.

The directory examples contains ready to run, simple Sinatra app. Try

rackup -p 4567 config.ru

or better yet (requires the thin gem to be installed):

thin --rackup config.ru -p 4567 start

Finally, visit the following url:

http://localhost:4567

and contemplate the sheer beauty of the rendered code.

Supported Highlighters

These currently include: Syntax (fast), Coderay (very fast), Ultraviolet (slow, but highlights almost any language).

The Codehighlighter gem provides a thin interface over a bunch of exisitng code highlighters to make their usage as generic possible.

What does it mean? Explain.

Syntax

Languages supported by Syntax:

xml
ruby

Coderay

Languages supported by Coderay:

C, CSS
Delphi, diff
HTML, RHTML (Rails), Nitro-XHTML
Java, JavaScript, JSON
Ruby
YAML

Google Code Prettify, pure Javascript

Languages supported by Prettify:

css, lisp, hs, lua, sql, vb, wiki,
bsh, c, cc, cpp, cs, csh, cyc, cv, htm, html,
java, js, m, mxml, perl, pl, pm, py, rb, sh,
xhtml, xml, xsl

Ultraviolet

The ultraviolet gem needs oniguruma regexp library.

On Fedora install the library with:

sudo yum install oniguruma

For installation instruction from sources, see Carbonica

Now, install the gem:

sudo gem install ultraviolet