Pygments 是一个受欢迎的语法高亮工具，它支持广泛的https://pygments.org/languages/[编程和模板语言^]。

安装Pygments

为了在Asciidoctor中使用Pygments，你需要[url-python][Python]和https://rubygems.org/gems/pygments.rb[pygments.rb gem^]。pygments.rb gem管理对Pygments的调用，Pygments是一个使用Python运行的外部程序。

Tip
 你不需要单独安装Pygments。它已经包含在pygments.rb gem中了。
Important
 您必须安装了Python才能使用pygments.rb。

您使用的pygments.rb版本所需的Python版本取决于您正在使用的pygments.rb版本：

  • pygments.rb 1.x 需要 Python 2。请检查你的 PATH 环境变量中是否有 python2（Linux）、python（macOS）或者 py -2（Windows）可执行文件。（在 macOS 上，通过运行 python -V 命令来验证 python 可执行文件是否使用的是 Python 2）。

  • pygments.rb 2.x 需要 Python 3。请检查你的 PATH 环境变量中是否有 python3（Linux/macOS）或 py -3（Windows）可执行文件。

通过CLI（跨平台）安装Python和pygments.rb宝石
$ "`\which apt-get || \which dnf || \which yum || \which brew`" install python # (1)
$ gem install pygments.rb # (2)

  1. 使用你的包管理器安装Python

  2. 安装pygments.rb宝石

激活Pygments

安装这些库之后，在文档头部为`source-highlighter`属性指定`pygments`。

:source-highlighter: pygments

Pygments属性

您可以通过额外的 Pygments 属性来进一步自定义源代码块的输出。

pygments风格

设置Pygments使用的颜色主题名称。要查看可用样式名称的列表，请参见可用的 Pygments 风格名称。默认值：pastie。

Pygments样式表

控制应用CSS到标记上的方法是什么。可以是 class（CSS类）或 style（内联样式）。查看Pygments样式表部分来了解更多关于如何处理值 class 的信息。默认值：class。

pygments-linenums-mode

控制启用源代码块行号时行号的排列方式。可以是 table 或者 inline。如果预格式化块启用了行包裹（即 prewrap），并且你希望在源代码块上使用行号，必须将此属性的值设置为 inline，以确保号码正确地与其目标行对齐。默认值：table。

使用Pygments属性自定义源代码块
: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'
}
----

可用的 Pygments 风格名称

要列出可用的Pygments样式，请在终端运行以下命令：

$ $(dirname $(gem which pygments.rb))/../vendor/pygments-main/pygmentize -L styles

pygments.rb 宝石使用了打包好的 Pygments 版本（通常领先于最新发布的版本）。这条命令确保你调用的 pygmentize 命令是来自那个宝石使用的 Pygments。

Pygments超时（仅限pygments.rb 1.x版本）

如果您正在使用pygments.rb 1.x，您可能需要调整超时时间。如果您使用的是配合Python 3的pygments.rb 2.x，则无需进行此配置步骤。

由于 Pygments 是一个外部程序，所以在 pygments.rb 1.x 中对该命令的调用是通过一个超时来管理的，以防止进程挂起。默认情况下，这个超时时间是8秒。如果你发现调用在这个超时期限内无法完成，你可以通过设置 MENTOS_TIMEOUT 环境变量来增加超时时间（以秒为单位）。

export MENTOS_TIMEOUT=30

现在通过pygments.rb 1.x版本对Pygments的调用将被分配最多30秒的时间来完成。

使用自定义的Pygments安装

如果你的系统上已经安装了Pygments，你想使用自己的分支，或者你想自定义Pygments的配置方式，你可以让Asciidoctor使用自定义版本的Pygments，而不是pygments.rb宝石捆绑的那个版本。

首先，安装你自己版本的Pygments。你可以通过克隆上游的Pygments仓库来做到这一点，例如：

$ hg clone https://bitbucket.org/birkenfeld/pygments-main pygments

寻找包含文件[.path]_pygmentize_或[.path]_Makefile_的目录。那是你的Pygments安装路径。记下它。

接下来，创建一个脚本，在首次调用Asciidoctor之前运行。我们将其命名为[.path]pygments_init.rb。用以下内容填充脚本：

pygments_init.rb
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
 你可以通过读取环境变量（或配置文件）中的 Pygments 安装路径来增强这个脚本的功能。

现在只需在第一次调用Asciidoctor之前引入这个脚本。当使用`asciidoctor`命令时，使用`-r`标志传递脚本：

$ asciidoctor -r ./pygments_init.rb document.adoc

当使用Asciidoctor API时，使用`require`或`require_relative`来加载脚本：

require 'asciidoctor'
require_relative './pygments_init.rb'

Asciidoctor.convert_file 'document.adoc', safe: :safe

现在Asciidoctor使用的是你的自定义安装版本的Pygments，而不是pygments.rb宝石包中捆绑的版本。

另外，您可以扩展Pygments的适配器并将这个逻辑放入该适配器内。