Source Blocks :: Antora Docs

什么是源代码块？

一个AsciiDoc源代码块，简称为源代码块，显示了以给定的编程、数据、配置或标记语言编写的内容片段。当在站点中呈现时，源代码块的内容将使用语法高亮显示。通过将属性 source 和一个有效的源语言名称分配给一个块来创建源代码块。

source 和 source 语言属性

样式 source 是一个位置元素属性。它通过属性列表中的第一个位置分配给一个块。

示例 1. 直接使用属性列表分配源和源语言

[source,name-of-language] (1)

1	一个属性列表，其中 `source` 分配给第一个位置，第二个位置分配一个源语言名称，如 `bash`、`cpp` 等。

源语言的名称分配给属性列表中的第二个位置，或使用 source-language 文档属性。源语言是块内容所写的编程、数据、配置或标记语言的名称。

指定源语言有两个目的。首先，它向站点访问者传达了需要哪种语言运行时或数据格式读取器来解释块中显示的代码。其次，它允许语法高亮显示器正确地为源内容着色，例如强调语言类型和关键字。最后，通过为块分配语言，您可以同时隐式地为块分配 source。如在示例 2 中所示，通过将有效的源语言名称分配给属性列表的第二个位置，您隐式地将 source 分配给第一个位置。

示例 2. 将源语言分配给属性列表的第二个位置

[,name-of-language] (1)

1	要将源语言分配给属性列表的第二个位置，而不直接将 `source` 分配给第一个位置，请在开方括号后立即输入逗号 (`,`)，然后输入源语言的名称。

语言名称以小写字母书写，必须是语法高亮显示器 Antora 使用的语言才能正确着色内容。如果大多数源代码块使用相同的语言，您可以将语言名称分配给 source-language 文档属性。

当指定了 source 但未在源代码块的属性列表中或通过 source-language 文档属性指定语言时，Antora 在运行时应用语言 none。该块的样式与其他源代码块相同，但不会对其内容应用语法高亮显示。

创建一个源代码块

源块通常是从分隔列表块、字面块以及段落创建的。在以下情况下，一个块会变成源块：

在块的属性列表中将语言名称分配给第二个位置，这会隐式地将source分配给属性列表的第一个位置
直接将source分配给块的属性列表的第一个位置，并将语言名称分配给第二个位置或source-language文档属性
设置文档属性source-language，这会自动将所有未分配其他样式的分隔列表块提升为源块

当使用任何这些方法将source分配给一个块时，该块的内容将根据分配的源语言由语法高亮器着色。

隐式分配源

因为使用属性列表的第一个位置将source分配给一个块，您可以通过在开括号后直接输入逗号（,），然后输入源语言的名称来隐式分配它。逗号是必需的，否则语言将被分配给属性列表的第一个位置。示例 3展示了将source属性隐式应用于列表块。

示例 3. 隐式应用源到列表块

[,语言名称] (1)
--(2)
源块的内容 (3)
  源块的内容

源块的内容
--(4)

1	在属性列表的开方括号（`[`）后，输入逗号（`,`），然后输入块内容所写的源语言名称。完成属性列表，然后选择`Enter`以进入下一行。
2	在属性列表下方的新行中，输入列表块的开分隔符（`----`），然后选择`Enter`以进入下一行。
3	在开分隔符下方的行中插入您的代码片段。
4	在新行中，输入列表块的闭分隔符（`----`）。

source来创建源块。示例 4展示了将 source属性隐式应用于段落。

示例 4. 将源样式应用于段落

一个常规段落。

[,语言名称] (1)
源块的内容 (2)

一个常规段落。

1	在属性列表的开方括号（`[`）后，输入逗号（`,`），然后输入块内容所写的源语言名称。完成属性列表，然后选择`Enter`以进入下一行。
2	在属性列表下方的新行中，连续输入一个或多个行上的块内容。

示例 5中， source被隐式分配， haskell被分配为语言。

示例 5. 将源和语言 haskell 分配给一个块

[,haskell]
----
main :: IO ()
main = putStrLn "Hello, World!"
----

示例 6展示了在站点中显示源块时的样式高亮效果。

示例 6. 应用语法高亮的渲染源块

main :: IO ()
main = putStrLn "Hello, World!"

示例 6中的内容被着色，当您悬停在块上时，语言名称 HASKELL会出现在其右上角。

直接分配源

在某些情况下，您可能更喜欢直接将source分配给一个块。在块的属性列表中，source在列表中的第一个位置输入，后跟逗号（,），然后是语言的名称，例如clojure，json，xml等。示例7显示了将source属性直接应用于被分隔的文字块（....）。

示例7. 将源样式直接应用于块

[source,name-of-language] (1)
....
源块的内容
  源块的内容

源块的内容
....

1	在属性列表中，将`source`分配给第一个位置，后跟逗号（`,`），然后是块内容所写的源语言的名称。

在示例8中，将source分配给第一个位置，并将sql分配为第二个位置的语言。

示例8. 将源和语言sql分配给一个块

[source,sql]
----
IF EXISTS (SELECT name FROM myobjects WHERE name = 'hello')
----

示例9展示了在站点中显示源块时的外观。

