After much anticipation, GitHub recently upgraded Asciidoctor to the 0.1.4 release, thanks to @bkeepers!
比升级更大的新闻，*源代码列表中启用了语法高亮！*如果你需要看到它才相信，我在这里展示给你证据。
由于自0.1.0版本以来Asciidoctor发生了很多变化——这是之前部署的版本——我们将探讨5个关于此次升级的知识点，以充分利用GitHub上的AsciiDoc渲染。
1. 源代码语法高亮显示
首先和最重要的是，源代码的语法高亮终于被启用了！源代码列表中的色彩斑斓是由http://pygments.org[Pygments]语法高亮器添加的。
您不需要做任何特别的事情就可以开始使用这个功能。只需使用以下方式将一个源代码块添加到您的AsciiDoc文件中：
-
列表块语法
[source,ruby] ---- puts ['AsciiDoc', 'GitHub', 'AsciiDoc on GitHub'].map {|item| "I use #{item}!" } * "\n" ---- -
打开块语法
[source,ruby] -- puts ['AsciiDoc', 'GitHub', 'AsciiDoc on GitHub'].map {|item| "I use #{item}!" } * "\n" -- -
或者使用围栏代码块语法（类似GitHub风格的Markdown）
ruby puts ['AsciiDoc', 'GitHub', 'AsciiDoc on GitHub'].map {|item| "I use #{item}!" } * "\n"
渲染后的样子是这样的：
ruby puts [AsciiDoc, GitHub, AsciiDoc on GitHub].map {|item| "I use #{item}!" } * "\n"
你可以在 Pygments 文档的[词法分析器页面](http://pygments.org/docs/lexers/#lexers-for-agile-languages)找到 Pygments 可识别的语言列表。
哇！！！天哪！！！哇————！！！啊——————惊叹声 哦————— 耶——————！！！双层彩虹！！！
2. 文档标题和脚注
你会很高兴地知道，如果你的AsciiDoc文件有一个标题（0级标题），GitHub现在会将其显示为<h1>标题。以前，文档标题会被忽略，这就需要你使用一些变通的方法，如果你想要你的渲染文档以一个标题开始的话（正如大多数人所希望的）。
另外，GitHub现在会在你期望找到脚注的地方，在文档的底部呈现脚注[1]。遗憾的是，从参考文献到脚注的链接并不工作，因为HTML清洁器会清除掉元素上的id属性（它们作为锚点）。但至少现在你知道要寻找脚注了。我们会在下一次升级中修复这些链接。
将 include 替换为链接
我很想告诉你包含文件现在可以工作了，但那个消息还得等到我们解决了安全问题之后的另一天。在那之前，我们至少有了一个改善阅读体验的解决方案。
如果你在你的AsciiDoc中使用了+include+指令，Asciidoctor会将该指令替换为一个指向目标文件的链接，这使得在GitHub界面之间导航变得很容易。你可以在[这个样本AsciiDoc文件](https://github.com/opendevise/asciidoc-samples/blob/master/runtime.adoc)中看到一个例子。
4. 符合规范的AsciiDoc，增加了语法糖
升级到Asciidoctor 0.1.4带来了各种各样的改进到AsciiDoc语法。AsciiDoc文档现在的解析准确度不亚于使用AsciiDoc Python的情况。这意味着自从AsciiDoc Python停止更新以来，GitHub上的AsciiDoc首次成为了_真正的_ AsciiDoc。
改善了合规性
以下是几个现在可以被正确解析的语法领域：
-
属性条目在文档中找到的位置生效。
讲话者：John 主题：Sarah “嗨{subject}!”，{speaker}大喊。 扬声器：Sarah 主题：John “嘿，{subject}！”{speaker}回答道。 -
现在已正确忽略在逐字内容内的属性条目。
[literal] :name: not an attribute entry
-
显式替换可以使用subs属性应用于任何块。
[source,xml,subs="attributes,verbatim"] -- <dependencies> <dependency> <groupId>org.springframework</groupId> <artifactId>spring-context</artifactId> <version>{spring-version}</version> <scope>runtime</scope> </dependency> </dependencies> -- -
根据AsciiDoc语法的规定，可以通过第一个位置属性为块级内容分配一个备选的上下文环境。
例如，一个开放的块可以伪装成一个源代码块，如下所示：
[source,ruby] -- puts 'Hello, GitHub!' --
-
列表被解析得更准确，特别是那些包含复杂内容的列表。
糖在上面
在这种遵从行为的顶层是一层甜美的Asciidoctor美好。这些增强包括：
-
快捷方式id、角色和块选项的语法
[sidebar#audience.text-justify] -- 这段内容出现在一个ID为"audience"的侧边栏，并且是两端对齐的文本。
-
解析包括标题和引用块在内的部分Markdown内容
## Asciidoctor speaks Markdown 你听说了吗？Asciidoctor知道如何解析基本的Markdown吗？ 你猜对了，我确实做了！
-
隐式表头行和隐式内容分隔符
项目, 语言 Asciidoctor, Ruby AsciidoctorJ, Java ,===
-
没有因缺失属性而删除的行
虽然无法解析 {foobar}，但是这行内容会按原样渲染。 -
在文档头部用分号分隔的多个作者
= 文件标题 第一作者；第二作者；第三作者
-
如果块属性的值不包含逗号或空格，你可以省略值两边的引号。
[cols=3,width=50%]
-
自定义宏，包括
menu、btn、kbd和icon实验性的； 通过按下kbd:[Ctrl+T]或选择menu:File[New]来打开一个新标签页。
我们可以继续下去，但我就说到这里，让你去探索Asciidoctor增加的许多额外的甜美层次。
|
尽管AsciiDoc语法被正确解析和渲染，但输出的效果并不总是符合预期。我们面临的挑战在于，Asciidoctor生成的HTML输出通常依赖于样式表来完整地呈现用户界面模式。然而，这些样式在GitHub上并不存在。 更难的是，内容通过HTML消毒程序传递，它去除了大多数HTML属性，所以即使我们可以映射到GitHub中存在的CSS类，我们也不能这么做，因为class属性被剥离了。在未来的升级中，我们将努力寻找一种方法来使这些UI模式工作，例如警示块。 |
5. 目录
最后但同样重要的是，您现在可以在输出中包含一个内容目录，以帮助导航那些较大的文档。
在GitHub上启用目录的第一件事情是在文档头部设置+toc+属性。
= 文件标题 :toc:
接下来，您需要将 toc-placement 属性设置为 preamble，或者取消设置该属性。
= 文件标题 :toc: :toc-placement: preamble
如果您选择+preamble+，那么目录将会在序言之后以及第一节之前被渲染。如果您取消设置该属性，您将需要使用+toc::[]+块宏手动在文档中放置目录。
= 文件标题 :toc: :toc-placement!: toc::[]
您会注意到，当在GitHub上渲染时，目录中会出现多余的项目符号。这种行为可以由缺少必要的样式来解释，正如最后一节的末尾所描述的那样。
AsciiDoc在GitHub上万岁！
最近在GitHub上对Asciidoctor的升级无疑带来了许多改进。你可以在 asciidoc-samples 仓库中看到更多展示可用功能的例子。
| 如果你在GitHub上已经有了AsciiDoc内容，但没有看到新特性，很可能需要对文件进行修改，以便从缓存中启动渲染过的文件，并迫使GitHub重新生成它。 |
如果某些内容仍然没有达到你的满意度，你还有一个“逃生通道”选项。下表中显示了三个隐含属性，你可以查询这些属性来有条件地包含或排除内容。前两个属性只在GitHub环境中被赋值。
属性名称,属性值
env,github env-github,empty string asciidoctor-version,0.1.4 ,===
如果在GitHub上您想渲染不同的内容，简单地使用+ifdef+和+ifndef+预处理指令：
ifdef::env-github[] I'm on GitHub! endif::[] ifndef::env-github[] I'm clearly somewhere else right now. endif::[]
如果您只想在Asciidoctor版本升级时呈现内容，那么请使用+ifeval+预处理指令：
ifeval::["{asciidoctor-version}" > "0.1.4"]
Asciidoctor has been upgraded again!
GitHub is now running Asciidoctor {asciidoctor-version}.
endif::[]
这结束了我们对GitHub上新AsciiDoc体验的简要概述。在GitHub上的AsciiDoc不再是Markdown的二等公民。这是真正的交易，包括语法高亮显示在内。
我想感谢每一个帮助实现这次升级的人，包括[Ryan Waldron](Matthew McCullough(Tim Berglund(Garen Torikian(Brandon Keepers(https://github.com/bkeepers)。当然，我也要感谢AsciiDoc社区中每一个倡导AsciiDoc并帮助使Asciidoctor变得更棒的人。
快乐记录！