期待已久的Asciidoctor 1.5.0 “Bleeding Heart”版本终于发布了！此版本包含了150项修复、改进和增强，以及对AsciiDoc语法的若干改良。我们相信，您将会比以往更加喜爱使用Asciidoctor来进行写作。

Asciidoctor 1.5.0 是 0.1.4 的后续版本。我们调整了版本号以采纳语义化版本控制方案，并表明这个版本已经非常稳定了。

图标：警告[颜色=红色] 请注意！

在你升级到Asciidoctor 1.5.0之前，了解我们引入了一些与旧版本不兼容的AsciiDoc语法变更非常重要。不过别担心！我们也引入了一个兼容模式。

参考https://asciidoctor.org/docs/migration/[迁移指南]了解受影响的语法及如何迁移（或准备迁移）您的内容。通过这些语法更改，我们致力于使AsciiDoc更加一致和易于学习。

里程碑与动力

在Asciidoctor 1.5.0的开发周期中，我们关闭了https://github.com/asciidoctor/asciidoctor/issues?q=milestone%3Av1.5.0[150个问题]。在上一次发布的时候，我们宣布Asciidoctor已经从RubyGems.org达到了50,000次下载。这一次，我们不仅仅是翻倍增长下载量，我们将其_翻了四倍_！在这次发布时，Asciidoctor已经超过了225,000次下载！

我们最自豪的不是下载量。而是awesome people 组成的社区。现在Asciidoctor生态系统中有超过50名贡献者，仅这次发布就收到了这个团队几乎每个人的参与！如果你还没有机会参与Asciidoctor，现在加入的时机从未如此好过。

这里是我们已经达到的里程碑的总结：

  • 在1.5.0版本中关闭了150个问题

  • 共50名贡献者

  • 总下载量225,000次

  • 共计1,800次提交

  • 1500次测试

  • 总共1000个问题（包括拉取请求）

  • 共关闭了800个问题（包括拉取请求）

  • 400个邮件列表主题

  • 2年的开发时间（初始提交于2012年6月1日）

这不会是一个Asciidoctor发布公告，如果我们不讨论处理器的速度。1.5.0版本比之前的版本又快了10%。为了让你了解它现在有多快，以50,000多行的Spring Framework参考指南为例，它可以在使用Ruby 2.1的Asus ZenBook UX301LA上以1.15秒的速度渲染成HTML。

Asciidoctor 现在被更多的开源项目所使用，包括 Groovy、Griffon、GroovyFX、Infinispan、Weld、Hibernate OGM、Spring Data 和 git-scm.com。它也被用来制作 NFJS 杂志。最棒的是，https://github.com/graphitefriction[Sarah] 一直在努力填充 Asciidoctor 自己的https://asciidoctor.org/docs/user-manual[用户手册]，并帮助团队了解如何编写更好的文档。

如果你没有注意到，Asciidoctor项目正在如火如荼地进行。在这个基础上，让我们来看看这个新版本都包含了什么！

版本亮点

图标:烧瓶[] 使用MathJax进行技术处理

