= Rouge
:url-rouge: http://rouge.jneen.net
:url-rouge-gem: https://rubygems.org/gems/rouge
:url-rouge-repo: https://github.com/rouge-ruby/rouge/tree/HEAD/lib/rouge/themes

{url-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 {url-rouge-gem}[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.

[,asciidoc]
----
: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`.

[.line-through]#rouge-linenums-mode# (not currently implemented, see https://github.com/asciidoctor/asciidoctor/issues/3641[#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 {url-rouge-repo}[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.

.Activating the Rouge syntax highlighter and applying a different style
[source,asciidoc]
....
:source-highlighter: rouge
:rouge-style: monokai

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

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

.Customizing a source block with Rouge line numbers
[source,asciidoc]
....
: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.