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
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
|
= Pygments
:url-pygments: https://pygments.org
:url-pygments-lang: https://pygments.org/languages/
:url-python: https://www.python.org
:url-pygments-gem: https://rubygems.org/gems/pygments.rb
{url-pygments}[Pygments^] is a popular syntax highlighter that supports a broad range of {url-pygments-lang}[programming and template languages^].
== Install Pygments
In order to use Pygments with Asciidoctor, you need {url-python}[Python] and the {url-pygments-gem}[pygments.rb gem^].
The pygments.rb gem manages calls to Pygments, which is an external program that runs using Python.
TIP: You do not need to install Pygments itself.
It comes bundled with the pygments.rb gem.
IMPORTANT: You must have Python installed to use pygments.rb.
The version of Python required depends on which pygments.rb release you're using:
* pygments.rb 1.x requires Python 2.
Check that you have a `python2` (Linux), `python` (macOS), or `py -2` (Windows) executable on your PATH.
(On macOS, verify that the `python` executable uses Python 2 by running `python -V`).
* pygments.rb 2.x requires Python 3.
Check that you have a `python3` (Linux/macOS) or `py -3` (Windows) executable on your PATH.
.Installing Python and the pygments.rb gem via the CLI (cross platform)
[,console]
----
$ "`\which apt-get || \which dnf || \which yum || \which brew`" install python # <.>
$ gem install pygments.rb # <.>
----
<.> Install Python using your package manager
<.> Install the pygments.rb gem
== Activate Pygments
Once you've installed these libraries, assign `pygments` to the `source-highlighter` attribute in your document's header.
[,asciidoc]
----
:source-highlighter: pygments
----
== Pygments attributes
You can further customize the source block output with additional Pygments attributes.
pygments-style::
Sets the name of the color theme Pygments uses.
To see the list of available style names, see <<listing-pygments-style-names>>.
Default: `pastie`.
pygments-css::
Controls what method is used for applying CSS to the tokens.
Can be `class` (CSS classes) or `style` (inline styles).
See the xref:html-backend:source-highlighting-stylesheets.adoc#pygments[Pygments stylesheet section] to learn more about how the value `class` is handled.
Default: `class`.
pygments-linenums-mode::
Controls how line numbers are arranged when line numbers are enabled on the source block.
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`.
.Customizing a source block with Pygments attributes
[source,asciidoc]
....
:source-highlighter: pygments
:pygments-style: manni
:pygments-linenums-mode: inline
[%linenums,ruby]
----
ORDERED_LIST_KEYWORDS = {
'loweralpha' => 'a',
'lowerroman' => 'i',
'upperalpha' => 'A',
'upperroman' => 'I'
#'lowergreek' => 'a'
#'arabic' => '1'
#'decimal' => '1'
}
----
....
////
.Result: Source block using inline line numbers and the manni theme
====
image::custom-pygments.png[Line numbers and a custom Pygments theme for a source block.]
====
////
[#listing-pygments-style-names]
=== Available Pygments style names
To list the available Pygments styles, run the following command in a terminal:
$ $(dirname $(gem which pygments.rb))/../vendor/pygments-main/pygmentize -L styles
The pygments.rb gem uses a bundled version of Pygments (often ahead of the latest release).
This command ensures that you are invoking the `pygmentize` command from the Pygments used by that gem.
[#pygments-timeout]
== Pygments timeout (pygments.rb 1.x only)
If you're using pygments.rb 1.x, you may need to adjust the timeout.
This configuration step is not necessary if you're using pygments.rb 2.x with Python 3.
Since Pygments is an external program, the call to that command in pygments.rb 1.x is managed by a timeout to safeguard against a hanging process.
By default, this timeout is 8 seconds.
If you discover that the call is failing to complete within this timeout period, you can increase the timeout (in seconds) by setting the `MENTOS_TIMEOUT` environment variable.
export MENTOS_TIMEOUT=30
Now the call to Pygments (via pygments.rb 1.x) will be allocated up to 30 seconds to complete.
== Use a custom Pygments installation
If you already have Pygments installed on your system, you want to use your own fork, or you want to customize how Pygments is configured, you can get Asciidoctor to use a custom version of Pygments instead of the one bundled with the pygments.rb gem.
First, install your own version of Pygments.
You can do this, for instance, by cloning the upstream Pygments repository:
$ hg clone https://bitbucket.org/birkenfeld/pygments-main pygments
Find the directory that contains the file [.path]_pygmentize_ or the [.path]_Makefile_.
That's your Pygments installation path.
Make note of it.
Next, create a script to run _before_ invoking Asciidoctor for the first time.
Let's call it [.path]_pygments_init.rb_.
Populate the script with the following content:
.pygments_init.rb
[,ruby]
----
require 'pygments'
# use a custom Pygments installation (directory that contains pygmentize)
Pygments.start '/path/to/pygments'
# example of registering a missing or additional lexer
#Pygments::Lexer.create name: 'Turtle', aliases: ['turtle'],
# filenames: ['*.ttl'], mimetypes: ['text/turtle', 'application/x-turtle']
----
TIP: You could enhance this script to read the Pygments installation path from an environment variable (or configuration file).
Now just require this script before your invoke Asciidoctor the first time.
When using the `asciidoctor` command, pass the script using the `-r` flag:
$ asciidoctor -r ./pygments_init.rb document.adoc
When using the Asciidoctor API, require the script using `require` or `require_relative`:
[,ruby]
----
require 'asciidoctor'
require_relative './pygments_init.rb'
Asciidoctor.convert_file 'document.adoc', safe: :safe
----
Now Asciidoctor is using your custom installation of Pygments instead of the one bundled with the pygments.rb gem.
Alternately, you can xref:custom.adoc#extend[extend the adapter for Pygments] and put this logic inside that adapter.
|
