Prepare appendices Antora module

* Update hacking with branch description from README

docs/antora/antora.yml

@@ -4,8 +4,9 @@ version: 4.0
 asciidoc:
   attributes:
     release-version: 4.0.2
-    project-name: asciidoctor-gradle-plugin
     project-full-path: asciidoctor/asciidoctor-gradle-plugin
+    project-name: asciidoctor-gradle-plugin
+    project-repo-url: asciidoctor-gradle-plugin
     plugin-name: Asciidoctor Gradle plugin
     asciidoc-url: https://asciidoc.org
     asciidoc-docs: https://docs.asciidoctor.org/asciidoc/latest

docs/antora/docs/modules/ROOT/nav.adoc

@@ -1,16 +1,18 @@
 * xref:compatibility.adoc[]
+* xref:compatibility.adoc[]
 * xref:quick-start.adoc[]
 * xref:common-task-configuration.adoc[]
 * xref:asciidoctorj-base-plugin.adoc[]
 * xref:asciidoctorj-plugin.adoc[]
 * xref:asciidoctorj-pdf-plugin.adoc[]
 * xref:asciidoctorj-epub-plugin.adoc[]
 * xref:asciidoctorj-revealjs-plugin.adoc[]
-* xref:asciidoctorj-leanpub-plugin.adoc[]
+// * xref:asciidoctorj-leanpub-plugin.adoc[]
 * xref:asciidoctor-diagram.adoc[]
 * xref:asciidoctorj-gems-plugin.adoc[]
-//xref:kindlegen-plugin.adoc[]
+// * xref:kindlegen-plugin.adoc[]
 * xref:asciidoctorj-custom-extensions.adoc[]
 * xref:asciidoctorjs-plugin.adoc[]
 * xref:asciidoctoreditorconfig-plugin.adoc[]
 * xref:docinfo.adoc[]
+* xref:upgrading.adoc[]

docs/antora/docs/modules/appendices/pages/hacking.adoc

@@ -0,0 +1,10 @@
+= Development
+:development-branch: development-4.x
+
+`master` now represents the code for the latest 4.x release of these plugins.
+
+Development for 4.x is against the link:{project-repo-url}/tree/{development-branch}[{development-branch}] branch.
+PRs are preferably taking against this branch.
+
+The 3.x series of the plugin is now in maintenance only mode.
+PRs for that should be raised against the link:https://github.com/asciidoctor/asciidoctor-gradle-plugin/tree/maintenance-3.x[maintenance-3.x] branches.

docs/antora/docs/modules/appendices/pages/known-limitations.adoc

