我们决定在Asciidoctor 1.5.0中重新设计一些AsciiDoc的语法，以使其更加一致、确定性强并易于学习。您可以通过 Asciidoctor 1.5.0发布说明 了解更多关于这些变化的信息。
兼容性对我们非常重要，因此我们添加了兼容模式以及过渡语法，以便从Asciidoctor 0.1.4 迁移到Asciidoctor 1.5.0。本文档解释了如何启用compat(ibility) mode，如果你还没有准备好迁移，以及迁移方案，当你准备好进行切换时。它还会引起你注意一些小的变化，你需要知道这些变化可能会影响你的内容。
兼容模式
如果你现在不能迁移，你可以通过设置文档级别的 compat-mode 属性或使用setext风格（即两行）的文档标题来激活兼容模式。
在兼容模式下，Asciidoctor 1.5.0中大多数偏离传统AsciiDoc语法的_语法修改_将会被还原。这种模式不会禁用只属于Asciidoctor的语法，比如内联图标（例如，icon:fire[]）。
你可以在文档头部定义`compat-mode`属性。
使用命令行标志`-a`：
-a compat-mode
或者通过在API中使用`attributes`选项：
attributes: %w(compat-mode)
另外，你可以通过使用setext风格（即两行）的节标题来启用兼容模式：
Document Title ============== 内容默认在兼容模式下解析。
既然setext风格的标题通常用于较旧的AsciiDoc文档，这个约定允许Asciidoctor兼容这些较旧的文档，而无需唤醒任何沉睡的巨人。 ;)
你可以在文档的任何位置设置`compat-mode`。
:compat-mode: // (1) 有时候你会觉得'自在'。 :compat-mode!: // (2) 有时候你_不会_。
-
在文档的正文中设置兼容模式。
-
在文档的主体中使用感叹号(
!)来取消兼容模式。
为了避免对您的内容造成不必要的干扰，兼容模式将在可预见的未来得到支持。
如果你想开始迁移到现代语法，请继续阅读。
迁移情景
Asciidoctor 1.5.0 对 AsciiDoc 语法所做的更改影响了几种情景：
-
单间距普通文本（不包含任何AsciiDoc语法的文本）
-
不带替换的等宽文本（你希望防止等宽文本被解释）
-
具有替换内容的等宽文本（你希望等宽文本得到解释）
-
智能引号简写
我们首先来考虑在这些例子中使用的遗留语法。
遗留语法
对于上面列出的场景，这是旧版语法（Asciidoctor 0.1.4及更早版本）。
-
+单间距普通文本+ 或 `单间距普通文本`
-
`{asciidoctor-version} holds the version` (attribute is not replaced)
-
传递：[
Asciidoctor版本为2.0.15]（属性被替换） -
通过：[“双引号” 和 ‘单引号’] （引号是弯曲的）
新语法
这里是使用Asciidoctor 1.5.0语法的那三个相同场景。
-
传递：[
单间距正常文本] -
`+{asciidoctor-version} holds the version+` (attribute is not replaced)
-
`Asciidoctor 版本是 {asciidoctor-version}`（属性被替换）
-
通过：["
双引号" 以及单引号]（引号是弯曲的）
|
Warning
|
在旧语法中，为了转义单个智能引号，你需要在开始引号前放置一个反斜杠（例如，\``单引号'`）。在新语法中，你需要在开始引号和结束引号前都使用反斜杠（例如，\'`单引号\`'）。这是因为`'是一个不受限制的（任何地方都可以用的）右侧智能引号替换。 |
在跳转到新语法之前，你需要了解的是，它不能被 Asciidoctor 0.1.4 正确解析。遗憾的是，我们无法控制像 GitHub 这样的服务何时升级 Asciidoctor，因此会有一段时间你需要使用一种两个版本都兼容的语法。那么我们该怎么办？答案是，使用过渡语法。
过渡性语法
过渡语法允许你准确指出文档中最终想要迁移到现代语法的位置，但直到Asciidoctor 0.1.4被淘汰之前还不能迁移。
使用过渡语法，只需在旧语法前添加角色 x-，以表示你希望Asciidoctor 1.5.0使用旧的行为。自然地，Asciidoctor 0.1.4已经理解旧语法，并会简单地忽略这个角色。
-
`monospaced normal text` (No transitional syntax necessary!)
-
[x-]`{asciidoctor-version} holds the version` (attribute is not replaced)
-
[x-]+The Asciidoctor version is {asciidoctor-version}+ (attribute is replaced)
-
"双引号"和’单引号'
|
Note
|
没有专门用于曲线（即智能）引号的转换语法。相反，我们鼓励你直接在文档中输入智能引号。毕竟这是UTF-8编码！ 参考 http://smartquotesforsmartpeople.com [聪明人的智能引号]，https://www.kryogenix.org/days/2013/10/17/smart-quotes-for-smart-ubuntu-people [聪明的Ubuntu（Linux）人士的智能引号] 或 https://fsymbols.com/keyboard/linux/compose/ [Linux键盘快捷键文本符号] 了解如何输入这些字符的指南。 |
让我们来考虑一个例子。
假设你想要在等宽字体文本中添加斜体。如果你希望语法即在Asciidoctor又在AsciiDoc Python中有效，你需要做以下其中一项：
-
启用文档上的`compat-mode`属性，并输入文本如下：
+cat _filename_+
-
不要启用`compat-mode`属性，并按如下方式输入文本:
[x-]+cat _filename_+
你可以将 [x-] 看作是一种本地兼容模式设置。
如果你不担心文档在GitHub这样的服务上的呈现效果，你可以立即开始使用现代语法。
迁移速查表
以下表格提供了一个迁移用的对照表，它将传统的、过渡的和现代的语法并列进行了比较。
| 遗产 | 过渡 | 现代 | 渲染 |
|---|---|---|---|
|
不适用 |
|
斜体文本 |
|
不适用 |
|
|
|
不适用 |
|
|
|
|
|
|
|
|
|
|
|
|
|
“双引号” |
|
|
|
‘单引号’ |
如果你对新语法有任何反馈，请在问题跟踪器中告诉我们 https://github.com/asciidoctor/asciidoctor/issues 。
目录（Table of Contents）定位
对“toc2”属性说再见吧。它已经被弃用了！
从Asciidoctor 1.5.0开始，toc2、`toc-placement`和`toc-position`属性已合并为一个更具表现力的`toc`属性。`toc`属性包揽一切！它现在负责启用目录并指定目录应该显示的位置。
例如，要在左侧边栏激活内容目录，请在文档头部定义`toc`属性，并将其值设置为`left`。
= 文档标题 作者名称 :toc: 左侧
如果你想要手动设置目录的位置，那么你应该将`toc`属性的值设置为`macro`（不是 manual）并使用`toc::[]`宏来指明目录应该出现的位置。
= 文档标题 作者姓名 :toc: 宏 一些内容 toc::[] 更多内容
下面的列表显示了`toc`属性的允许值：
-
当`toc`属性值为空时的默认值(auto)
-
左
-
正确
-
序言
-
巨集
我们建议您从文档或启动脚本中删除所有影响目录（toc）定位的其他属性（例如，toc2、toc-placement 和 toc-position）。
关于目录的更多信息，请参见用户手册中的目录部分。
Font Awesome 升级 (3.2.1 → 4.1)
AsciiDoctor 1.5.0 版本升级了从 Font Awesome 3.2.1 到 4.1 的支持。Font Awesome 4 引入了一种新的图标命名模式。这不会影响 Font Awesome 内置用法的任何内容，例如警告图标，但它会影响内联图标宏。如果你使用内联图标宏，请参考 旧图标和新图标之间的映射，以确保你没有任何图片显示不出来。