Spring Getting Started Guides migrated to Asciidoctor

Engineering
Greg Turnquist
December 13, 2013

“If Markdown is a 1st-grader, then AsciiDoc is a PhD student.”[sic] – Dan Allen, project lead of AsciiDoctor

We recently migrated all of our Getting Started Guides to Asciidoctor. Why? Because Asciidoctor provides so many valuable features!

Several built in directives make it possible to pull in entire code files, small fragments of code, and external chunks of reusable content.
Rendering is now embedded into spring.io’s website.
No need to “generate” the guide, which always puts you at risk of being out of sync with the code, the build files, and the document itself.
Lines up with how many of our projects are migrating away from DocBook towards AsciiDoctor to reduce maintenance.

We had a home grown tool helping us in the past with all these things, but by moving to Asciidoctor, we don’t have to maintain it anymore. Instead we can draw upon the talents of the community to build a better collection of guides. Asciidoctor is also much more stable and well developed with all the contributions it has received.
Making contributions to a guide

In case you didn’t know, each guide on the website is backed by a GitHub repository. Just visit http://github.com/spring-guides to see the list.

We place high value on your feedback. If you spot an issue with a guide, please open an issue against its related repository on GitHub. In our internal HipChat channel, we get a nice ding! when that happens.

The guides are aimed at providing nice, concise ways to solve problems. The idea is that you should be able to read through a single guide during a lunch break in 15-30 minutes, including the ability to download the code and run it yourself.

If you want to make contributions to an existing guide, there is a set of guidelines you can read. They include instructions on installing Asciidoctor as well as rendering the content to check out your edits. Just sign our contributor’s agreement and submit a pull request.
AsciiDoc vs. Asciidoctor

You might have noticed me mentioning Asciidoctor everywhere. Asciidoctor is compliant with AsciiDoc, but it has many extra features we make use of.

including remote bits of text
including subsections of code
filtering out front matter

There are others, but essentially, don’t install and run AsciiDoc and assume it will look the same.

Note: GitHub doesn’t render include directives. If you view a guide directly on GitHub, you will see many parts rendered, but not code fragments or the reused bits of content. To see it in its rendered format, you have to view it on the spring.io website. Not to worry; each guide has a link in the description of the repository.

Summary

When we undertook the task of writing these guides, we had two goals. The first was to serve up the most useful set of code samples for solving problems with Spring. The second was to author the content using well supported tools, making it easy for both internal staff and the community to make contributions.

We’re not done writing guides. More are in the pipeline. But switching to Asciidoctor has enabled us to use a very popular, community-driven tool with strong support from its leader. Hopefully with this reduction in barriers, it will be easier than ever for you to flag issues and make contributions. That way, we can focus on producing better content!
comments powered by Disqus

translate：
翻译：

我们最近将所有入门指南迁移到了Ascidoctor。为什么？因为腹水检查提供了很多有价值的功能！
有几个内置的指令可以将整个代码文件、代码的小片段和可重用内容的外部块拉入。
渲染现在嵌入到spring.io的网站中。
不需要“生成”指南，这总是使您面临与代码、生成文件和文档本身不同步的风险。
与我们有多少项目正在从DocBook迁移到AsciiDoctor以减少维护。
在过去，我们有一个自己开发的工具来帮助我们处理所有这些事情，但是通过迁移到Ascidoctor，我们不再需要维护它了。相反，我们可以利用社区的人才，建立一个更好的指南集。腹水科也更加稳定和良好的发展与所有的贡献，它收到了。
为导游作贡献
如果您不知道，网站上的每个指南都有一个GitHub存储库作为支持。请访问http://github.com/spring-guides查看列表。
我们非常重视您的反馈。如果您发现指南有问题，请针对GitHub上的相关存储库打开一个问题。在我们的内部HipChat频道，我们得到了一个不错的叮当！当那发生的时候。
这些指南旨在提供解决问题的简洁、友好的方法。这个想法是，你应该能够在午休的15-30分钟内读完一本指南，包括下载代码并自己运行代码的能力。
如果您想对现有指南作出贡献，可以阅读一组指南。其中包括有关安装Ascidoctor以及呈现内容以签出编辑的说明。只需签署我们的贡献者协议并提交一个请求。
腹水组与腹水组

Spring Getting Started Guides migrated to Asciidoctor相关推荐

Building a Restful Web Service(最好的Spring入门教程 --来自Spring官网的Guides)
搭建一个Restful Web服务本文档将引导你用Spring搭建一个"Hello,World!"Restful Web服务. 你要搭建的是什么? 你将搭建一个Web服务,这个服 ...
Spring Boot/Cloud干货汇总（持续更新：20180226版）
抽空对本号推送的Spring相关内容做个汇总整理,包括: - Spring - Spring Boot - Spring cloud - 其他Spring干货内容 Spring Boot专题基础入门 ...
Spring干货汇总（含Spring Boot与Spring Cloud）
周末抽空对本号推送的Spring相关内容做个汇总整理(包括spring boot.spring cloud等),方便大家查阅. Spring Boot专题基础入门内容 SpringBoot快速入门 ...
Spring.Net官网翻译
http://www.springframework.net/ Home Overview Downloads Modules Roadmap Documentation Examples/Tutor ...
调试Spring源码 5.2.2.RELEASE
文章目录 1. 环境准备 2. Spring 环境配置 3. 调试源码 1. 环境准备 spring-framework 5.2.2.RELEASE:https://github.com/spring ...
springboot Serving Web Content with Spring MVC
Serving Web Content with Spring MVC This guide walks you through the process of creating a "hel ...
Spring Security(四) —— 核心过滤器源码分析
摘要: 原创出处 https://www.cnkirito.moe/spring-security-4/ 「老徐」欢迎转载,保留摘要,谢谢! 4 过滤器详解前面的部分,我们关注了Spring Sec ...
Spring Security + JWT实现权限管理
1 写在之前本博客主要使用Spring Boot 整合Spring Security + JWT实现权限管理,利用JWT工具生成token,返回给登录接口.在访问其他接口时,采用Bearer Tok ...
Maven+Spring Web 项目结构在Eclipse下面的实现
软件151 马清友我们在这里所要实现的关键就是如何保证 Maven 规定的目录结构. 这里对于Maven的目录结构做一个简单的说明: src/main /Java src/main/resour ...

Spring Getting Started Guides migrated to Asciidoctor

Spring Getting Started Guides migrated to Asciidoctor相关推荐

最新文章

热门文章