Rouge

Rouge is an extendable code highlighter written in Ruby that supports a vast array of languages.

Install Rouge

To use Rouge with Asciidoctor, you need the rouge gem. You can use one of the following methods to install Rouge.

Install using gem (all systems)

$ gem install rouge

Install using apt-get (Debian-based systems)

$ sudo apt-get install ruby-rouge

Install using dnf (Fedora-based systems)

$ sudo dnf install rubygem-rouge

Install using pacman (Arch Linux-based systems)

$ sudo pacman -S ruby-rouge

Assign rouge to source-highlighter

Once you’ve installed the gem, assign the rouge value to the source-highlighter attribute in the document header to activate it.

:source-highlighter: rouge

Rouge attributes

You can further customize the source block output with additional Rouge attributes.

rouge-css: Controls what method is used for applying CSS to the tokens. Can be class or style. Default: class.
rouge-linenums-mode (not currently implemented, see #3641): Controls how line numbers are laid out. Can be table or inline. If line wrapping is enabled on preformatted blocks (i.e., prewrap), and you want to use line numbering on source blocks, you must set the value of this attribute to inline in order for the numbers to line up properly with their target lines. Default: table.
rouge-style: Controls the color theme used to for highlighting. You can find the list of themes in the Rouge code repository.

Typically, you set these attributes using the CLI or API (e.g., -a source-highlighter=rouge -a rouge-style=colorful) so you don’t have to define them in each document. However, you can define them per document as shown in the following example.

Example 1. Activating the Rouge syntax highlighter and applying a different style

:source-highlighter: rouge
:rouge-style: monokai

[,ruby]
----
puts "Hello, Rouge!"
----

You can enable line numbering using the linenums option on the block.

Example 2. Customizing a source block with Rouge line numbers

:source-highlighter: rouge

[%linenums,ruby]
----
ORDERED_LIST_KEYWORDS = {
  'loweralpha' => 'a',
  'lowerroman' => 'i',
  'upperalpha' => 'A',
  'upperroman' => 'I'
   #'lowergreek' => 'a'
   #'arabic'     => '1'
   #'decimal'    => '1'
}
----

It’s also possible to enable linenums for all source blocks by setting the source-linenums-option attribute on the document.