Rouge tells you to write your own formatter and documents eleven, and its own project link points at a different domain than its homepage

The project's own reference link names a different domain than its homepage

One project address is recorded for the site, and the README's reference link definition records a different one.

The metadata names a Canadian domain. The README's link definition for the project name points at a different domain with a different country code, over plain http rather than https.

So a reader who clicks the project's own name in the README, which is how the opening sentence refers to the library, lands somewhere other than the address the repository advertises.

The same pattern runs through the rest of the reference definitions. The languages page is on a documentation subdomain, which is also what the third badge links to, so that one is consistent. The reference for the highlighter whose stylesheets Rouge is compatible with is also plain http.

Three of the six link targets in that block, plus one badge, use http. For a library whose entire output is HTML that gets embedded in other people's pages, a README that hands out insecure links for its own documentation is a small but real inconsistency, and the two domains are the part that matters: one of them is a legacy address that a current reader has no way to know is superseded.

Six of the eleven formatters target one specific output each

The configuration section documents eleven formatters, and most of them exist for a narrow reason that the README states in a sentence.

There is one that emits plain HTML with standard token class names and no wrapping elements. There is one that emits no class names at all and inlines the styles into the style attribute, which the file recommends for email and other places with minimal CSS support. There is one that puts each line in its own div, one that wraps a configurable set of line numbers in a span with a chosen class, one that produces a table with one row per line, one that produces a table with a single row, and one that wraps another formatter in the div structure that Pygments stylesheets expect.

There is one that is a compatibility class for the previous major version, one that emits 256-colour terminal codes, one that emits true-colour terminal codes instead of approximating, and one that wraps tokens in a macro for a TeX system.

Read as a list, that is a small library of output shapes rather than eleven ways of doing the same job. The two that matter most for most users are the first two, and the file's own framing agrees: it says that as of version 2.0 you are encouraged to write your own formatter if you need something custom, and then gives you the eleven.

The two table formatters share three option names and drop a fourth

Two of the eleven produce an HTML table of numbered lines, and their option lists are nearly identical in a way that makes them hard to tell apart.

Both take a starting line number, and both name a CSS class for the gutter cell and one for the code cell, with the same values in both. Both produce a table class, with different values.

Then they diverge. The per-line version takes a class for each row and a template for the identifier attribute of each row. The single-row version takes neither: instead of a row class and a row identifier template, it takes a template for the line number itself, because there is only one row.

So the two option lists differ by exactly one removed name and one replaced name, and the replacement has a different purpose: a row identifier in one case, a rendered number in the other.

The file does explain the difference in output, and it is a real one: the single-row table is friendlier for scripting over the document, but long code lines will break its column alignment. What it does not do is warn that the two formatters' option names are close enough to be guessed wrong, which is exactly the failure mode when you copy an options hash from one to the other.

One formatter is a shim over three others

One entry in the list is not a formatter at all in the way the others are. It is described as a backwards-compatibility class for users of the previous major version, with the options that were supported then.

Its four options each delegate to another formatter in the same list. One switches to the inline formatter with a given theme. One switches to a table formatter, and its default is off. One switches to the Pygments-compatible wrapper, and its default is on. The fourth is a class name for that wrapper.

So one of the eleven is a façade over three of the other ten, and it exists so that code written against the old version keeps working.

That is a reasonable thing to ship and it is also the reason the list is eleven long rather than ten. A reader counting formatters to choose one will include it, and a reader maintaining an application with a pinned old version will be glad it is there.

What is missing is a note that it is a shim. Nothing in the entry says these options will be removed, or points at the version where the shim goes away, so a user who finds it has no way to learn that the modern equivalent is three separate formatters.

The tutorial for writing your own formatter stops in the middle of its loop

The README's most useful section for anyone extending the library ends mid-statement.

The prose before the example is good. Subclass the base formatter class, define a tag, implement a method that receives token and value pairs and yields out chunks to be concatenated. Two helper methods are named, one on the base class that separates tokens into lines and one on the HTML formatter that escapes and renders span tags, plus an override point for changing how an individual span is rendered.

Then the code example opens. It subclasses the HTML formatter, the main entry method carries a comment explaining that it receives an enumerable of pairs and should yield fragments, the method yields an opening div with a class of its own, and then the loop begins.

And the example stops there, in the middle of the destructuring in the loop header.

So the one thing the README tells you to do yourself is demonstrated to the exact point where it starts being interesting, and the fragment you are given ends with an unfinished line.

Everything after it, in the file, is truncated too, so the closing advice is not available either. The prose is enough to get started; the code is not enough to copy.

The command line accepts a Sublime Text theme file as its theme argument

The command line tool is three lines of example, and all three are worth reading.

$ rougify foo.rb
$ rougify foo.rb -t monokai.sublime
$ rougify style monokai.sublime > syntax.css

The first line highlights a file with the default settings. The second passes a theme, and the theme is given as a path to a file with the extension of a different editor's colour scheme.

So the library reads another editor's theme format rather than only its own. That is a deliberate interoperation decision: a user moving from that editor to a Ruby toolchain gets their colours for free, and the file uses a well-known theme name to demonstrate it.

The third line is the interesting one. A style subcommand takes the same theme and writes a stylesheet to standard output. That means the theme file is the interchange format in both directions: you can highlight with a theme someone else wrote, and you can generate a stylesheet from it for a web page.

The gem name, the library name and the command all differ by a suffix, which is the only friction here and is exactly what a package manager handles.

A lint to-do file and a committed temporary directory

Two entries at the repository root describe how the project is worked on rather than what it does.

There is a linter configuration and a second file beside it whose name marks it as a to-do: a list of violations the project has accepted and intends to fix later. For a library whose README tells you to write your own formatter, the existence of an outstanding lint list is worth knowing about, because it tells you the codebase has accumulated warnings that are being tracked rather than fixed.

There is also a temporary directory, committed. Whatever it holds, it is not meant to be there.

Everything else in the root is conventional: a gem specification, a gemfile, a rakefile, a tasks directory, a spec directory, a library directory, a directory of generated documentation with its own options file, a watch configuration for a file-watcher, a Rack configuration file at the root, and an agent instruction file.

The Rack file is the one that hints at scope the README does not mention. A syntax highlighter as a gem does not need a Rack application entry point; something in this repository serves over HTTP.

The releases land on a weekend and a New Year's Eve

The three newest release dates are worth reading for their pattern.

One was published on the last day of December. The next came in late May, and the newest in early August. All three are minor version bumps.

That tells you the cadence is roughly quarterly and that the maintainer publishes when the work is done rather than on a schedule. The December release landing on New Year's Eve is consistent with that.

What the dates do not tell you is the compatibility story. A library whose minor version moved twice in the visible history, and whose formatter guidance dates from a much older major version, is signalling that the major number is the thing to watch.

For a user the practical consequence is small: pin the version, and read the changelog in the repository rather than trusting the release note titles, which in the visible history are just the version numbers repeated.

Editorial conclusion

Use Rouge if you are in the Ruby ecosystem and want highlighting that is both a library and a command line tool, because the two are the same gem and the command line is a genuine part of the interface rather than a developer convenience. It is also the right choice if you need HTML that drops into Pygments stylesheets without writing a wrapper. Three things to check before you commit. Which formatter you actually need, because there are eleven documented and the README recommends writing your own, so the choice is yours to make rather than the library's. Which domain you trust for the project site, because the README's own reference link and the repository's homepage field name two different addresses. And what you will do about maintenance signals, since the repository's licence field reports nothing recognised while a licence file sits at the root, so read the file rather than the metadata if that matters to you.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. rouge-ruby/rouge on GitHub