You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
108 lines
3.0 KiB
108 lines
3.0 KiB
4 years ago
|
////
|
||
|
|
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>
|
||
|
|
....
|