Introduction

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

This approach may sound a little funky (and it is), but it's way better than the misery of Git submodules. In fact, it's actually pretty easy. If you're just getting started, then follow the directions immediately below. If you're needing a refresher on how to keep things up to date, then head to the section at the bottom on "keeping up to date".

Getting started with AsciiDoc

If you are using homebrew, enter the following:

brew install asciidoc source-highlighter

For other platforms, you will have to investigate similar installation tools.

Add the getting-started-base remote

git remote add getting-started-base https://github.com/gregturn/getting-started-base.git

Pull in the base infrastructure

git pull getting-started-base master

Edit README.asc

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

include::macros/header.txt

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.7]

 - 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.7. To replace it, simply embed this:

:java_version: 1.6
include::prereq_editor_jdk_buildtools.asc[]

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.

asciidoc README.asciidoc

Open README.html with your browser.

How to keep your guide up to date

Once you've set up your guide's infrastructure as shown above, you'll get notified whenever changes are made to the shared getting-started-base project.

Basically, you just have to sync up to the latest batch of updates to getting-started-base, like this:

git checkout master
git pull --no-ff getting-started-base master