“如果 Markdown 是个一年级学生，那么 AsciiDoc 就是个博士生。”[原文如此]——Dan Allen，AsciiDoctor 项目负责人

我们最近将所有的 入门指南 迁移到了 Asciidoctor。为什么？因为 Asciidoctor 提供了这么多有价值的功能！

• 几个内置指令可以方便地引入整个代码文件、代码片段以及外部可重用内容块。
• 渲染已嵌入到 spring.io 网站中。
• 无需“生成”指南，这总是存在与代码、构建文件和文档本身不同步的风险。
• 与我们许多项目正在从 DocBook 迁移到 AsciiDoctor 以减少维护成本的做法保持一致。

过去，我们有一个自研的工具来帮助我们处理所有这些事情，但迁移到 Asciidoctor 后，我们就不再需要维护它了。取而代之的是，我们可以借助社区的力量来构建一个更好的指南集合。Asciidoctor 还因为收到了许多贡献而变得更加稳定和成熟。

对指南进行贡献

如果您还不知道，网站上的每个指南都有一个 GitHub 仓库支持。只需访问 http://github.com/spring-guides 即可查看列表。

我们非常重视您的反馈。如果您发现指南中存在问题，请在其 GitHub 相关的仓库中提交一个 issue。当这种情况发生时，我们内部的 HipChat 频道会收到一个响亮的 叮！ 声。

这些指南旨在提供简洁有效的解决问题的方法。其理念是，您应该能在午休时间（15-30分钟）内阅读完一份指南，包括下载代码并自行运行的能力。

如果您想为现有指南做出贡献，可以阅读 一套指南。其中包含关于安装 Asciidoctor 以及渲染内容以检查您的修改的说明。只需签署我们的 贡献者协议 并提交一个 pull request。

AsciiDoc 与 Asciidoctor 的区别

您可能已经注意到我到处都在提及 Asciidoctor。Asciidoctor 是符合 AsciiDoc 标准的，但它有许多我们使用的额外功能。

• 包括远程文本片段
• 包括代码的子节
• 过滤掉前端内容

还有其他的，但总而言之，请不要安装并运行 AsciiDoc，然后期望它能显示相同的内容。

注意： GitHub 不渲染 include 指令。如果您直接在 GitHub 上查看指南，您将看到许多部分被渲染出来，但不会显示代码片段或重用的内容。要查看其渲染后的格式，您必须在 spring.io 网站上查看。不用担心；每个指南在仓库的 description 中都有一个链接。

总结

当我们着手编写这些指南时，我们有两个目标。第一个是提供最有用的代码示例集来解决 Spring 的问题。第二个是使用受良好支持的工具来编写内容，从而方便内部员工和社区进行贡献。

我们还没有停止编写指南。还有更多的正在计划中。但切换到 Asciidoctor 使我们能够使用一个非常受欢迎、由社区驱动且受到其领导者大力支持的工具。希望通过降低这些障碍，您可以比以往任何时候都更容易地标记问题和做出贡献。这样，我们就可以专注于制作更好的内容了！