Pygments

Pygments 是一个流行的语法高亮器，支持广泛的 编程和模板语言。

安装 Pygments

要将 Pygments 与 Asciidoctor 一起使用，您需要 Python 和 pygments.rb gem。pygments.rb gem 管理对 Pygments 的调用，Pygments 是一个通过 Python 运行的外部程序。

您无需自行安装 Pygments。它已与 pygments.rb gem 一起捆绑提供。
您必须安装 Python 才能使用 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) 可执行文件。

示例 1. 通过 CLI (跨平台) 安装 Python 和 pygments.rb gem
$ "`\which apt-get || \which dnf || \which yum || \which brew`" install python (1)
$ gem install pygments.rb (2)
1 使用您的包管理器安装 Python
2 安装 pygments.rb gem

激活 Pygments

安装完这些库后，在文档的头部将 pygments 分配给 source-highlighter 属性。

:source-highlighter: pygments

Pygments 属性

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

pygments-style

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

pygments-css

控制用于将 CSS 应用于标记的方法。可以是 class (CSS 类) 或 style (内联样式)。请参阅 Pygments 样式表部分，了解更多关于 class 值如何处理的信息。默认值：class。

pygments-linenums-mode

控制在源代码块中启用行号时行号的排列方式。可以是 table 或 inline。如果预格式化块 (即 prewrap) 中启用了行换行，并且您想在源代码块中使用行号，则必须将此属性的值设置为 inline，以便数字能与目标行正确对齐。默认值：table。

示例 2. 使用 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 gem 使用 Pygments 的捆绑版本（通常比最新版本更新）。此命令可确保您调用的是 gem 使用的 pygmentize 命令。

Pygments 超时 (仅限 pygments.rb 1.x)

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

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

export MENTOS_TIMEOUT=30

现在，调用 Pygments（通过 pygments.rb 1.x）将有最多 30 秒的时间来完成。

使用自定义 Pygments 安装

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

首先，安装您自己的 Pygments 版本。例如，您可以克隆上游 Pygments 仓库来完成此操作

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

找到包含 pygmentize 文件或 Makefile 的目录。那就是您的 Pygments 安装路径。请记下它。

接下来，创建一个脚本，在首次调用 Asciidoctor *之前* 运行。我们称之为 pygments_init.rb。用以下内容填充该脚本

示例 3. 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']
您可以增强此脚本，使其从环境变量（或配置文件）读取 Pygments 安装路径。

现在，在首次调用 Asciidoctor 之前，只需 require 此脚本。使用 asciidoctor 命令时，通过 -r 标志传递脚本

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

使用 Asciidoctor API 时，请使用 require 或 require_relative 来 require 此脚本

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

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

现在 Asciidoctor 正在使用您的自定义 Pygments 安装，而不是 pygments.rb gem 捆绑的版本。

或者，您可以 扩展 Pygments 的适配器并将此逻辑放入该适配器中。