Upgrade Asciidoctor Maven Plugin so that syntax highlighting can be enabled using an attribute

[gavvvr]

Unlike Gradle, when building with Maven plugin the :source-highlighter: highlightjs attribute in *.adoc files does not work (it can be even removed). You should explicitly specify sourceHighlighter in Maven plugin configuration, see https://asciidoctor.org/docs/asciidoctor-maven-plugin/#configuration-2

[wilkinsona]

Thanks for the suggestion. The loss of syntax highlighting is caused by a bug in the version of the Asciidoctor Maven Plugin that's being used. Rather than working around the bug by declaring the source highlighter in XML, I think it would be better to upgrade to the latest 1.5.x version of the Maven plugin. Would you like to update this pull request to do that instead? It'd be great if you could make the same update to the documentation as well.

[gavvvr]

Hi @wilkinsona. Would be great to fix it with a plugin version update. But I tried to use 1.5.8 and there was still no highlighting without explicit <sourceHighlighter> in pom. The newest plugin version is 1.6.0 and it throws an exception in my project (with latest rest docs 2.0.3.RELEASE) on attempt to mvn prepare-package:

    at org.apache.maven.plugin.DefaultBuildPluginManager.executeMojo (DefaultBuildPluginManager.java:184)
    at org.apache.maven.lifecycle.internal.MojoExecutor.execute (MojoExecutor.java:210)
    at org.apache.maven.lifecycle.internal.MojoExecutor.execute (MojoExecutor.java:156)
    at org.apache.maven.lifecycle.internal.MojoExecutor.execute (MojoExecutor.java:148)
    at org.apache.maven.lifecycle.internal.LifecycleModuleBuilder.buildProject (LifecycleModuleBuilder.java:117)
    at org.apache.maven.lifecycle.internal.LifecycleModuleBuilder.buildProject (LifecycleModuleBuilder.java:81)
    at org.apache.maven.lifecycle.internal.builder.singlethreaded.SingleThreadedBuilder.build (SingleThreadedBuilder.java:56)
    at org.apache.maven.lifecycle.internal.LifecycleStarter.execute (LifecycleStarter.java:128)
    at org.apache.maven.DefaultMaven.doExecute (DefaultMaven.java:305)
    at org.apache.maven.DefaultMaven.doExecute (DefaultMaven.java:192)
    at org.apache.maven.DefaultMaven.execute (DefaultMaven.java:105)
    at org.apache.maven.cli.MavenCli.execute (MavenCli.java:956)
    at org.apache.maven.cli.MavenCli.doMain (MavenCli.java:288)
    at org.apache.maven.cli.MavenCli.main (MavenCli.java:192)
    at jdk.internal.reflect.NativeMethodAccessorImpl.invoke0 (Native Method)
    at jdk.internal.reflect.NativeMethodAccessorImpl.invoke (NativeMethodAccessorImpl.java:62)
    at jdk.internal.reflect.DelegatingMethodAccessorImpl.invoke (DelegatingMethodAccessorImpl.java:43)
    at java.lang.reflect.Method.invoke (Method.java:567)
    at org.codehaus.plexus.classworlds.launcher.Launcher.launchEnhanced (Launcher.java:282)
    at org.codehaus.plexus.classworlds.launcher.Launcher.launch (Launcher.java:225)
    at org.codehaus.plexus.classworlds.launcher.Launcher.mainWithExitCode (Launcher.java:406)
    at org.codehaus.plexus.classworlds.launcher.Launcher.main (Launcher.java:347)
Caused by: java.lang.IncompatibleClassChangeError: Found interface org.asciidoctor.extension.JavaExtensionRegistry, but class was expected
    at org.springframework.restdocs.asciidoctor.RestDocsExtensionRegistry.register (RestDocsExtensionRegistry.java:32)
    at org.asciidoctor.extension.internal.ExtensionRegistryExecutor.registerAllExtensions (ExtensionRegistryExecutor.java:21)
    at org.asciidoctor.internal.JRubyAsciidoctor.registerExtensions (JRubyAsciidoctor.java:113)
    at org.asciidoctor.internal.JRubyAsciidoctor.processRegistrations (JRubyAsciidoctor.java:102)
    at org.asciidoctor.internal.JRubyAsciidoctor.create (JRubyAsciidoctor.java:82)
    at org.asciidoctor.Asciidoctor$Factory.create (Asciidoctor.java:726)
    at org.asciidoctor.maven.AsciidoctorMojo.getAsciidoctorInstance (AsciidoctorMojo.java:401)
    at org.asciidoctor.maven.AsciidoctorMojo.execute (AsciidoctorMojo.java:205)
    at org.apache.maven.plugin.DefaultBuildPluginManager.executeMojo (DefaultBuildPluginManager.java:137)
    at org.apache.maven.lifecycle.internal.MojoExecutor.execute (MojoExecutor.java:210)
    at org.apache.maven.lifecycle.internal.MojoExecutor.execute (MojoExecutor.java:156)
    at org.apache.maven.lifecycle.internal.MojoExecutor.execute (MojoExecutor.java:148)
    at org.apache.maven.lifecycle.internal.LifecycleModuleBuilder.buildProject (LifecycleModuleBuilder.java:117)
    at org.apache.maven.lifecycle.internal.LifecycleModuleBuilder.buildProject (LifecycleModuleBuilder.java:81)
    at org.apache.maven.lifecycle.internal.builder.singlethreaded.SingleThreadedBuilder.build (SingleThreadedBuilder.java:56)
    at org.apache.maven.lifecycle.internal.LifecycleStarter.execute (LifecycleStarter.java:128)
    at org.apache.maven.DefaultMaven.doExecute (DefaultMaven.java:305)
    at org.apache.maven.DefaultMaven.doExecute (DefaultMaven.java:192)
    at org.apache.maven.DefaultMaven.execute (DefaultMaven.java:105)
    at org.apache.maven.cli.MavenCli.execute (MavenCli.java:956)
    at org.apache.maven.cli.MavenCli.doMain (MavenCli.java:288)
    at org.apache.maven.cli.MavenCli.main (MavenCli.java:192)
    at jdk.internal.reflect.NativeMethodAccessorImpl.invoke0 (Native Method)
    at jdk.internal.reflect.NativeMethodAccessorImpl.invoke (NativeMethodAccessorImpl.java:62)
    at jdk.internal.reflect.DelegatingMethodAccessorImpl.invoke (DelegatingMethodAccessorImpl.java:43)
    at java.lang.reflect.Method.invoke (Method.java:567)
    at org.codehaus.plexus.classworlds.launcher.Launcher.launchEnhanced (Launcher.java:282)
    at org.codehaus.plexus.classworlds.launcher.Launcher.launch (Launcher.java:225)
    at org.codehaus.plexus.classworlds.launcher.Launcher.mainWithExitCode (Launcher.java:406)
    at org.codehaus.plexus.classworlds.launcher.Launcher.main (Launcher.java:347)

[wilkinsona]

1.6 of the plugin doesn't work as it pulls in a version of AsciidoctorJ that contains breaking changes. See #581 for details.

I tried the Data REST sample with 1.5.8 of the Asciidoctor Maven Plugin and the syntax highlighting worked. How did you try it?

[gavvvr]

How did you try it?

In my own example, I had an empty line between top-line header and attributes. So, not a plugin issue. I updated pom.xml and docs, ready for merge

[wilkinsona]

Thanks very much, @gavvvr. The proposed changes are now in 1.2.x and master.