Find file
Fetching contributors…
Cannot retrieve contributors at this time
276 lines (187 sloc) 8.36 KB

Rack::Codehighlighter middleware

The Rack::Codehighlighter is a middleware which allows for easy connecting a code highlighter of somebody's choice to an HTML page containing pieces of programming code. Parameters to Rack::Codehighlighter are: the name of a highlighter and a specification of how to find the pieces of code in the page.

It supports the most popular Ruby code highlighters of today:

  • ultraviolet
  • coderay
  • syntax
  • pygments (through pygments.rb)

As well as

To ease testing it implements censor highlighter.

How it works?

Rack::Codehighlighter looks for code blocks to be highlighted in the HTML produced by your application. For each block found it calls requested highlighter.

Installing and Usage

Install the gem with:

sudo gem install rack-codehighlighter

In order for the highlighting to show up, you’ll need to include a highlighting stylesheet. For example stylesheets you can look at stylesheets in the examples/public/stylesheets directory.


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

require 'coderay'               # get one of supported highlighters 
require 'rack/codehighlighter' do |config|  
  config.gem 'coderay'
  config.gem 'rack-codehighlighter'

  config.middleware.use Rack::Codehighlighter, :coderay, :element => "pre", :pattern => /\A:::(\w+)\s*\n/

Any Rack application

The rack-codehighlighter gem 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 'coderay'       # get one of supported highlighters 
require 'coderay'   

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

use Rack::Codehighlighter, :coderay, :element => "pre", :pattern => /\A:::(\w+)\s*\n/
run app

Rack::Codehighlighter by an example

To colorize code in pre elements with well known coderay highlighter use the following:

use Rack::Codehighlighter, :coderay, :element => "pre", :pattern => /\A:::(\w+)\s*\n/

The first parenthesized expression from the pattern /\A:::(\w+)\s*\n/ will be used to match the language name. For example, from the pre element below:

puts "hello world"

the ruby name is extracted.

To find the appropriate name to use for programming language, look at the lists below.

Next, the matched element is removed and the second line is passed to coderay highlighter for processing.

The highlighted code returned by the coderay highlighter is wrapped with pre element with attributes appropriate for the codehighlighter used.

More examples

In examples displayed below, the default value of each option is used.


use Rack::Codehighlighter, :coderay,
  :element => "pre", :pattern => /\A:::(\w+)\s*(\n|&#x000A;)/i, :logging => false


use Rack::Codehighlighter, :ultraviolet, :theme => "dawn", :lines => false,
  :element => "pre", :pattern => /\A:::(\w+)\s*(\n|&#x000A;)/i, :logging => false


use Rack::Codehighlighter, :ultraviolet, :markdown => true, 
  :theme => "minimal_theme", :lines => false, :element => "pre>code", 
  :pattern => /\A:::([-_+\w]+)\s*(\n|&#x000A;)/, :logging => false,
  :themes => {"vibrant_ink" => ["ruby"], "upstream_sunburst" => ["objective-c", "java"]}

Unofficial Pygments API (uses web service no dependencies):

use Rack::Codehighlighter, :pygments_api, :element => "pre",
   :pattern => /\A:::([-_+\w]+)\s*(\n|&#x000A;)/, :logging => false

Pygments (with pygments.rb):

use Rack::Codehighlighter, :pygments, :element => "pre",
   :pattern => /\A:::([-_+\w]+)\s*(\n|&#x000A;)/, :logging => false


use Rack::Codehighlighter, :syntax,
  :element => "pre", :pattern => /\A:::(\w+)\s*(\n|&#x000A;)/i, :logging => false


use Rack::Codehighlighter, :censor, :reason => "[[--  ugly code removed  --]]",
  :element => "pre", :pattern => /\A:::(\w+)\s*(\n|&#x000A;)/i, :logging => false

Markdown, Maruku and RDiscount processors, the code is wrapped with pre>code.
To remove this extra one level of nesting the :markdown option should be used:

use Rack::Codehighlighter, :coderay, :markdown => true,
  :element => "pre>code", :pattern => /\A:::(\w+)\s*(\n|&#x000A;)/i, :logging => false

Remark: Within pre tag, HAML replaces each new line characters with the &#x000A; entity (line feed) so that it can ensure that it doesn't adversely affect indentation. This change confuses both rack-codehighlighter and the highlighters themselves (e.g. Ultraviolet and Coderay). So, to support pre tags as rendered by HAML, &#x000A; was added to the default pattern.

The examples directory contains several rackup files. Each rackup file uses a different highlighter. Install the shotgun gem and try, for example, the Pygments highlighter:


The results could be checked at http://localhost:9393.

Try it!

A simple Copy & Paste example.

# example.rb

require 'rubygems'
gem 'sinatra'
require 'sinatra'
gem 'rack-codehighlighter'
require 'rack/codehighlighter'

use Rack::Codehighlighter, :censor, :reason => '[[--difficult code removed--]]'

get "/" do
  erb :hello

@@ hello
<h3>Fibonacci numbers in Ruby</h3>
def fib(n)
  if n < 2
    fib(n-2) + fib(n-1)

Run the example with:

ruby example.rb

and check results at http://localhost:4567.

Supported highlighters

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


Languages supported by Syntax:

  • xml
  • ruby


Languages supported by Coderay:

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


The ultraviolet gem needs oniguruma regexp library.

On Fedora install the library with:

sudo yum install oniguruma oniguruma-devel

For installation instruction of the oniguruma library from sources, see Carbonica

Now, install the gem:

sudo gem install ultraviolet

See also Ultraviolet themes gallery

Ultraviolet supports almost any language:

  • actionscript, active4d, active4d_html, active4d_ini, active4d_library, ada, antlr, apache, applescript, asp,
  • bibtex, blog_html, blog_markdown, blog_text, blog_textile, build, bulletin_board
  • c, c++, cake, camlp4, cm, coldusion, context_free, cs, css, css_experimental, csv
  • d, diff, dokuwiki, dot, doxygen, dylan
  • eiffel, erlang, f-script, fortran, fxscript
  • greasemonkey, gri, groovy, gtd, gtdalt
  • haml, haskell, html, html-asp, html_django,, html_mason, html_rails, html_tcl
  • icalendar, inform, ini, installer_distribution_script, io
  • java, javaproperties, javascript, javascript_+_prototype, javascript_+_prototype_bracketed, jquery_javascript, json
  • languagedefinition, latex, latex_beamer, latex_log, latex_memoir, lexflex, lighttpd, lilypond, lisp, literate_haskell, logo, logtalk, lua
  • m, macports_portfile, mail, makefile, man, markdown, mediawiki, mel, mips, mod_perl, modula-3, moinmoin, mootools, movable_type, multimarkdown
  • objective-c, objective-c++, ocaml, ocamllex, ocamlyacc, opengl
  • pascal, perl, php, plain_text, pmwiki, postscript, processing, prolog, property_list, python, python_django
  • qmake_project, qt_c++, quake3_config
  • r, r_console, ragel, rd_r_documentation, regexp, regular_expressions_oniguruma, regular_expressions_python, release_notes remind, restructuredtext, rez, ruby, ruby_experimental, ruby_on_rails
  • s5, scheme, scilab, setext, shell-unix-generic, slate, smarty, sql, sql_rails, ssh-config, standard_ml, strings_file, subversion_commit_message, sweave, swig
  • tcl, template_toolkit, tex, tex_math, textile, tsv, twiki, txt2tags
  • vectorscript
  • xhtml_1.0, xml, xml_strict, xsl
  • yaml, yui_javascript