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

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

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

过去我们有一个自制的工具来帮助我们做所有这些事情，但通过迁移到 Asciidoctor，我们不再需要维护它。 相反，我们可以利用社区的才能来构建更好的指南集合。 Asciidoctor 也更加稳定和完善，并获得了所有贡献。

贡献指南

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

我们非常重视您的反馈。 如果您发现指南有问题，请在 GitHub 上针对其相关存储库打开一个问题。 在我们的内部 HipChat 频道中，当发生这种情况时，我们会得到一个不错的叮！。

这些指南旨在提供简洁明了的方法来解决问题。 我们的想法是，您应该能够在 15-30 分钟的午休时间内阅读完单个指南，包括下载代码并自己运行的能力。

如果您想为现有指南做出贡献，可以阅读 一套指南。 它们包括有关安装 Asciidoctor 以及渲染内容以检查您的编辑的说明。 只需签署我们的 贡献者协议 并提交拉取请求。

AsciiDoc 与 Asciidoctor

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

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

还有其他的，但本质上，不要安装并运行 AsciiDoc 并假设它看起来会一样。

注意：GitHub 不渲染 include 指令。 如果您直接在 GitHub 上查看指南，您将看到许多部分已呈现，但没有代码片段或重用的内容。 要以其渲染格式查看它，您必须在 spring.io 网站上查看它。 不用担心； 每个指南在存储库的描述中都有一个链接。

总结

当我们承担编写这些指南的任务时，我们有两个目标。 第一个目标是提供最有用的代码示例集，以解决使用 Spring 遇到的问题。 第二个目标是使用良好支持的工具编写内容，使内部员工和社区都可以轻松地做出贡献。

我们还没有完成编写指南。 还有更多正在筹备中。 但是切换到 Asciidoctor 使我们能够使用一种非常流行的、社区驱动的工具，并得到其领导者的强大支持。 希望通过减少这些障碍，您能够比以往更容易地标记问题并做出贡献。 这样，我们就可以专注于制作更好的内容！