代码高亮会应用于被赋予`source`块样式（无论是显式的还是隐式的）的文本上，以及一个源语言。源语言要么在块上定义，要么继承自`source-language`文档属性。

源代码高亮属性

源代码高亮在默认情况下是不开启的。要启用源代码高亮，您必须在文档头部使用属性条目设置`source-highlighter`属性。

= 文档标题
:source-highlighter: <value>

例如，这里是如何使用Rouge来启用语法高亮的方法：

= 文档标题
:source-highlighter: rouge

您也可以使用CLI或API来声明这个属性。

可用的源代码高亮显示器

'''内置的源代码高亮值及其支持的工具链 列出了 source-highlighter 属性的认可值以及支持使用语法高亮库的工具链。'''

Table 1. 内置的源代码高亮值及其支持的工具链
图书馆 价值 工具链

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，您必须在系统上安装相应的库。 请参阅 asciidoctor:syntax-highlighting:rouge.html、asciidoctor:syntax-highlighting:coderay.html 或 asciidoctor:syntax-highlighting:pygments.html 以获取安装说明。

如果您正在使用客户端库asciidoctor:syntax-highlighting:highlightjs.html，则无需安装额外的库。生成的HTML将从CDN、自定义URL或文件路径加载所需的源文件。

源代码高亮器与语法高亮器

你可能会注意到，source-highlighter 属性使用了“source highlighter”这个术语，而执行高亮的库则被称作“syntax highlighter”。它们之间有什么区别？

  • 通常接受的用于语法（又称代码）高亮的术语是“语法高亮器”。

  • 语法高亮器被应用于AsciiDoc中的源代码块，这就是为什么我们称之为“源代码高亮器”。

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

应用源代码高亮显示

要给源代码块应用高亮显示，您必须指定一种源代码语言。如果该块是文字块或段落，您还必须指定`source`样式。

AsciiDoc 语言并未规定有效源语言值的列表。相反，可用的源语言值是由语法高亮库定义的。

Tip
 您可以在Rouge文档的 https://github.com/rouge-ruby/rouge/blob/master/docs/Languages.md 链接中找到Rouge支持的可用语言列表。您可以通过运行 pygmentize -L formatters 命令来打印Pygments支持的可用语言列表。highlight.js支持的可用语言取决于您使用的highlight.js的哪个软件包。

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

带有ID和源代码高亮显示的源代码块
Unresolved directive in source-highlighter.adoc - include::example$source.adoc[tag=src-base-co]

  1. 由于指定了源语言，所以隐含了块风格`source`。

  2. 可以通过使用`id`的缩写语法(#)，将其附加到样式后面来为区块添加一个可选的ID。

  3. 将源语言指定到第二个位置。

  4. 隐式源代码块使用列表结构容器。

带有ID和源代码高亮显示的源代码块的结果如下所示。

Unresolved directive in source-highlighter.adoc - include::example$source.adoc[tag=src-base-co-res]

源段落
Unresolved directive in source-highlighter.adoc - include::example$source.adoc[tag=src-para-co]

  1. 将属性列表直接放置在段落上方。在这种情况下，始终需要`source`样式。

  2. 遇到空行时，源代码块结束。

结果如下所示 源段落。

Unresolved directive in source-highlighter.adoc - include::example$source.adoc[tag=src-para]

Shell 与控制台

源语言中的 shell 和 console 经常会混淆。语言 shell 旨在用于 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`选项来启用行号。

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

linenums` 选项可以作为常规块选项命名为 linenums 指定，或者作为块上的第三个位置属性指定。位置属性的值并不重要，尽管习惯上使用 linenums。

使用`linenums`选项启用行号。
Unresolved directive in source-highlighter.adoc - include::example$source.adoc[tag=linenums-option]
使用第三个位置属性启用行号。
Unresolved directive in source-highlighter.adoc - include::example$source.adoc[tag=linenums-posattr]

禁用源代码高亮

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

源语言属性

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

设置源语言属性
Unresolved directive in source-highlighter.adoc - include::example$source.adoc[tag=src-lang]

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

你可以通过在块级别直接指定源语言来覆盖全局源语言设置。

覆盖源语言属性
Unresolved directive in source-highlighter.adoc - include::example$source.adoc[tag=override]