示例9. 应用语法高亮的渲染源块

IF EXISTS (SELECT name FROM myobjects WHERE name = 'hello')

示例9中的内容被着色，当您悬停在块上时，语言名称SQL将出现在块的右上角。

使用适用于源块的元素ID、角色或选项的简写语法，指定source属性并将ID、角色或选项附加到属性。示例10展示了将source属性和元素ID分配给列表块。

示例10. 将元素ID分配给源块

[#element-id,name-of-language] (1) (2)
----
源块的内容
  源块的内容
----

1	在属性列表中，指定元素ID在第一个位置。元素ID直接附加到样式（在本例中为空）中，使用井号符号（`#`）后跟ID名称。由于在第二位置指定了语言，因此`source`样式是隐含的。
2	在元素ID之后直接输入逗号（`,`），然后是块内容所写的源语言的名称。

现在让我们看一个使用分隔文字块创建的源块，并使用简写井号符号（#）分配元素ID的源块。在示例11中，元素ID使用#附加到隐式source样式。行比较语法diff分配给第二位置。

示例11. 将源、元素ID和语言diff分配给一个块

[#temper-change,diff]
....
-   temperDestination(destination)
+   if (destination instanceof Boom) moderateDestination(destination)
  }
  rootLoggerHolder.set(undefined, addFailOnExitHooks(logger, failureLevel))
....

示例12展示了在站点中显示源块时的外观。

示例12. 应用语法高亮的渲染源块

-   temperDestination(destination)
+   if (destination instanceof Boom) moderateDestination(destination)
  }
  rootLoggerHolder.set(undefined, addFailOnExitHooks(logger, failureLevel))

示例12中的内容被着色，当您悬停在块上时，语言名称DIFF将出现在块的右上角。

使用source-language提升列表块

您可以通过设置source-language文档属性在页面、组件版本或站点级别全局定义源语言。当设置source-language时，所有未分配样式的分隔列表块将自动提升为源块。 source-language属性在页面的文档头部、组件版本描述文件或playbook中设置并分配一个值。在示例13中，source-language属性在页面的头部设置，并分配了一个语言的名称。

示例13. 在文档头部设置source-language

= 页面标题
:source-language: 语言名称 (1)

一个段落。

--(2)
源块的内容
--(2)

一个段落。

.... (3)
文字块的内容。
.... (3)

1	在页面头部的新行中，设置内置文档属性`source-language`并将其分配为语言的名称作为值。
2	因为设置了`source-language`，此列表块将自动提升为源块。
3	此文字块仍然是文字块。只有在设置了`source-language`时，未分配样式的列表块才会自动提升为源块。

当设置了source-language时，您可能希望某些列表块不被提升为源块，或者为其中的一些分配不同的语言。示例14展示了如何防止列表块被提升为源块以及如何覆盖source-language属性分配的语言。

示例14. 在选择块上覆盖source-language

= 页面标题
:source-language: java (1)

一个段落。

--(2)
源块的内容
--(2)

一个段落。

[listing] (3)
----
列表块的内容
----

[,yaml] (4)
----
源块的内容
----

1	在页面头部设置文档属性`source-language`并分配值`java`。在此页面上的所有未直接分配样式的列表块将被提升为源块，所有未直接分配源语言的源块将被分配语言`java`。
2	此列表块将自动提升为源块，并分配语言`java`。其内容将被识别为JAVA并相应着色。
3	此列表块分配了样式`listing`，因此不会被提升为源块，其内容不会被着色。
4	此源块直接分配了语言`yaml`。因此，块的内容将被识别为YAML并相应着色。

我们将在下一节中看如何添加着色。

语法高亮

语法高亮是一种通过强调类型、关键字和其他语言结构来着色代码的技术，使其更易于阅读。启用源代码块的语法高亮使用source-highlighter属性。Antora默认在整个站点范围内设置source-highlighter（请参阅站点和配置属性），因此，您无需执行任何操作即可启用此功能。Antora使用highlight.js自动为指定源语言的源代码块添加语法高亮。

语法高亮还需要UI的支持。参考Antora UI捆绑了highlight.js库（包括JavaScript和CSS），并将其添加到每个页面中。当前支持的语言名称列在Antora UI存储库中highlight.bundle.js文件中。

您可以在playbook或组件版本描述符中禁用或覆盖source-highlighter属性。要禁用语法高亮，请在playbook中取消设置source-highlighter属性。

示例 15. 在antora-playbook.yml中禁用source-highlighter属性

asciidoc:
  attributes:
    source-highlighter: ~

目前，使用参考UI时Antora支持的唯一source-highlighter值是highlight.js。如果将值设置为rouge、pygments或coderay，Antora将失败。这是因为这些内置的构建时语法高亮器在Antora环境（特别是Asciidoctor.js）中不可用。

您可以使用其他客户端（也称为浏览器）库，如prettify或prism。但是，要使用它们，您需要修改UI以捆绑并将库添加到每个页面，就像参考UI为highlight.js所做的那样。

将来，将可以注册其他适配器以插入其他语法高亮器。但是，目前Antora中还没有此功能。

了解更多

源代码块的内容通常使用包含指令插入。请参阅包含示例以了解更多。