@@ -0,0 +1,9 @@
+= Known Issues
+
+These are the main ones we know about:
+
+* EPUB3 + KF8 in one task. Both formats in one task is currently failing. The exact failure message depends on which order
+  (KF8+EPUB3 or EPUB3+KF8) the conversion takes place in.
+* KF8 conversions fails under Windows. (Related to {issues-asciidoctorj}659[{asciidoctorj-name} #659] & {issues-jruby}4943[{jruby-name} #4943].
+* Does not work with JDK9 (but does with JDK10).
+* DeckTape export to JPG/PNG does not work on Windows (issues-asciidoctorj}[{asciidoctorj-name} #381] & https://github.com/astefanutti/decktape/issues[Decktape #181]).

docs/antora/docs/modules/appendices/pages/tips-and-tricks.adoc

@@ -0,0 +1,75 @@
+= Tips & Tricks
+
+== Issues with plugins that modify project.version
+
+Plugins such as https://github.com/nebula-plugins/nebula-release-plugin[Nebula Release] and https://github.com/ajoberstar/reckon[Reckon] modify `project.version` with a non-serialisable object. This breaks the build.
+
+The safest workaround is to set the `revnumber` attribute to a delayed evaluation of `project.version` in your build:
+
+[source,groovy]
+----
+asciidoctorj {
+    attributes revnumber : { project.version.toString() }
+}
+----
+
+== Pre-process and post-process
+
+To make your own custom actions before or after asciidoctor processing, use `doFirst` and `doLast`. Check out chapters https://docs.gradle.org/current/userguide/tutorial_using_tasks.html[14] and https://docs.gradle.org/current/userguide/more_about_tasks.html[17] in the Gradle docs to learn about the various actions you can perform.
+
+[source,groovy]
+.build.gradle
+----
+asciidoctor.doFirst {
+  // pre-process
+}
+asciidoctor.doLast {
+  // post-process
+}
+----
+
+As an example, here's how to copy the generated `index.html` file to the root of the project. This is useful in Windows systems where asciidoctor can't output directly to the root.
+
+[source,groovy]
+.build.gradle
+----
+asciidoctor.doLast {
+    copy {
+        from 'build/docs/html5'
+        into "$projectDir"
+        include 'index.html'
+    }
+}
+----
+
+== Using Pygments source highlighter
+
+NOTE: You need to have Python 2.x installed on a system or in a container for Pygments to work.
+
+[source,groovy]
+[subs=attributes+]
+----
+plugins {
+  id 'org.asciidoctor.jvm.pdf' version '{release-version}'
+  id 'org.asciidoctor.jvm.gems' version '{release-version}'
+}
+
+repositories {
+    jcenter()
+    ruby.gems()
+}
+
+dependencies {
+  asciidoctorGems 'rubygems:pygments:1.2.1'
+}
+
+asciidoctorPdf {
+  dependsOn asciidoctorGemsPrepare
+  sourceDir 'docs'
+
+  asciidoctorj {
+    requires 'pygments'
+    attributes 'source-highlighter' : 'pygments'
+  }
+}
+----

docs/src/docs/asciidoc/appendix/hacking.adoc

@@ -1,4 +1,11 @@
 [appendix]
 = Development
+:development-branch: development-4.x
 
-NOTE: The `master` branch represents the code for the latest 2.x release of these plugins. Development for for 2.x is against the link:https://github.com/asciidoctor/asciidoctor-gradle-plugin/tree/development-2.0[development-2.0] branch. PRs are preferably taking against that branch. The 1.5.x & 1.6.x series of the plugin is now in maintenance only mode. PRs for these should be raised against the https://github.com/asciidoctor/asciidoctor-gradle-plugin/tree/maintenance-1.5[maintenance-1.5] and https://github.com/asciidoctor/asciidoctor-gradle-plugin/tree/maintenance-1.6[maintenance-1.6]branch.
+`master` now represents the code for the latest 4.x release of these plugins.
+
+Development for 4.x is against the link:{project-repo-url}/tree/{development-branch}[{development-branch}] branch.
+PRs are preferably taking against this branch.
+
+The 3.x series of the plugin is now in maintenance only mode.
+PRs for that should be raised against the link:https://github.com/asciidoctor/asciidoctor-gradle-plugin/tree/maintenance-3.x[maintenance-3.x] branches.

docs/src/docs/asciidoc/attributes.adoc

@@ -1,5 +1,6 @@
-:project-name: asciidoctor-gradle-plugin
 :project-full-path: asciidoctor/asciidoctor-gradle-plugin
+:project-name: asciidoctor-gradle-plugin
+:project-repo-url: asciidoctor-gradle-plugin
 :plugin-name: Asciidoctor Gradle plugin
 :asciidoc-url: https://asciidoc.org
 :asciidoc-docs: https://docs.asciidoctor.org/asciidoc/latest

docs/src/docs/asciidoc/index.adoc

@@ -33,13 +33,13 @@ include::parts/asciidoctorj-epub-plugin.adoc[]
 
 include::parts/asciidoctorj-revealjs-plugin.adoc[]
 
-//! include::parts/asciidoctorj-leanpub-plugin.adoc[]
+// include::parts/asciidoctorj-leanpub-plugin.adoc[]
 
 include::parts/asciidoctor-diagram.adoc[]
 
 include::parts/asciidoctorj-gems-plugin.adoc[]
 
-//! include::parts/kindlegen-plugin.adoc[]
+// include::parts/kindlegen-plugin.adoc[]
 
 include::parts/asciidoctorj-custom-extensions.adoc[]