1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
|
= 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.
|
