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

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

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

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

为指南做贡献

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

我们非常重视您的反馈。如果您发现指南有任何问题，请在 GitHub 上针对其相关的仓库创建一个 issue。在我们内部的 HipChat 频道中，发生这种情况时我们会收到一个漂亮的提示！

这些指南旨在提供解决 Spring 相关问题的好方法和简洁方法。我们的想法是，您应该能够在 15-30 分钟的午餐休息时间内阅读一篇指南，包括下载代码并自行运行代码的能力。

如果您想为现有指南做出贡献，您可以阅读一系列指南。其中包括安装 Asciidoctor 以及渲染内容以查看您的编辑的说明。只需签署我们的贡献者协议并提交 pull request。

AsciiDoc 与 Asciidoctor

您可能已经注意到我到处都提到了 Asciidoctor。Asciidoctor 兼容 AsciiDoc，但它还有许多我们正在使用的额外功能。

• 包括远程文本片段
• 包括代码子部分
• 过滤掉前置内容

还有其他一些，但本质上，不要安装和运行 AsciiDoc 并假设它看起来相同。

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

摘要

当我们着手编写这些指南时，我们有两个目标。首先是提供最实用的代码示例来解决 Spring 相关问题。其次是使用支持良好的工具创作内容，使内部员工和社区都可以轻松地做出贡献。

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