How to use spring-asciidoctor-backends?

Question

I want to use spring-asciidoctor-backends to build a documentation with Spring's look and feel. I added the recommended Maven plugin to the pom like this:

<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>2.1.0</version>
    <executions>
        <execution>
            <id>generate-html-documentation</id>
            <phase>prepare-package</phase>
            <goals>
                <goal>process-asciidoc</goal>
            </goals>
            <configuration>
                <backend>spring-html</backend>
            </configuration>
        </execution>
    </executions>
    <dependencies>
        <dependency>
            <groupId>io.spring.asciidoctor.backends</groupId>
            <artifactId>spring-asciidoctor-backends</artifactId>
            <version>0.0.6</version>
        </dependency>
    </dependencies>
</plugin>

Then I build the docs using the following maven command:

mvn asciidoctor:process-asciidoc

The build runs and the HTMLs are being generated. Unfortunately, the result is not a Spring styled HTML but the usual standard Asciidoc style.

Since there isn't any step by step information to find about how to integrate/config/build spring-asciidoctor-backends I'm stuck at the moment. I assumed that adding the Maven dependencies should be enough. Do I need to add some magic configuration files or something else?

Answer 1

Well, I did manage it. Ihad to read about Maven plugins, goals and phases. And finally I discovered, that the following instruction will produce the desired result:

mvn prepare-package

I would like to conclude by saying that, unfortunately, I keep coming across code and instruction snippets that simply assume that the user is at the same level of knowledge as the person who wrote the instructions. However, this is rarely the case.

What's the harm in including this one simple instruction in the documentation? How is someone who has never dealt with Maven plugins in a deeper sense supposed to know this? It's not helpful to have to learn all the compiler flags first in order to create a Hello World example. There should always be a complete ready-to-go solution that can be implemented quickly, so that newcomers to this topic can deduce one thing or another. And everything else comes afterwards if necessary.