Add compatibility matrix (#569)

* Adds list of supported versions for maven plugin and site integration * Ignore docs in Build gh action Fixes #567
asciidoctor · Jan 15, 2022 · a85bd4f · a85bd4f
1 parent 1e70af1
commit a85bd4f
Show file tree

Hide file tree

Showing 10 changed files with 64 additions and 8 deletions.
diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml
@@ -3,9 +3,15 @@ on:
   push:
     branches:
       - main
+    paths-ignore:
+      - README.adoc
+      - docs/**
   pull_request:
     branches:
       - main
+    paths-ignore:
+      - README.adoc
+      - docs/**
 
 jobs:
   build:

diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc
@@ -17,6 +17,7 @@ Documentation::
 
   * Add ID's for all parameters of process-asciidoc, auto-refresh and http mojo, to be able to generate direct urls (https://github.com/uniqueck[@uniqueck]) (#533)
   * Clarify where to put the plugin section in `pom.xml` (#558)
+  * Add compatibility matrix (#569)
 
 Bug Fixes::
 

diff --git a/docs/antora.yml b/docs/antora.yml
@@ -4,13 +4,14 @@ version: '2.2'
 asciidoc:
   attributes:
     release-version: 2.2.1
-    maven-site-plugin-version: 3.9.0
     project-repo: asciidoctor/asciidoctor-maven-plugin
     uri-asciidoc: https://asciidoc.org
     uri-asciidoctor: https://asciidoctor.org
     uri-asciidoctorj: https://github.com/asciidoctor/asciidoctorj
     uri-examples: https://github.com/asciidoctor/asciidoctor-maven-examples
     uri-maven: https://maven.apache.org
+    uri-maven-site-plugin: https://maven.apache.org/plugins/maven-site-plugin
+    maven-site-plugin-version: 3.10.0
 nav:
 - modules/plugin/nav.adoc
 - modules/site-integration/nav.adoc

diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc
@@ -9,4 +9,4 @@ The conversion can happen in 2 flavors:
 
 . As a xref:plugin:introduction.adoc[Maven plugin]: AsciiDoc files are converted at full Asciidoctor power independently from Maven site,
 
-. As a xref:site-integration:index.adoc[Maven site module]: AsciiDoc files are integrated with https://maven.apache.org/doxia/[Maven Doxia] tools, however, with a few limitations.
+. As a xref:site-integration:introduction.adoc[Maven site module]: AsciiDoc files are integrated with https://maven.apache.org/doxia/[Maven Doxia] tools, however, with a few limitations.
diff --git a/docs/modules/plugin/nav.adoc b/docs/modules/plugin/nav.adoc
@@ -6,6 +6,7 @@
 *** xref:goals/http.adoc[]
 ** xref:usage.adoc[]
 ** xref:command-line-configuration.adoc[]
+** xref:compatibility-matrix.adoc[]
 ** xref:examples.adoc[]
 ** Help & Guides
 *** xref:tips-and-tricks.adoc[]

diff --git a/docs/modules/plugin/pages/compatibility-matrix.adoc b/docs/modules/plugin/pages/compatibility-matrix.adoc
@@ -0,0 +1,23 @@
+= Compatibility Matrix
+
+Here is the list of supported versions alongside the required {uri-asciidoctorj}[Asciidoctorj] version.
+Release candidate releases are not accounted. 
+
+== Versions
+
+|===
+|Asciidoctor Maven Plugin | AsciidoctorJ | Supported
+
+|v2.x.x
+|v2.x.x
+|Yes
+
+|v1.6.0
+|v1.5.x, v1.6.x
+|No
+
+|v1.5.x
+|v1.5.x
+|No
+
+|===
diff --git a/docs/modules/site-integration/nav.adoc b/docs/modules/site-integration/nav.adoc
@@ -1,2 +1,4 @@
 * Maven Site Integration
-** xref:index.adoc[]
+** xref:introduction.adoc[]
+** xref:setup-and-configuration.adoc[]
+** xref:compatibility-matrix.adoc[]
diff --git a/docs/modules/site-integration/pages/compatibility-matrix.adoc b/docs/modules/site-integration/pages/compatibility-matrix.adoc
@@ -0,0 +1,19 @@
+= Compatibility Matrix
+
+Here is the list of supported versions alongside the required {uri-maven-site-plugin}[Maven Site Plugin] version.
+Release candidate releases are not accounted.
+
+== Versions
+
+|===
+|Asciidoctor Maven Plugin | Maven Site Plugin | Supported
+
+|v2.1.x ~ v2.2.1
+|v3.4 ~ v3.9.1
+|Yes
+
+|v1.5.6 ~ v1.6.0
+|v3.4 ~ v3.9.1
+|No
+
+|===
diff --git a/docs/modules/site-integration/pages/introduction.adoc b/docs/modules/site-integration/pages/introduction.adoc
@@ -0,0 +1,6 @@
+= Introduction
+:maven-doxia-url: https://maven.apache.org/doxia/
+
+The Asciidoctor Maven Site integration provides a {maven-doxia-url}[Maven Doxia] module to author your content with the {Maven Site Plugin}[maven-site-plugin].
+
+Read the xref:setup-and-configuration.adoc#_setup[setup] section to know about how start using it.
diff --git a/...modules/site-integration/pages/index.adoc → ...ration/pages/setup-and-configuration.adoc b/...modules/site-integration/pages/index.adoc → ...ration/pages/setup-and-configuration.adoc
@@ -1,12 +1,9 @@
-= Maven Site Integration
-:navtitle: Setup & Configuration
+= Setup & Configuration
 
 == Setup
 
 To author your Maven-generated site in AsciiDoc, you must first add a dependency on the Asciidoctor plugin to your maven-site-plugin declaration (which more precisely adds a Doxia Parser Module).
 
-IMPORTANT: Maven v3.2.1 or above required, and since asciidoctor-maven-plugin v1.5.6 only maven-site-plugin v3.4 or above is supported.
-
 [source,xml,subs=attributes+]
 .Maven site integration
 -----
@@ -15,7 +12,7 @@ IMPORTANT: Maven v3.2.1 or above required, and since asciidoctor-maven-plugin v1
         <plugin>
             <groupId>org.apache.maven.plugins</groupId>
             <artifactId>maven-site-plugin</artifactId>
-            <version>3.9.1</version>
+            <version>{maven-site-plugin-version}</version>
             <dependencies>
                 <dependency> <!-- Add Asciidoctor Doxia Parser Module -->
                     <groupId>org.asciidoctor</groupId>