Asciidoctor 升级说明

Antora 3 使用 Asciidoctor.js 2.2.x（Asciidoctor 2.0.x）代替 Asciidoctor.js 1.5.9（Asciidoctor 1.5.8）来处理内容文件。Asciidoctor 2 引入了许多新功能和一些对现有功能的实质性更改。

Asciidoctor 2 特性变更

以下各节描述了现有Asciidoctor功能的新行为，并建议您在从Antora 2升级到Antora 3之前应采取的操作。

非AsciiDoc文件和include指令

功能 新行为 操作

使用include指令包含非AsciiDoc文件，特别是在verbatim（列表、文字或源代码）块内部

使用include指令包含非AsciiDoc文件时，尾随空格字符不会被移除，制表符不会被展开，换行符不会被规范化。这可能会改变输出的显示方式。

  • 如果发布时非AsciiDoc文件使用了制表符和空格混合或不一致的换行符，请更新这些文件，以便内容显示如预期。

  • 如果设置了indent属性但未按预期工作，请替换非AsciiDoc文件中的任何制表符。

  • 从非AsciiDoc文件中移除尾随空格字符，特别是在文件内容中使用callouts或应用indent属性时。

在include指令或插入的verbatim块上设置indent属性的非AsciiDoc文件

由于非AsciiDoc内容中不会展开制表符，因此indent属性可能不会按预期工作。

使用include指令将callouts包含到verbatim块中的非AsciiDoc文件

由于尾随空格字符不会被移除，因此可能不再检测到callout编号。

列表和源代码块

功能 新行为 操作

未明确指定样式的分隔列表块，当设置了source-language时

未明确指定样式的分隔列表块（----），如果文档、组件描述符或playbook中设置了source-language，则会自动升级为源代码块，这可能导致不希望的语法高亮显示。

如果未设置source-language，则无需采取任何操作。

如果设置了source-language，请执行以下操作：

  • 将样式listing分配给任何未设置样式的分隔列表块，以防止其升级为源代码块。您也可以将它们更改为分隔文字块（....）。

  • （可选）从应升级为源代码块的分隔列表块中删除样式source。样式source会自动应用。

查看 源代码块 以了解更多信息。

未分配语言的源代码块

当块上未设置语言或通过source-language设置语言时，语言none会自动分配给源代码块（source）。

该块的样式与其他源代码块相同，但不会应用语法高亮显示。

如果这种行为是可以接受的，则无需更改。否则，请执行以下操作之一：

  • 为源代码块分配适当的语言，或

  • 删除source样式，并替换为listing样式，或

  • 删除source样式，并将块更改为分隔文字块（....）。

查看 源代码块 以了解更多信息。

表格

功能 新行为 操作

a 和 l 列修饰符

当在表格的列中应用AsciiDoc（a）和文字（l）修饰符时，现在正常的替换和默认标题格式将正确应用于隐式标题行中的单元格。

更新使用a 和 l 修饰符的表格，以便显示您期望的输出。

v 修饰符

verse修饰符（v）已弃用。分配了v修饰符的列或单元格现在被视为常规表格单元格。

如果将单元格内容显示为常规内容是可以接受的，则无需采取任何操作。

table-topbot CSS类

CSS类table-ends取代了已弃用的table-topbot CSS类。

如果在您的UI中自定义了table-topbot的样式，请将类名更新为table-ends并构建新的UI捆绑版本。

表格列宽度

计算表格列宽度时使用的四舍五入方式略有变化。

由于更改对站点访问者不应该明显，因此无需采取任何操作。

列表

功能 新行为 操作

描述列表分隔符（::）

描述列表分隔符，即双冒号（::）如果裸露或位于行首，不再被误认为是描述列表项。

删除先前被误认为是描述列表分隔符的双冒号（::）周围的转义语法。

节和块标题

功能 新行为 操作

节和块标题替换顺序

现在应用于节和块标题的替换顺序与正常替换顺序相匹配。这可能会影响使用属性引用的节和块标题。

检查包含属性引用的节和块标题以查找错误。

无效和未解析的引用和属性

特性 新行为 操作

内容中的“未解析包含指令”消息

消息已更改为“未解析指令”。

除非您使用一个后处理器来查找输出中的此消息，否则不需要采取任何操作。

page 类

xrefs 的类 page 已替换为 xref <family>，其中 <family> 是 xref 指向的资源家族的名称（例如，xref page）。

如果您的 CSS 或后处理器尝试匹配此类，则需要更新选择器。现在可以使用 CSS 选择器 a.xref 在页面中找到所有 xref 链接。

page unresolved 类

当 xref 的目标无效或无法解析时，类 page unresolved 已替换为 xref unresolved。

如果您的 CSS 或后处理器尝试匹配此类，则需要更新选择器。

内联锚点的引用验证

如果 Asciidoctor 无法找到内联锚点的引用，即使存在，它也会记录一条关于可能无效引用的信息。

使用双方括号封闭定义内联锚点，并仅将其放置在 Asciidoctor 扫描其位置的地方。有效位置包括段落文本的任何位置，或者在列表项或表格单元格的开头。您也可以忽略这些消息或不启用 info 日志级别。

attribute-missing

现在在处理包含指令和块宏时会遵守 attribute-missing 设置。这可能会显示新的缺失包含文件和引用。

检查日志消息以获取新的警告并修复任何报告的错误。

脚注

特性 新行为 操作

脚注宏

已弃用 footnoteref 宏，并且 footnote 宏的结构已更改以与其他 AsciiDoc 宏保持一致。以前，脚注目标放置在宏的方括号内。现在，目标直接放在冒号后面（footnote:<target>[<optional attributes>]）。

将 footnoteref 更改为 footnote 并将脚注目标移动到正确位置。

脚注中的锚点和 xrefs

在处理脚注宏之前，会处理锚点和 xref 宏，以防止脚注宏过早终止。

从脚注宏属性列表中使用的锚点和 xref 宏中删除转义语法，例如反斜杠（\）。

引用块

特性 新行为 操作

"" 引用块分隔符

2 字符 "" 引用块分隔符已弃用。

删除已弃用的 "" 分隔符，并用四个下划线（____）块分隔符或引用段落语法替换。

编码

特性 新行为 操作

对电子邮件地址中的字符进行编码以符合 RFC-3986

以前，电子邮件地址中的空格被编码为 %20。现在，电子邮件地址中的空格被编码为加号（+），以符合 RFC-3986。

此更改不会影响电子邮件链接的行为。

语义化版本和Asciidoctor 2

从Asciidoctor 2.0.0开始，Asciidoctor和Asciidoctor.js切换到语义化版本。这使得Antora可以在安装过程中自动选择Asciidoctor.js的最新补丁版本，而无需发布新的Antora版本。

准备从Antora 2升级到Antora 3.1？请参阅升级Antora获取说明。