如果你在写作中需要使用技术性内容，Asciidoctor可以与[MathJax](TeX / LaTeX(AsciiMath(docs.mathjax.org/en/latest/input/asciimath.html)表达式。

一个排版的LaTeX数学方程
\[x = {-b \pm \sqrt{b^2-4ac} \over 2a}\]

通过简单声明https://asciidoctor.org/docs/user-manual/#stem[stem]属性，您现在也可以用纯文字编写https://asciidoctor.org/docs/user-manual/#inline-stem-content[内联]和https://asciidoctor.org/docs/user-manual/#block-stem-content[块]公式了！

图标：站点地图[] 图表，图表，图表

您可以通过从纯文本中构建的图表向文档添加更多视觉元素。https://github.com/asciidoctor/asciidoctor-diagram[Asciidoctor Diagram] 是从一个请求中诞生的，该请求是要将 AsciiDoc Python 的 PlantUML 扩展移植到 Asciidoctor。Pepijn Van Eeckhoudt (@pepijnve) 接过了这个任务，并且创建了一个综合性的图表扩展，该扩展不仅加入了与 PlantUML 的整合，还增加了三个附加的图表工具，同时也为将来添加更多工具提供了框架。

Asciidoctor Diagram 1.5.0 现在支持以下图表工具：

Asciidoctor 图表处理图

查看https://asciidoctor.org/docs/asciidoctor-diagram[Asciidoctor Diagram guide]以了解如何在您的Asciidoc文档中从ASCII艺术创建图表。

好奇如何从命令行界面加载像Asciidoctor Diagram这样的扩展？继续阅读。

图标：齿轮[] 从命令行界面加载扩展

Asciidoctor在0.1.4版本中引入了一个扩展API，使你能够扩展AsciiDoc语法并接入处理器的生命周期。然而，只有在通过API调用Asciidoctor或创建自定义启动脚本时才能加载这些扩展。

asciidoctor` 命令现在支持 -r 和 -I 标志（从 ruby 命令中移植而来），分别用来引入额外的路径或修改加载路径。

这里有一个使用`-r`标志来启用Asciidoctor Diagram扩展的例子：

$ asciidoctor -r asciidoctor-diagram sample.adoc

-r` 标志也接受绝对路径或相对路径，并且可以多次使用。

$ asciidoctor -r ./my-extension-a.rb -r ./my-extension-b.rb sample.adoc

通过`-r`标志引用的脚本将按照它们列出的顺序在任何其他处理发生之前加载。

现在你可以充分利用`asciidoctor`命令加上扩展功能了！

图标：书籍[] 拥抱 DocBook 5

The DocBook 5 规范在2008年最终确定。是时候我们接受它了。

当您使用https://asciidoctor.org/docs/user-manual/#docbook[`docbook`后端]时，DocBook 5 现在是默认的输出格式。如果您仍然需要生成DocBook 4.5，请使用`docbook45`后端。

Making XML parsers happy

HTML5重新引入了灵活的HTML语法，这种语法仅仅是基于SGML而非严格的XML…​这一决定使HTML5变得更易于接近。然而，这也让XML解析器变得非常棘手。

为了适应使用XML解析器来读取生成的HTML的工具，Asciidoctor现在可以输出HTML5的XHTML变体，也就是所谓的http://www.w3.org/TR/html5/introduction.html#html-vs-xhtml[XHTML5]。

要输出XHTML5而不是HTML5，请将后端设置为 xhtml，或者更明确地说，xhtml5。名称开头的“x”巧妙地指示Asciidoctor关闭短标签，为布尔属性赋值以及在根元素上添加`xmlns`属性。

信任我们，你的XML解析器会感激你的。

图标：file-pdf-o[] PDF和EPUB3

Asciidoctor 现在可以直接从 AsciiDoc 转换为 PDF 和 EPUB3，分别使用 Asciidoctor PDF 和 Asciidoctor EPUB3 进行转换。这些转换器托管在它们自己的仓库中，并且作为单独的 gems 分发。

由Asciidoctor EPUB3生成的EPUB3

转换器目前是α版，但仍然非常实用。

图标：地球[] Asciidoctor.js 是 Asciidoctor

吉尔姆·格罗塞蒂（Guillaume Grossetie）在1.5.0开发周期内带头努力，以使https://github.com/asciidoctor/asciidoctor.js[Asciidoctor.js]代码库与Asciidoctor核心对齐。经过大量的摆弄和Opal补丁之后，Asciidoctor.js现在可以直接针对master分支和Asciidoctor 1.5.0版本进行构建。这意味着，Asciidoctor.js首次*成为了*Asciidoctor。

Anthonny Quérouil (@anthonny) 接着开发了一个Grunt构建脚本来打包Asciidoctor.js，并将其发布到https://www.npmjs.org/package/asciidoctor.js[npm]（Node.js包管理器）和http://bower.io/search/?q=asciidoctor[Bower]（网页包管理器）。

Guillaume是https://chrome.google.com/webstore/detail/asciidoctorjs-live-previe/iaalpfgpbocpdfblpnhhgllgbdbchmia[AsciiDoc预览 for Chrome] 的创建者，Anthonny是https://atom.io/packages/asciidoc-preview[AsciiDoc预览 for Atom] 的创建者。Atom的AsciiDoc预览补充了由安东·莫伊谢夫（Anton Moiseev）（https://github.com/antonmoiseev[@antonmoiseev]）开启的[Asciidoctor语言定义](github.com/asciidoctor/atom-language-asciidoc)。托马斯·克恩（Thomas Kern）（https://github.com/nerk[@nerk]）紧随其后，基于上述工作，为Brackets推出了https://github.com/asciidoctor/brackets-asciidoc-preview[AsciiDoc插件]。我们也邀请了Asciidoctor.js的资深项目http://gist.asciidoctor.org[DocGist]加入了Asciidoctor组织。DocGist是由安德斯·纳沃斯（Anders Nawroth）（https://github.com/nawroth[@nawroth]）创建的。Guillaume、Anthonny、Anders、Thomas、Anton和其他人一直在协作，基于Asciidoctor.js开发工具。他们正在帮助Asciidoctor勇敢地走向前所未有的AsciiDoc实现的新境界。

Asciidoctor.js和Asciidoctor核心的对齐是一个重大的努力。我想真诚地感谢Guillaume、Anthonny和Opal团队（Adam Beynon、meh和Elia Schito）让这一切成为可能。

图标：编辑[] AsciiDoc 语法洗牌

单引号（'）和反引号（ ` ）是AsciiDoc语法中的两个标记字符，它们经常让人们感到困扰。它们喜欢互相妨碍。我们决定对一些AsciiDoc语法进行洗牌，以解决这个问题，总体上使其更加一致和易于学习。这些变更不仅减少了解析器的失误，而且增强了加号字符的含义，并且通过使反引号成为主要的等宽格式字符，实现了与Markdown的更多对齐。

使用兼容模式迁移

在介绍发生了什么变化之前，我们想要强调一点，您可以通过设置`compat-mode`属性来放弃斜体、等宽字体和直通文本的语法更改，如下所示在文档头部定义：

兼容模式

或者使用两行文档标题：

Document Title ==============

兼容模式用于在新语法与遗留语法不一致时启用遗留语法。有关迁移你的AsciiDoc文档以及可用的过渡语法的更多信息，请参阅 迁移指南。

“+”表示直通

在原始的AsciiDoc语法中，+`字符的使用并不一致。单个加号(+`)和双加号(++)被用来将文本格式化为等宽字体，而三个加号(+++)和四个加号(++++)被用来将文本从处理中逃逸。

我们通过始终使用`+`作为https://asciidoctor.org/docs/user-manual/#passthru[透传格式标记]，使AsciiDoc更直观、更易于教学。我们没有使用单加号和双加号进行等宽字体格式化，而是将它们分别制作成受限和不受限的文字（即，“按原样渲染”）。例如：

_bar_ 变成 bar foo_bar_ 变成 foo_bar_

我们还没有提到如何将文本格式化为等宽字体。为此，我们将重新使用反引号。

Markdown风格的单间字体

熟悉Markdown的作者习惯于使用反引号(`)将文本格式化为等宽字体。我们在Asciidoctor中也接受了这一约定。

Using backtick characters around text now means the text should be formatted as monospace only. The backtick characters do not add passthrough semantics, as they did before. In most cases, the passthrough semantics aren’t necessary, so using the backticks for monospaced formatting is sufficient.

literal` 变成 literal（以等宽字体显示） html5 变成 html5（以等宽字体显示） a||b 变成 a||b（其中 || 以等宽字体显示）

如果你想防止等宽文本中的替换，只需记住，“加号用于直通”：

{backend}` 变为 html5 （在等宽字体中）

通过不将等宽字体格式化与直通（字面）语义混合，我们与Markdown中反引号的行为略有偏差。然而，那是因为AsciiDoc具有额外的特性，例如属性引用，我们想要在将文本格式化为等宽字体时能够利用这些特性。

在一段时间内，你需要同时使用 Asciidoctor 0.1.4 和 1.5.0 来处理你的文档（主要是在我们等待 GitHub 升级的时候）。我们在处理器中增加了特殊的逻辑来处理过渡期间使用的混合语法。有关详细信息，请参阅https://asciidoctor.org/docs/migration/[迁移指南]。

更智能的“智能”引号

旧版AsciiDoc同样使用反引号来制作弯曲引号。因为其语法与等宽字面文本非常相似，它经常以意想不到的方式匹配。我们已经让智能引号的语法…​更智能了。

在Asciidoctor 1.5.0中，反引号作为引号上的修饰符，表示引号应该是弯曲的。现在，您将反引号放在引号字符内部，紧邻被引用的短语，以使其变得“智能”。

翻开一本《泰晤士报》的副本，你一定会看到很多“聪明”的引号。

这种改变使得反引号与引号在位置上更为靠近，因此使得解析变得更加确定性。有关更多弯曲引号和撇号示例，请参阅用户手册的https://asciidoctor.org/docs/user-manual/#curved部分。

引号意味着引用

短语周围的单引号现在保持不变，除非你在兼容模式下运行Asciidoctor。

AsciiDoc 传统上支持使用单引号作为斜体短语的替代语法。然而，在西方语言中，短语周围的单引号已经有了非常明确的含义。使它们成为它们本不是的东西并不是一个好主意。无论如何，我们也从来不推荐出于这个目的使用它们。此外，它们与新的弯曲引号语法相冲突，所以它们不得不被弃用。

请参考https://asciidoctor.org/docs/migration/[迁移指南]以帮助确保顺利过渡到新语法。

图标：缩进[] 调整你的偏移量

leveloffset` 属性用于在组合文档时改变章节的层级。它在单一包含层级的情况下工作得非常好，但正如Groovy开发者https://github.com/melix[Cédric]和https://github.com/glaforge[Guillaume]发现的那样，当进入多层嵌套时，这种方法很快就会崩溃。

问题的关键在于级别偏移值被假定为绝对值。Asciidoctor现在支持使用前导的+或-操作符来实现_相对的_级别偏移值。

Unresolved directive in ../release-notes/asciidoctor-1-5-0.adoc - include::chapter-01.adoc[] :leveloffset: -1

或者，您可以直接在include指令上指定`leveloffset`属性，这样就不用担心恢复旧值了。

Unresolved directive in ../release-notes/asciidoctor-1-5-0.adoc - include::chapter-01.adoc[leveloffset=+1]

图标：过滤器[] 过滤后的标签指令

Groovy开发者经常使用include和tag指令。他们发现，在更广泛的标记范围内的tag指令会被带到文档中。Asciidoctor现在会删除这些行，这样你就可以https://asciidoctor.org/docs/user-manual/#selecting-parts-of-a-document-to-include[在更广范围内嵌套细粒度的范围]。

标签指令也使用更严格的匹配进行搜索，以避免错误匹配。

图标：刷新[] 替换修饰符

当您需要对一个区块进行自定义替换时，您过去必须列出所有想要启用的替换。现在可以通过添加或移除默认替换集合中的替换来实现了https://asciidoctor.org/docs/user-manual/#applying-substitutions[使用 + 和 - 修饰符] (例如，[subs=+quotes])。这应该可以省去很多不必要的打字!

图标：锁[] 安全资产

通过SSL传输资源是一种最佳实践，以避免中间人攻击和一般的间谍行为。

Asciidoctor中默认引用的所有远程资源，如Font Awesome，现在通过SSL从\https://cdnjs.cloudflare.com 和 https://fonts.googleapis.com 提供。

图标：eye-slash[] 隐藏URI方案

Asciidoctor会自动检测和自动链接URLs。写作者们通常不会利用这个功能，因为链接显示了URI方案前缀（例如，http://）。因此，他们最终会长篇大论地使用它，仅仅是为了隐藏前缀。

asciidoctor.org

现在，如果你在文档上设置了`hide-uri-scheme`属性，Asciidoctor可以生成完全相同的结果。

隐藏 URI 方案

https://asciidoctor.org
当设置 hide-url-scheme 时渲染的 URL

asciidoctor.org

图标：指南针[] 人性化的交叉引用

如果您要链接到文档中其他位置的锚点，可以通过标题而不是ID来引用它。

请参阅<<第A节>>。

== 第A节

随着文档的成熟，你可能会希望转而使用ID，但这无疑会帮助早期草稿的流程！

图标：打印[] 打印您的文档

Leif Gruenwoldt (@leif81) 指出打印样式过于激进，导致打印出的文件丧失了完整性。我们一起对样式表进行了调整，直到打印输出的效果几乎和由DocBook工具链生成的PDF一样好。这些样式甚至可以在使用`book`文档类型时将章节分开打印到不同页面。除了这些样式，我们还为网页和打印版的所有网格和框架排列添加了缺失的表格边框样式。

当你有了HTML5和CSS3，谁还需要DocBook呢？

Asciidoctor生成的HTML打印预览

图标：字体[] 开源字体

Asciidoctor的文化深深植根于开源，在这一点上，我们希望始终坚持开源的方式。

在过去，默认的样式表依赖于用户系统上安装的微软核心字体（Arial 和 Georgia）。我们已经用开源字体替换了这些专有字体，这些开源字体我们从谷歌字体加载。

我们选择了以下字体：

  • Noto Serif - 素文和块标题

  • Open Sans Light - 部分标题

  • Droid Sans Mono - 单间距文字和预格式化的块

我们特别喜欢https://www.google.com/fonts/specimen/Noto+Serif[Noto Serif]字体，因为它极具可读性，并且支持全世界所有的语言。

我们对默认样式表进行了额外的改进，使其具有专业、现代的外观。这是新默认主题的预览：

默认Asciidoctor主题的截图

Font Awesome 4.1

提到字体，由于Guillaume Grossetie（在Github的用户mogztter[@mogztter]）所做的工作，Asciidoctor现在与Font Awesome 4.1集成了！现在你有*超过400个图标*可用来装饰你的文档！

在Font Awesome 4中，许多图标被重命名了。如果您有使用图标宏的现有文档，您可能想要添加由Guillaume创建的，用于简化过渡的https://github.com/asciidoctor/asciidoctor/blob/master/compat/font-awesome-3-compat.css[Font Awesome 3兼容性CSS]。

一切都棒极了!!!

致谢

Asciidoctor最好的部分是，而且将永远是，它蓬勃发展的社区。我们想感谢以下参与这次发布的人员。

  • Guillaume Grossetie (@mogztter)

  • Ken Dreyer (@ktdreyer)

  • @megathaum

  • James FitzGibbon (@jf647)

  • Jean-Louis Jouannic (@jljouannic)

  • Leif Gruenwoldt (@leif81)

  • 罗曼·普里索尔（https://github.com/randybb[@randybb]）

  • Aslak Knutsen (@aslakknutsen)

  • Charles Moulliard (@cmoulliard)

  • Pepijn Van Eeckhoudt (@pepijnve)

  • Ken Finnigan (Ken Finnigan的GitHub主页：https://github.com/kenfinnigan[@kenfinnigan])

  • @neher

  • David Gamba (@davidgamba)

  • Jason Porter (GitHub上的链接为https://github.com/lightguard[@lightguard])

  • 马特·斯坦（GitHub上的用户链接：/mstine[@mstine]）

  • Brian Carlson (@bk2204)

  • John Ericksen (@johncarl81)

  • Guillaume Laforge (@glaforge)

  • 亚当·贝侬 (@adambeynon)

  • Romain Manni-Bucau (@rmannibucau)

  • 莎拉·怀特 (GitHub用户名：graphitefriction[@graphitefriction])

  • David Gamba (@davidgamba)

  • 塞德里克·尚佩乌 (@melix)

  • James Carlson (@jxxcarlson)

  • 呃，（https://github.com/meh[@meh]）

  • Laurent Laville (@llaville)

  • 恩里克·鲁伊斯 (@eruiz)

  • Alejandro Revilla (@ar)

  • Matthew Casperson (@mcasperson)

  • Rob Winch (@rwinch)

  • Anthonny Quérouil（[uri-github]/anthonny[@anthonny]）

  • 彼得·诺伯尔（https://github.com/peterneubauer[@petermeubauer]）

  • Andres Almiray (@aalmiray)

  • @cristoper

  • Vadim ([uri-github]/vad1mo[@vad1mo])

  • Phil Webb (@philwebb)

  • Jean-Michel Bruel (@jmbruel)

  • Julien Viet (在GitHub的个人页面：https://github.com/vietj[@vietj])

  • 安德斯·纳沃思 (@nawroth)

  • 罗曼·德尔图尔 (@rdeltour)

  • 费利佩·康特雷拉斯 (@felipec)

  • 徐婉 “fishy” 王 (@fishy)

  • Alex Soto（https://github.com/lordofthejars[@lordofthejars]）

  • Dave Baldwin (Dave Baldwin的GitHub主页：https://github.com/davebaldwin[@davebaldwin])

  • Heiko W. Rupp (@pilhuhn)

  • Baptiste Mathus (@batmat)

  • Michael Hunger (@jexp)

我们想特别感谢以下这些人：

  • 向 Guillaume Grossetie、Ken Dreyer、Leif Gruenwoldt、@megathaum、Ken Finnigan、Brian Carlson、Aslak Knutsen、David Gamba、Wim Champagne、Charles Moulliard、Jean-Louis Jouannic、Roman Priesol 和 James FitzGibbon 致以感谢，因为他们对 Asciidoctor 核心进行了他们的首次源代码贡献。

  • 感谢*Guillaume Grossetie*带头努力，以使Asciidoctor核心与Asciidoctor.js保持一致。

  • 感谢*Anthonny Quérouil*建立了一个用于Asciidoctor.js的Grunt构建，并将其发布到npm和Bower上。

  • 感谢Opal团队的成员(Adam Beynon、meh 和 Elia Schito)帮助我们实现了与Opal的兼容性，并进行了必要的上游更改。

  • 感谢 Ken Dreyer 为Fedora大修了RPM包，并将Asciidoctor的测试套件升级到Minitest 5。

  • 感谢 彼得·诺伊鲍尔 制作了第一件https://twitter.com/mojavelinux/status/486037855051862019[Asciidoctor T恤]，我在发布时穿上了它！

我（丹）还要感谢*莎拉·怀特*，她在软件设计上做出了巨大的努力，编辑用户手册，更新网站，测试（可读作：破坏）以及为项目建立文档工作流。如果没有她的奉献，Asciidoctor不会成为今天的样子。

非常感谢每一个使用该项目的人，感谢那些为改进文档作出呼声以及参与到子项目不断成长的生态系统中的人。Asciidoctor的使命是帮助你成功地编写、发布和传达你的内容，并且享受这个过程！有了你们的反馈和参与，我们就能一起实现这个目标！我们鼓励你在邮件列表、Twitter或IRC上提问和讨论项目的任何方面。

如果您在源代码、文档或网站内容中发现错误或遗漏，请不要犹豫提交问题或者打开一个修复的pull请求。我们总是渴望了解您的体验以及我们如何帮助改善它们。一起，我们让文档变得有趣、简单和有益!

接下来是什么？

这个发布只是发布列车的开始。请期待AsciidoctorJ、Asciidoctor.js、构建插件（Gradle和Maven）、Linux包以及更多产品的发布！

Asciidoctor的下一个版本将是1.5.1的小版本更新。从现在开始，我们计划更快速地迭代，并且只为主要和次要版本做公告。

查看https://github.com/asciidoctor/asciidoctor/blob/master/CHANGELOG.adoc[变更日志]以获取完整的变更列表。