Working with AsciiDoctor

Spring's Getting Started Guides are written with Asciidoctor. This includes a common set of "macros". These macros are simply bits of asciidoc that get included like any other source code.

Getting started with AsciiDoctor

For starters, you need to install Asciidoctor, the Ruby version of AsciiDoc.

gem install asciidoctor

Note: asciidoctor and asciidoc are very similar in functionality. But since the spring.io website actually uses the Java-wrapper around asciidoctor, it's important to use the same version to test out your guide.

Edit README.adoc

Make all your edits to the guide. To pull in macros, simply use AsciiDoc's include macro, like this:

include::https://raw.github.com/spring-guides/getting-started-macros/master/prereq_editor_jdk_buildtools.adoc[]

That effectively pulls in the AsciiDoc text contained in that file.

Some of the macros have parameters, like prereq_editor_jdk_buildtools.asc. If you look at it, you will see this:

:linkattrs:

ifndef::java_version[:java_version: 1.6]

 - A favorite text editor or IDE
 - http://www.oracle.com/technetwork/java/javase/downloads/index.html[JDK {java_version}] or later
 - http://maven.apache.org/download.cgi[Gradle 1.8+] or http://maven.apache.org/download.cgi[Maven 3.0+]
 - You can also import the code from this guide as well as view the web page directly into link:/guides/gs/sts[Spring Tool Suite (STS)] and work your way through it from there.

:java_version: is the parameter. It says that if this attribute is not defined in your guide, it will default to 1.6. To replace it, simply embed this:

:java_version: 1.7
include::https://raw.github.com/spring-guides/getting-started-macros/master/prereq_editor_jdk_buildtools.adoc[]

You can see how the attribute is set before calling the macro, and then inside the macro, it is invoked by writing {java_version}.

View the page locally

You can render the page locally and check it out inside a web browser, though this won't be identical to the way it renders in either GitHub or on the Spring website.

asciidoctor -S safe -a allow-uri-read,skip-front-matter README.adoc

Note: To support remote macros, asciidoctor has to be run in "safe" mode with attribute allow-uri-read turned on. It also supports stripping out YAML front matter if it's present.

Open the generated README.html with your browser.

Don't forget: to see these changes on spring.io's website, you must also git push these latest changes to origin.

Note: github doesn't process include directives, hence you won't see the final format when looking at the guide there.

If you use Google's Chrome browser, you can install the Asciidoctor plugin to quickly view things as well. It won't pull in the code bits or remote asciidoc text like the command up above. But it's handy.

Keeping your guide up-to-date with macro changes

Nothing! Yep, since the macros are fetched remotely, on demand, there is no need to update your guide whenever a macro is updated. Same can be said for code edits. Guides are rendered on the fly (with some caching features enabled) inside the sagan web app, so there's nothing to manage.