源码高亮

源代码高亮应用于被分配了source块样式（显式或隐式）和源代码语言的文本。源代码语言定义在块上或从source-language文档属性继承。

source-highlighter 属性

源代码高亮默认未启用。要启用源代码高亮，您必须在文档头部使用属性条目设置source-highlighter属性。

= Document Title
:source-highlighter: <value>

例如，以下是如何使用 Rouge 启用语法高亮

= Document Title
:source-highlighter: rouge

您也可以使用 CLI 或 API 声明此属性。

可用的源代码高亮器

表 1 列出了source-highlighter属性的识别值以及支持使用语法高亮库的工具链。

表 1. 内置 source-highlighter 值和支持的工具链
库	值	工具链
CodeRay	`coderay`	Asciidoctor, AsciidoctorJ, Asciidoctor PDF
highlight.js	`highlight.js`	Asciidoctor, AsciidoctorJ, Asciidoctor.js
Pygments	`pygments`	Asciidoctor, Asciidoctor PDF
Rouge	`rouge`	Asciidoctor, AsciidoctorJ, Asciidoctor PDF

要使用 Rouge、CodeRay 或 Pygments，您必须在系统上安装相应的库。请参阅 Rouge、CodeRay 或 Pygments 以获取安装说明。

如果您使用的是客户端库 Highlight.js，则无需安装其他库。生成的 HTML 将从 CDN、自定义 URL 或文件路径加载所需的源文件。

源代码高亮器 vs. 语法高亮器

您可能会注意到source-highlighter属性使用了“source highlighter”（源代码高亮器）一词，而执行高亮操作的库则被称为“syntax highlighter”（语法高亮器）。有什么区别？

对于语法（又称代码）高亮器，普遍接受的术语是“syntax highlighter”。
语法高亮器应用于 AsciiDoc 中的源代码块，因此我们称之为“source highlighter”。

换句话说，source-highlighter属性的意思是“使用此语法高亮器为源代码块着色”。

应用源代码高亮

要对源代码块应用高亮，您必须指定源代码语言。如果该块是字面量块或段落，您还必须指定source样式。

AsciiDoc 语言不指定有效的源代码语言值列表。相反，可用的源代码语言值由语法高亮库定义。

您可以在 Rouge 文档中找到 Rouge 支持的可用语言列表。您可以通过运行pygmentize -L formatters来打印 Pygments 支持的可用语言列表。highlight.js 支持的可用语言取决于您使用的 highlight.js 捆绑包。

通常，源代码语言值是语言的正确名称（小写）（例如，ruby、java）。大多数语法高亮器也接受使用源文件名扩展名（例如，js、rb），尽管保持一致很重要。如果语法高亮器不识别或不支持源代码语言，该块将不会被高亮。

示例 1. 带 ID 和源代码高亮的源代码块

[#hello,ruby] (1) (2) (3)
---- (4)
require 'sinatra'

get '/hi' do
  "Hello World!"
end
----

1	由于指定了源代码语言，因此`source`块样式是隐式的。
2	可以通过使用`id`的简写语法（`#`）将其添加到样式中来为块添加可选的 ID。
3	将源代码语言分配给第二个位置。
4	隐式源代码块使用列表结构容器。

示例 1 的结果显示在下面。

require 'sinatra'

get '/hi' do
  "Hello World!"
end

示例 2. 源代码段落

[source,xml] (1)
<meta name="viewport"
  content="width=device-width, initial-scale=1.0">
(2)
This is normal content.

1	将属性列表放在段落的正上方。在这种情况下，始终需要`source`样式。
2	遇到空行后，源代码块结束。

示例 2 的结果显示在下面。

<meta name="viewport"
  content="width=device-width, initial-scale=1.0">

这是正常内容。

shell vs console

shell 和 console 的源代码语言经常被混淆。shell语言用于 shell 脚本的内容，通常由通用的 shebang 指示。如果 shell 脚本是为特定 shell 编写的，您可能会改用该语言（例如，bash或zsh）。console语言用于表示输入到控制台（即终端应用程序）的文本。

以下是一个何时使用shell的示例

[,shell]
----
#!/bin/sh

fail () {
    echo
    echo "$*"
    echo
    exit 1
} >&2

JAVACMD=java
which java >/dev/null 2>&1 || fail "ERROR: no 'java' command could be found in your PATH.

exec "$JAVACMD" "$@"
----

以下是一个何时使用console的示例

[source,console]
$ asciidoctor -v

通常，语法高亮器会解析每行开头的提示符（例如，$），然后使用 shell 语言处理其余文本。

通常，基本的控制台命令使用字面量段落表示，因为在这种情况下，从语法高亮中获得的收益不大。

启用行号

如果源代码高亮器支持此功能，您可以通过在块上设置linenums选项来为源代码块启用行号。

行号由语法高亮器添加，而不是 AsciiDoc 转换器。因此，要在源代码块上获取行号，您必须设置source-highlighter属性，并且其引用的库必须支持行号。使用 Asciidoctor 时，唯一不支持行号的语法高亮器是 highlight.js。

linenums选项可以作为名为linenums的普通块选项指定，也可以作为块上的第三个位置属性指定。位置属性的值无关紧要，但通常使用linenums。

示例 3. 使用linenums选项启用行号

[%linenums,ruby]
----
puts 1
puts 2
puts 3
----

示例 4. 使用第三个位置属性启用行号

[,ruby,linenums]
----
puts 1
puts 2
puts 3
----

禁用源代码高亮

要禁用给定源代码块的源代码高亮，请将语言指定为text或删除source样式。

source-language 属性

如果您的绝大多数源代码块使用相同的源代码语言，您可以在文档头部设置source-language属性并为其分配一个语言。设置source-language文档属性会隐式地将列表块提升为源代码块。

示例 5. 设置 source-language 属性

= Document Title
:source-highlighter: pygments
:source-language: java

----
public void setAttributes(Attributes attributes) {
    this.options.put(ATTRIBUTES, attributes.map());
}
----

请注意，在这种情况下，不必在块上指定source样式或源代码语言。要制作一个列表块，您必须在块上设置listing样式。

您可以通过在块上直接指定源代码语言来覆盖全局源代码语言。

示例 6. 覆盖 source-language 属性

= Document Title
:source-highlighter: pygments
:source-language: java

[,ruby]
require 'sinatra'