////
Included in:

- user-manual: Source Code Highlighting: Rouge installation
////

https://rouge.jneen.net[Rouge] is an elegant, extendable code highlighter written in pure Ruby that supports a vast array of languages.

In order to use Rouge with Asciidoctor, you need the https://rubygems.org/gems/rouge[rouge] RubyGem.
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 rouge

Install using `dnf` (Fedora-based systems)::
+
 $ sudo dnf install rubygem-rouge

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

[source]
----
:source-highlighter: rouge
----

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::
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 https://github.com/rouge-ruby/rouge/tree/master/lib/rouge/themes[Rouge code repository].

.Customizing a source block with Rouge line numbers
[source]
....
:source-highlighter: rouge
:rouge-linenums-mode: inline

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

==== Highlight Select Lines

Not to be confused with syntax highlighting, you can configure Rouge to highlight (i.e., emphasize) select lines in order to call attention to them.

The highlight attribute accepts a comma or semi-colon delimited list of line ranges.
A line range is represented by two numbers separated by a double period (e.g., `2..5`).
These numbers correspond to the line numbers of the source block, inclusive, where the first line is 1.
This feature is activated on a source block if the highlight attribute is defined and at least one of the line numbers falls in this range.

.Highlight select lines in a source block
[source]
....
:source-highlighter: rouge
:docinfo: private

[source,ruby,linenums,highlight=2..5]
----
ORDERED_LIST_KEYWORDS = {
  'loweralpha' => 'a',
  'lowerroman' => 'i',
  'upperalpha' => 'A',
  'upperroman' => 'I',
}
----
....

You will need to give it some help using extra CSS provided by the following docinfo file:

.Docinfo file to support line highlighting with Rouge
[source,html]
....
<style>
pre.rouge .hll {
  background-color: #ffc;
}
pre.rouge .hll * {
  background-color: initial;
}
</style>
....