Pygments is a widely used syntax highlighter that supports a broad range of programming and template languages. Asciidoctor integrates with Pygments through the pygments.rb gem, which manages calls to the Pygments Python library.
You do not need to install Pygments separately — it is bundled with the pygments.rb gem. However, you must have Python installed on your system, because pygments.rb invokes Pygments as an external process.
Prerequisites
The version of Python required depends on which release of pygments.rb you use:
- pygments.rb 1.x requires Python 2. Verify you have a
python2 (Linux), python (macOS), or py -2 (Windows) executable on your PATH.
- pygments.rb 2.x requires Python 3. Verify you have a
python3 (Linux/macOS) or py -3 (Windows) executable on your PATH.
Installation
gem
Gemfile
apt-get + gem
Install Python using your system package manager, then install the gem: Add to your Gemfile:Then install: sudo apt-get install python3
gem install pygments.rb
Enabling Pygments
Once installed, set the source-highlighter attribute to pygments:
:source-highlighter: pygments
asciidoctor -a source-highlighter=pygments document.adoc
Asciidoctor.convert_file 'document.adoc',
safe: :safe,
attributes: { 'source-highlighter' => 'pygments' }
Pygments attributes
pygments-style
Sets the color theme. Default is default.
:source-highlighter: pygments
:pygments-style: monokai
$(dirname $(gem which pygments.rb))/../vendor/pygments-main/pygmentize -L styles
pygmentize from the Pygments version bundled with the gem, ensuring the list matches what Asciidoctor will use.
pygments-css
Controls how CSS is applied to highlighted tokens. Accepts class (default) or style.
| Value | Behavior |
|---|
class | Applies CSS classes; requires a linked or embedded Pygments stylesheet |
style | Applies inline styles directly on each token span |
class mode, Asciidoctor generates and embeds a Pygments stylesheet (or links to it when linkcss is set). In style mode, no external stylesheet is needed.
:source-highlighter: pygments
:pygments-css: style
pygments-linenums-mode
Controls how line numbers are rendered when line numbering is enabled. Accepts table (default) or inline.
If line wrapping is enabled on preformatted blocks (the prewrap attribute is set), use pygments-linenums-mode: inline so that line numbers remain aligned with their corresponding lines.
:source-highlighter: pygments
:pygments-linenums-mode: inline
Source block examples
Basic source block
:source-highlighter: pygments
[,python]
----
def greet(name):
print(f"Hello, {name}!")
greet("Pygments")
----
Custom theme with inline line numbers
:source-highlighter: pygments
:pygments-style: manni
:pygments-linenums-mode: inline
[%linenums,ruby]
----
ORDERED_LIST_KEYWORDS = {
'loweralpha' => 'a',
'lowerroman' => 'i',
'upperalpha' => 'A',
'upperroman' => 'I'
}
----
Highlighting specific lines
:source-highlighter: pygments
[,java,highlight=3..5]
----
public class Greeter {
public static void main(String[] args) {
System.out.println("Hello, Pygments!");
}
}
----
Adjusting the timeout (pygments.rb 1.x only)
Pygments runs as an external process managed by a timeout in pygments.rb 1.x (not needed with 2.x). The default timeout is 8 seconds. If Pygments is taking longer than that to complete, increase the timeout by setting the MENTOS_TIMEOUT environment variable:
export MENTOS_TIMEOUT=30
asciidoctor -a source-highlighter=pygments document.adoc
Using a custom Pygments installation
If you want to use your own Pygments installation rather than the one bundled with the gem, create an initialization script and require it before Asciidoctor runs:
# pygments_init.rb
require 'pygments'
# Point to your custom Pygments installation
Pygments.start '/path/to/pygments'
# Optionally register a custom or missing lexer
# Pygments::Lexer.create name: 'Turtle', aliases: ['turtle'],
# filenames: ['*.ttl'], mimetypes: ['text/turtle', 'application/x-turtle']
asciidoctor -r ./pygments_init.rb -a source-highlighter=pygments document.adoc
require 'asciidoctor'
require_relative './pygments_init.rb'
Asciidoctor.convert_file 'document.adoc', safe: :safe
