From 40000031aedb9e2f1b24c0149be6929ec5c7989e Mon Sep 17 00:00:00 2001 From: Abel Salgado Romero Date: Tue, 5 Mar 2024 12:45:20 +0100 Subject: [PATCH 01/10] Antora compatible doc changes: - use release-version instead of revnumber to prepare Antora - use level-0 depth level to prepare Antora - several fixes --- docs/antora/antora.yml | 33 ++++++++++++++ docs/antora/build.gradle | 45 ------------------- docs/antora/docs/modules/ROOT/nav.adoc | 16 +++++++ docs/antora/docs/modules/appendices/nav.adoc | 4 ++ docs/build.gradle | 3 +- docs/gradle.properties | 2 +- docs/settings.gradle | 4 +- docs/src/docs/asciidoc/appendix/hacking.adoc | 2 +- .../asciidoc/appendix/known-limitations.adoc | 2 +- .../asciidoc/appendix/tips-and-tricks.adoc | 13 +++--- docs/src/docs/asciidoc/index.adoc | 4 +- .../asciidoc/parts/asciidoctor-diagram.adoc | 4 +- .../parts/asciidoctoreditorconfig-plugin.adoc | 13 +++--- .../parts/asciidoctorj-base-plugin.adoc | 12 ++--- .../asciidoctorj-compatiblity-plugin.adoc | 9 ++-- .../parts/asciidoctorj-custom-extensions.adoc | 13 +++--- .../parts/asciidoctorj-epub-plugin.adoc | 6 +-- .../parts/asciidoctorj-gems-plugin.adoc | 6 +-- .../parts/asciidoctorj-leanpub-plugin.adoc | 9 ++-- .../parts/asciidoctorj-pdf-plugin.adoc | 12 ++--- .../asciidoc/parts/asciidoctorj-plugin.adoc | 8 ++-- .../parts/asciidoctorj-revealjs-plugin.adoc | 10 ++--- .../asciidoc/parts/asciidoctorjs-plugin.adoc | 6 +-- .../parts/common-task-configuration.adoc | 10 ++--- .../docs/asciidoc/parts/compatibility.adoc | 2 +- docs/src/docs/asciidoc/parts/docinfo.adoc | 2 +- .../docs/asciidoc/parts/exporting-slides.adoc | 10 ++--- .../docs/asciidoc/parts/kindlegen-plugin.adoc | 6 +-- docs/src/docs/asciidoc/parts/quick-start.adoc | 6 +-- docs/src/docs/asciidoc/parts/upgrading.adoc | 17 ++++--- 30 files changed, 148 insertions(+), 141 deletions(-) create mode 100644 docs/antora/antora.yml delete mode 100644 docs/antora/build.gradle create mode 100644 docs/antora/docs/modules/ROOT/nav.adoc create mode 100644 docs/antora/docs/modules/appendices/nav.adoc diff --git a/docs/antora/antora.yml b/docs/antora/antora.yml new file mode 100644 index 000000000..20067859e --- /dev/null +++ b/docs/antora/antora.yml @@ -0,0 +1,33 @@ +name: gradle-plugin +title: Gradle Plugin Suite +version: 4.0 +asciidoc: + attributes: + release-version: 4.0.2 + project-name: asciidoctor-gradle-plugin + project-full-path: asciidoctor/asciidoctor-gradle-plugin + plugin-name: Asciidoctor Gradle plugin + asciidoc-url: https://asciidoc.org + asciidoc-userguide: https://docs.asciidoctor.org/asciidoc/latest/ + asciidoctor-docs: https://docs.asciidoctor.org/ + asciidoctor-maven-plugin: https://github.com/asciidoctor/asciidoctor-maven-plugin[Asciidoctor Maven Plugin] + asciidoctor-url: https://asciidoctor.org + asciidoctor-userguide: https://docs.asciidoctor.org/asciidoctor/latest/ + asciidoctorj-epub-name: Asciidoctorj-EPUB + asciidoctorj-name: AsciidoctorJ + asciidoctorj-pdf-leanpub: Asciidoctorj Leanpub + asciidoctorj-pdf-name: Asciidoctorj-PDF + asciidoctorj: https://github.com/asciidoctor/asciidoctorj + asciidoctorjs-name: Asciidoctor.js + groovy-dsl-name: Groovy DSL + gradle-url: https://gradle.org/ + issues: https://github.com/asciidoctor/asciidoctor-gradle-plugin/issues/ + issues-asciidoctorj: https://github.com/asciidoctor/asciidoctorj/issues/ + issues-jruby: https://github.com/asciidoctor/asciidoctorj/issues/ + jruby-name: JRuby + kotlindsl: https://github.com/gradle/kotlin-dsl[Gradle Kotlin DSL] + lightguard: https://github.com/LightGuard[Jason Porter] + lordofthejars: https://github.com/lordofthejars[Alex Soto] +nav: + - modules/ROOT/nav.adoc + - modules/appendices/nav.adoc diff --git a/docs/antora/build.gradle b/docs/antora/build.gradle deleted file mode 100644 index 738def79d..000000000 --- a/docs/antora/build.gradle +++ /dev/null @@ -1,45 +0,0 @@ -plugins { - id 'org.ajoberstar.git-publish' -} - -ext { - currentBranch = System.getenv('CI_BRANCH') ?: 'not-on-ci' - pushDocs = currentBranch.matches(~/^master|development-.+|maintenance-.+$/) -} - -gitPublish { - repoUri = gitHubRepoUri - branch = antoraBranch - - contents { - into version - from rootProject.tasks.prepareSources, { - into 'sources' - } - from "${rootDir}/src/docs", { - include 'asciidoc/**' - } - - // TODO: Wait for Antora to support Javadoc - // See https://gitlab.com/antora/antora/issues/439 -// from rootProject.tasks.combinedDocs, { -// exclude 'user-guide' -// } - } - - preserve { - include '**' - exclude "${version}/**" - } - - commitMessage = "Updating ${version} sources for Antora" -} - -task publishDocs { - if (pushDocs) { - dependsOn gitPublishPush - } - doFirst { - logger.lifecycle "${currentBranch} is ${pushDocs ? 'a match. Push attempted' : 'not a match. Push skipped.'}" - } -} diff --git a/docs/antora/docs/modules/ROOT/nav.adoc b/docs/antora/docs/modules/ROOT/nav.adoc new file mode 100644 index 000000000..1950d77c5 --- /dev/null +++ b/docs/antora/docs/modules/ROOT/nav.adoc @@ -0,0 +1,16 @@ +* 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:asciidoctor-diagram.adoc[] +* xref:asciidoctorj-gems-plugin.adoc[] +//xref:kindlegen-plugin.adoc[] +* xref:asciidoctorj-custom-extensions.adoc[] +* xref:asciidoctorjs-plugin.adoc[] +* xref:asciidoctoreditorconfig-plugin.adoc[] +* xref:docinfo.adoc[] diff --git a/docs/antora/docs/modules/appendices/nav.adoc b/docs/antora/docs/modules/appendices/nav.adoc new file mode 100644 index 000000000..573c01894 --- /dev/null +++ b/docs/antora/docs/modules/appendices/nav.adoc @@ -0,0 +1,4 @@ +* Appendices +** xref:tips-and-tricks.adoc[] +** xref:known-limitations.adoc[] +** xref:hacking.adoc[] diff --git a/docs/build.gradle b/docs/build.gradle index 2cd20f5f6..bd3519fb2 100644 --- a/docs/build.gradle +++ b/docs/build.gradle @@ -69,7 +69,8 @@ asciidoctor { sources { include 'index.adoc' } attributes toc: 'right', toclevels: 2, - 'source-highlighter': 'rouge' + 'source-highlighter': 'rouge', + 'release-version': project.version docProjects.each { proj -> attributes "plugin-${proj.dir}": file("${prepareSources.destinationDir}/${proj.dir}/src") diff --git a/docs/gradle.properties b/docs/gradle.properties index c2f4a03fb..f7cdd9ca9 100644 --- a/docs/gradle.properties +++ b/docs/gradle.properties @@ -1 +1 @@ -gitHubRepoUri=https://github.com/asciidoctor/asciidoctor-gradle-plugin.git +gitHubRepoUri=git@github.com:abelsromero/asciidoctor-gradle-plugin.git diff --git a/docs/settings.gradle b/docs/settings.gradle index 12293e956..e8cf4cc4b 100644 --- a/docs/settings.gradle +++ b/docs/settings.gradle @@ -1,6 +1,4 @@ -rootProject.name='asciidoctor-gradle-docs' +rootProject.name = 'asciidoctor-gradle-docs' includeBuild('..') include 'gh-pages' -// Removes antora, causes issue with gh-pages and git-publish plugin. Causing commits to delete files. -// include 'antora' diff --git a/docs/src/docs/asciidoc/appendix/hacking.adoc b/docs/src/docs/asciidoc/appendix/hacking.adoc index 5d28834f7..e54682de0 100644 --- a/docs/src/docs/asciidoc/appendix/hacking.adoc +++ b/docs/src/docs/asciidoc/appendix/hacking.adoc @@ -1,4 +1,4 @@ [appendix] -== Development += Development 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. diff --git a/docs/src/docs/asciidoc/appendix/known-limitations.adoc b/docs/src/docs/asciidoc/appendix/known-limitations.adoc index 10f6ffff1..98d5f335b 100644 --- a/docs/src/docs/asciidoc/appendix/known-limitations.adoc +++ b/docs/src/docs/asciidoc/appendix/known-limitations.adoc @@ -1,5 +1,5 @@ [appendix] -== Known Issues += Known Issues These are the main ones we know about: diff --git a/docs/src/docs/asciidoc/appendix/tips-and-tricks.adoc b/docs/src/docs/asciidoc/appendix/tips-and-tricks.adoc index a153b89e6..dbdd6ca53 100644 --- a/docs/src/docs/asciidoc/appendix/tips-and-tricks.adoc +++ b/docs/src/docs/asciidoc/appendix/tips-and-tricks.adoc @@ -1,7 +1,7 @@ [appendix] -== Tips & Tricks += Tips & Tricks -=== Issues with plugins that modify project.version +== 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. @@ -14,7 +14,7 @@ asciidoctorj { } ---- -=== Pre-process and post-process +== 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. @@ -43,7 +43,7 @@ asciidoctor.doLast { } ---- -=== Using Pygments source highlighter +== Using Pygments source highlighter NOTE: You need to have Python 2.x installed on a system or in a container for Pygments to work. @@ -51,8 +51,8 @@ NOTE: You need to have Python 2.x installed on a system or in a container for Py [subs=attributes+] ---- plugins { - id 'org.asciidoctor.jvm.pdf' version '{revnumber}' - id 'org.asciidoctor.jvm.gems' version '{revnumber}' + id 'org.asciidoctor.jvm.pdf' version '{release-version}' + id 'org.asciidoctor.jvm.gems' version '{release-version}' } repositories { @@ -74,4 +74,3 @@ asciidoctorPdf { } } ---- - diff --git a/docs/src/docs/asciidoc/index.adoc b/docs/src/docs/asciidoc/index.adoc index 526767f7e..5f691eb49 100644 --- a/docs/src/docs/asciidoc/index.adoc +++ b/docs/src/docs/asciidoc/index.adoc @@ -6,11 +6,13 @@ endif::[] ifeval::[{env}!=idea] :toc: right endif::[] +:leveloffset: +1 The {doctitle} is the official means of using {asciidoctor-url}[Asciidoctor] to convert all your {asciidoc-url}[AsciiDoc] documentation using {gradle-url}[Gradle]. This started as a port of the {asciidoctor-maven-plugin} project founded by {lightguard} and relies on {asciidoctorj}[{asciidoctorj-name}] which was founded by {lordofthejars}. -In fact the 1.5.x series of the {plugin-name} can still be considered a port. However, with 2.x series came a complete departure with functionality far exceeding any lightweight markup plugins for any other build tool. +In fact the 1.5.x series of the {plugin-name} can still be considered a port. +However, with 2.x series came a complete departure with functionality far exceeding any lightweight markup plugins for any other build tool. With the 3.x serious allows for even more flexibility and options for the creation of a true DocuOps pipeline by bringing together Gradle as a powerful and generic build tool, and Asciidoctor as an agile and lightweight document generator. include::parts/compatibility.adoc[] diff --git a/docs/src/docs/asciidoc/parts/asciidoctor-diagram.adoc b/docs/src/docs/asciidoc/parts/asciidoctor-diagram.adoc index c697ca49a..4cdfac2d2 100644 --- a/docs/src/docs/asciidoc/parts/asciidoctor-diagram.adoc +++ b/docs/src/docs/asciidoc/parts/asciidoctor-diagram.adoc @@ -1,5 +1,5 @@ [[diagram]] -== Using AsciidoctorJ Diagram += Using AsciidoctorJ Diagram The new plugins have built-in support for `asciidoctorj-diagram`. Simply add the following to the project or task extension and diagramming will be available. If it is not set the `asciidoctorj-diagram` JAR will not be added to the classpath. @@ -18,7 +18,7 @@ asciidoctorj { With this enhancement, there is also no longer a need to add `requires 'asciidoctor-diagram'`. -NOTE: If you using OpenJDK 9/10 on MacOS you might find an error such as below +NOTE: If you are using OpenJDK 9/10 on macOS you might find an error such as below ---- Caused by: java.lang.UnsatisfiedLinkError: /path/to/openjdk10/lib/libfontmanager.dylib: dlopen(/path/to/openjdk10/lib/libfontmanager.dylib, 1): Library not loaded: /Users/jenkins/workspace/openjdk10_build_x86-64_macos/openjdk/installedfreetype/lib/libfreetype.6.dylib diff --git a/docs/src/docs/asciidoc/parts/asciidoctoreditorconfig-plugin.adoc b/docs/src/docs/asciidoc/parts/asciidoctoreditorconfig-plugin.adoc index 11bdc6be1..50361060a 100644 --- a/docs/src/docs/asciidoc/parts/asciidoctoreditorconfig-plugin.adoc +++ b/docs/src/docs/asciidoc/parts/asciidoctoreditorconfig-plugin.adoc @@ -1,11 +1,11 @@ -== The Asciidoctor Editor Config Plugin += The Asciidoctor Editor Config Plugin [source,groovy,role="primary"] [subs=attributes+] .build.gradle ---- plugins { - id 'org.asciidoctor.editorconfig' version '{revnumber}' + id 'org.asciidoctor.editorconfig' version '{release-version}' } ---- @@ -14,13 +14,13 @@ plugins { .build.gradle.kts ---- plugins { - id("org.asciidoctor.editorconfig") version "{revnumber}" + id("org.asciidoctor.editorconfig") version "{release-version}" } ---- Writes an `.asciidoctorconfig` file so that supporting IDEs can render Asciidoctor-based documentation correctly. -=== Adding attributes +== Adding attributes [source,groovy,role="primary"] ---- @@ -36,12 +36,11 @@ asciidoctorEditorConfig { <2> Adds all attributes defined on the project extension to the generated file. These attributes are added after the predefined attributes. <3> Appends the context of the specified file to the generated file. Context such as this is added last. This method also allows you to define a number of attributes in your source directory and include them in your main Asciidoc file as well as send them to `.asciidoctorconfig`. - -=== Changing the output directory +== Changing the output directory [source,groovy,role="primary"] ---- asciidoctorEditorConfig { destinationDir = 'docs' } ----- \ No newline at end of file +---- diff --git a/docs/src/docs/asciidoc/parts/asciidoctorj-base-plugin.adoc b/docs/src/docs/asciidoc/parts/asciidoctorj-base-plugin.adoc index 42771549c..dbba3bc8f 100644 --- a/docs/src/docs/asciidoc/parts/asciidoctorj-base-plugin.adoc +++ b/docs/src/docs/asciidoc/parts/asciidoctorj-base-plugin.adoc @@ -1,4 +1,4 @@ -== AsciidoctorJ Base Plugin += AsciidoctorJ Base Plugin This plugin is automatically applied by all AsciidoctorJ-based plugins. @@ -50,7 +50,7 @@ include::{plugin-base}/main/groovy/org/asciidoctor/gradle/base/AbstractImplement // TODO: Split attributes into a standalone section that is not part of base plugin. [[attributes,Setting Attributes]] [[options,Setting Options]] -=== Options & Attributes +== Options & Attributes The following options may be set using the extension's `options` property @@ -114,7 +114,7 @@ link:{asciidoctor-userguide}#attribute-assignment-precedence[Attribute assignmen for more information. [[asciidoctorj-modules,{asciidoctorj-name} Modules]] -=== Versions of modules +== Versions of modules The modules block currently supports four elements @@ -172,7 +172,7 @@ asciidoctorj { <1> Set the {asciidoctorj-pdf-name} version to `1.2.3`. <2> Use the default version of {asciidoctorj-pdf-name}. -=== Applying the {asciidoctorj-name} Base plugin on its own +== Applying the {asciidoctorj-name} Base plugin on its own If none of the default conventions work for you, the base plugin can be applied on its own. @@ -181,7 +181,7 @@ If none of the default conventions work for you, the base plugin can be applied .build.gradle ---- plugins { - id 'org.asciidoctor.jvm.base' version '{revnumber}' + id 'org.asciidoctor.jvm.base' version '{release-version}' } ---- @@ -190,6 +190,6 @@ plugins { .build.gradle.kts ---- plugins { - id("org.asciidoctor.jvm.base") version "{revnumber}" + id("org.asciidoctor.jvm.base") version "{release-version}" } ---- diff --git a/docs/src/docs/asciidoc/parts/asciidoctorj-compatiblity-plugin.adoc b/docs/src/docs/asciidoc/parts/asciidoctorj-compatiblity-plugin.adoc index e55824a2f..fab17ce1e 100644 --- a/docs/src/docs/asciidoc/parts/asciidoctorj-compatiblity-plugin.adoc +++ b/docs/src/docs/asciidoc/parts/asciidoctorj-compatiblity-plugin.adoc @@ -1,4 +1,4 @@ -== Asciidoctor Compatibility Plugin += Asciidoctor Compatibility Plugin In order to help people upgrade a compatibility plugin has been kept which mostly behaves in the same way as the {asciidoctorj-name} plugins in the 1.5.x series [source,groovy,role="primary"] @@ -6,7 +6,7 @@ In order to help people upgrade a compatibility plugin has been kept which mostl .build.gradle ---- plugins { - id 'org.asciidoctor.convert' version '{revnumber}' + id 'org.asciidoctor.convert' version '{release-version}' } ---- @@ -15,7 +15,7 @@ plugins { .build.gradle.kts ---- plugins { - id("org.asciidoctor.convert") version "{revnumber}" + id("org.asciidoctor.convert") version "{release-version}" } ---- @@ -64,4 +64,5 @@ sourceDir:: where the asciidoc sources are. sources:: specify which Asciidoctor source files to include by using an http://www.gradle.org/docs/current/javadoc/org/gradle/api/tasks/util/PatternSet.html[Ant-style PatternSet]. -NOTE: Even though the DSL remains the same with this task, the internals have been changed to use the same `JAVA_EXEC` mechanism of the `org.asciidoctor.jvm.convert` plugins. The problems which the 1.5.x series suffered with classpaths anions disappearing should now be a thing of the past. +NOTE: Even though the DSL remains the same with this task, the internals have been changed to use the same `JAVA_EXEC` mechanism of the `org.asciidoctor.jvm.convert` plugins. +The problems which the 1.5.x series suffered with classpaths anions disappearing should now be a thing of the past. diff --git a/docs/src/docs/asciidoc/parts/asciidoctorj-custom-extensions.adoc b/docs/src/docs/asciidoc/parts/asciidoctorj-custom-extensions.adoc index 9d0fe724f..e65f3fd63 100644 --- a/docs/src/docs/asciidoc/parts/asciidoctorj-custom-extensions.adoc +++ b/docs/src/docs/asciidoc/parts/asciidoctorj-custom-extensions.adoc @@ -1,10 +1,10 @@ [[asciidoctorj-extensions,Adding custom {asciidoctorj-name} extensions]] -== Adding Custom Extensions += Adding Custom Extensions Starting with version 1.5.0 you were able to write your own Asciidoctor extensions in Groovy, or any other JVM language for that matter. Now with the 2.0.0 you have even more flexibility in that extensions can be applied on a per task basis on globally. There are several options available to make it happen. -=== As External Library +== As External Library This is the most versatile option, as it allows you to reuse the same extension in different projects. An external library is just like any other Java/Groovy project. You simply define a dependency using the `asciidoctor` configuration. @@ -39,8 +39,7 @@ tasks.withType { } ---- - -=== As Project Dependency +== As Project Dependency The next option is to host the extension project in a multi-project build. This allows for a much quicker development cycle as you don't have to publish the jar to a repository every time you make adjustments to the code. Take for example the @@ -81,7 +80,7 @@ The `extension` project is a sibling for `core`. The build file for the latter l .build.gradle ---- plugins { - id 'org.asciidoctor.jvm.convert' version '{revnumber}' + id 'org.asciidoctor.jvm.convert' version '{release-version}' } repositories { @@ -108,7 +107,7 @@ Alternatively you can add the project to the extension directly .build.gradle ---- plugins { - id 'org.asciidoctor.jvm.convert' version '{revnumber}' + id 'org.asciidoctor.jvm.convert' version '{release-version}' } asciidoctorj { @@ -119,7 +118,7 @@ asciidoctorj { In the less-common case where extension is not supplied via the default configuration, the latter shortcut will not work, and you will need to use the longer method described above. -=== As Inline Script +== As Inline Script The next option is to define extensions directly in the build script. This approach is based on the project asciidoctorj-groovy-dsl that allows to define Asciidoctor extensions in Groovy. diff --git a/docs/src/docs/asciidoc/parts/asciidoctorj-epub-plugin.adoc b/docs/src/docs/asciidoc/parts/asciidoctorj-epub-plugin.adoc index 028213dd5..c8ba94f28 100644 --- a/docs/src/docs/asciidoc/parts/asciidoctorj-epub-plugin.adoc +++ b/docs/src/docs/asciidoc/parts/asciidoctorj-epub-plugin.adoc @@ -1,5 +1,5 @@ [[asciidoctorj-epub-plugin,{asciidoctorj-name} EPUB plugin]] -== The AsciidoctorEpub Plugin += The AsciidoctorEpub Plugin INFO: As from version 3.3 support for KindleGen is dropped as Amazon no longer has the binary available for download. @@ -8,7 +8,7 @@ INFO: As from version 3.3 support for KindleGen is dropped as Amazon no longer h .build.gradle ---- plugins { - id 'org.asciidoctor.jvm.epub' version '{revnumber}' + id 'org.asciidoctor.jvm.epub' version '{release-version}' } ---- @@ -17,7 +17,7 @@ plugins { .build.gradle.kts ---- plugins { - id("org.asciidoctor.jvm.epub") version "{revnumber}" + id("org.asciidoctor.jvm.epub") version "{release-version}" } ---- When applying `org.asciidoctor.jvm.epub` it creates a single task of type `org.asciidoctor.gradle.jvm.epub.AsciidoctorEpubTask` which is then configured to: diff --git a/docs/src/docs/asciidoc/parts/asciidoctorj-gems-plugin.adoc b/docs/src/docs/asciidoc/parts/asciidoctorj-gems-plugin.adoc index 7d41affb9..ca4293c06 100644 --- a/docs/src/docs/asciidoc/parts/asciidoctorj-gems-plugin.adoc +++ b/docs/src/docs/asciidoc/parts/asciidoctorj-gems-plugin.adoc @@ -1,5 +1,5 @@ [[asciidoctorj-gems-plugin,AsciidoctorJ GEMs plugin]] -== Ruby GEM support += Ruby GEM support GEM support is simplified via the `org.asciidoctor.jvm.gems` plugin. @@ -8,7 +8,7 @@ GEM support is simplified via the `org.asciidoctor.jvm.gems` plugin. .build.gradle ---- plugins { - id 'org.asciidoctor.jvm.gems' version '{revnumber}' + id 'org.asciidoctor.jvm.gems' version '{release-version}' } repositories { @@ -35,6 +35,6 @@ asciidoctorj { .build.gradle.kts ---- plugins { - id("org.asciidoctor.jvm.gems") version "{revnumber}" + id("org.asciidoctor.jvm.gems") version "{release-version}" } ---- diff --git a/docs/src/docs/asciidoc/parts/asciidoctorj-leanpub-plugin.adoc b/docs/src/docs/asciidoc/parts/asciidoctorj-leanpub-plugin.adoc index 1cac5bd7f..3dd5d3707 100644 --- a/docs/src/docs/asciidoc/parts/asciidoctorj-leanpub-plugin.adoc +++ b/docs/src/docs/asciidoc/parts/asciidoctorj-leanpub-plugin.adoc @@ -1,9 +1,10 @@ [[asciidoctorj-leanpub-plugin,{asciidoctorj-name} Leanpub plugin]] -== The AsciidoctorLeanpub Plugin += The AsciidoctorLeanpub Plugin When applying `org.asciidoctor.jvm.leanpub` it creates a single task of type `org.asciidoctor.gradle.jvm.epub.AsciidoctorLeanTask` which is then configured to: -* Output source to "${buildDir}/docs/asciidocLeanpub" -* Set also a default version for `asciidoctor-leanpub-backend` artifact. To override set `asciidoctorj.leanpubVersion` or `asciidoctorLeanpub.asciidoctorj.leanpubVersion`. +* Output source to "${buildDir}/docs/asciidocLeanpub". +* Set also a default version for `asciidoctor-leanpub-backend` artifact. +To override set `asciidoctorj.leanpubVersion` or `asciidoctorLeanpub.asciidoctorj.leanpubVersion`. -If you use the traditional Dropbox mechanism of synchronising your writing to Dropbox you can apply the `org.asciidoctor.jvm.leanpub.dropbox-copy' plugn which will add a `copyAsciidocToDropbox` task which can copy your generated Leanpub content to the Dropbox folder which Leanpub has created for you. +If you use the traditional Dropbox mechanism of synchronising your writing to Dropbox you can apply the `org.asciidoctor.jvm.leanpub.dropbox-copy' plugin which will add a `copyAsciidocToDropbox` task which can copy your generated Leanpub content to the Dropbox folder which Leanpub has created for you. diff --git a/docs/src/docs/asciidoc/parts/asciidoctorj-pdf-plugin.adoc b/docs/src/docs/asciidoc/parts/asciidoctorj-pdf-plugin.adoc index 8676d2e2d..bc92dea38 100644 --- a/docs/src/docs/asciidoc/parts/asciidoctorj-pdf-plugin.adoc +++ b/docs/src/docs/asciidoc/parts/asciidoctorj-pdf-plugin.adoc @@ -1,13 +1,13 @@ :AsciidoctorPdfTask-url: {groovydoc-jvm}/AsciidoctorPdfTask.html [[asciidoctorj-pdf-plugin,AsciidoctorJ PDF plugin]] -== The AsciidoctorPdf Plugin += The AsciidoctorPdf Plugin [source,groovy,role="primary"] [subs=attributes+] .build.gradle ---- plugins { - id 'org.asciidoctor.jvm.pdf' version '{revnumber}' + id 'org.asciidoctor.jvm.pdf' version '{release-version}' } ---- @@ -16,7 +16,7 @@ plugins { .build.gradle.kts ---- plugins { - id("org.asciidoctor.jvm.pdf") version "{revnumber}" + id("org.asciidoctor.jvm.pdf") version "{release-version}" } ---- @@ -24,8 +24,8 @@ When applying `org.asciidoctor.jvm.pdf` it creates a single task of type `org.as The default task is named `asciidoctorPdf` and is configured to: -* Output source to "${buildDir}/docs/asciidocPdf" -* Not to copy any resources to the output directory +* Output source to "${buildDir}/docs/asciidocPdf". +* Not to copy any resources to the output directory. * It will set also a default version for `asciidoctorj-pdf` artifact. To override set `asciidoctorj.pdfVersion` or `asciidoctorPdf.asciidoctorj.pdfVersion`. The `AsciidoctorPdfTask` task type has the following additional methods: @@ -48,7 +48,7 @@ pdfThemes { } } ---- -<1> Local themes are registered using the `local` keyword and must be provided with a name +<1> Local themes are registered using the `local` keyword and must be provided with a name. <2> Directory for finding the theme. Specify a directory in any form acceptable to `project.file`. <3> Optional setting of the style name. If this is not set, the theme name provided previously will be used. diff --git a/docs/src/docs/asciidoc/parts/asciidoctorj-plugin.adoc b/docs/src/docs/asciidoc/parts/asciidoctorj-plugin.adoc index 2fd0d9a16..ef195f431 100644 --- a/docs/src/docs/asciidoc/parts/asciidoctorj-plugin.adoc +++ b/docs/src/docs/asciidoc/parts/asciidoctorj-plugin.adoc @@ -1,11 +1,11 @@ -== The New AsciidoctorJ Plugin += The New AsciidoctorJ Plugin [source,groovy,role="primary"] [subs=attributes+] .build.gradle ---- plugins { - id 'org.asciidoctor.jvm.convert' version '{revnumber}' + id 'org.asciidoctor.jvm.convert' version '{release-version}' } ---- @@ -14,13 +14,13 @@ plugins { .build.gradle.kts ---- plugins { - id("org.asciidoctor.jvm.convert") version "{revnumber}" + id("org.asciidoctor.jvm.convert") version "{release-version}" } ---- When applying `org.asciidoctor.jvm.convert` it creates a single task of type `org.asciidoctor.gradle.jvm.AsciidoctorTask` called `asciidoctor`. -By convention it sets the +By convention, it sets the * `sourceDir` to `src/docs/asciidoc` * `outputDir` to `${buildDir}/docs/asciidoc` diff --git a/docs/src/docs/asciidoc/parts/asciidoctorj-revealjs-plugin.adoc b/docs/src/docs/asciidoc/parts/asciidoctorj-revealjs-plugin.adoc index 15be8c7ba..fe894d560 100644 --- a/docs/src/docs/asciidoc/parts/asciidoctorj-revealjs-plugin.adoc +++ b/docs/src/docs/asciidoc/parts/asciidoctorj-revealjs-plugin.adoc @@ -1,12 +1,12 @@ [[asciidoctorj-revealjs-plugin,AsciidoctorJ Reveal.js plugin]] -== The AsciidoctorJ Reveal.js Plugin += The AsciidoctorJ Reveal.js Plugin [source,groovy,role="primary"] [subs=attributes+] .build.gradle ---- plugins { - id 'org.asciidoctor.jvm.revealjs' version '{revnumber}' + id 'org.asciidoctor.jvm.revealjs' version '{release-version}' } ---- @@ -15,7 +15,7 @@ plugins { .build.gradle.kts ---- plugins { - id("org.asciidoctor.jvm.revealjs") version "{revnumber}" + id("org.asciidoctor.jvm.revealjs") version "{release-version}" } ---- @@ -56,7 +56,7 @@ revealjs { If not specified, sensible defaults are provided. -=== Reveal.js Options +== Reveal.js Options [[RevealJsOptions]] Various options can be configured for Reveal.js. Although these can be set as attributes directly, it is far better to set them on the task as advantage can be taken of Gradle task caching and file resolving. @@ -109,7 +109,7 @@ processBar:: Display a presentation progress bar. Type is boolean. pushToHistory:: Push each slide change to the browser history. Type is boolean. -righttoLeft:: Change the presentation direction to be RTL. +rightToLeft:: Change the presentation direction to be RTL. Type is boolean. slideNumber:: Display the slide number of the current slide. Can be a `RevealJSOptions.SlideNumber`, a string value or a boolean. diff --git a/docs/src/docs/asciidoc/parts/asciidoctorjs-plugin.adoc b/docs/src/docs/asciidoc/parts/asciidoctorjs-plugin.adoc index 52c129450..ec808787a 100644 --- a/docs/src/docs/asciidoc/parts/asciidoctorjs-plugin.adoc +++ b/docs/src/docs/asciidoc/parts/asciidoctorjs-plugin.adoc @@ -1,12 +1,12 @@ [[asciidoctorjs-plugin,{asciidoctorjs-name} plugin]] -== Working with Asciidoctor.js instead += Working with Asciidoctor.js instead Instead of {asciidoctorj-name}, {asciidoctorjs-name} can be used as a rendering engine as from 3.0. The configuration follows much the same as for {asciidoctorj-name}, but will a couple of differences. -* Only HTML is supported out of the box -* The configurating extension is called `asciidoctorjs` and is available at both task and project level. +* Only HTML is supported out of the box. +* The configuration extension is called `asciidoctorjs` and is available at both task and project level. * Docbook must be enabled via `asciidoctorjs.modules.docbook.use()`. * The implementation runs node.js under the hood, but the user does not have to install anything. The plugin suite takes care of everything. * Additional NPM modules can be added via `asciidoctorj.require`. diff --git a/docs/src/docs/asciidoc/parts/common-task-configuration.adoc b/docs/src/docs/asciidoc/parts/common-task-configuration.adoc index f25df4fbe..a66aec581 100644 --- a/docs/src/docs/asciidoc/parts/common-task-configuration.adoc +++ b/docs/src/docs/asciidoc/parts/common-task-configuration.adoc @@ -1,4 +1,4 @@ -== Task Configuration += Task Configuration All Asciidoctor tasks will have the following methods and properties: @@ -199,11 +199,11 @@ resources 'es', { } ---- -=== Include directives and base directory +== Include directives and base directory These plugins do not change the way link:https://asciidoctor.org/docs/user-manual/#include-resolution[include::] directive works, but it is important to note how setting `baseDir` will affect top level includes. It is recommended that you always use `\{includedir}` as a prefix for the file path. This attribute is always set to the correct top-level folder where the sources will be located. -However it is not practical for everyone to use `\{includedir}` and as from 2.2.0 it is possible to add a strategy for controlling the base directory: +However, it is not practical for everyone to use `\{includedir}` and as from 2.2.0 it is possible to add a strategy for controlling the base directory: [source,groovy,role="primary"] .build.gradle @@ -220,11 +220,11 @@ asciidoctor { <3> The base directory will always the the same as the source directory. If an intermediate working directory is being used, the base directory will automatically point to that. <4> The base directory will be the same as the directory of each individual source file. -=== Docinfo processing +== Docinfo processing When using the `docinfo` attribute with `html` and `docbook` backends, it is recommended that `baseDirFollowsSourceDir()` is always set. This will ensure that the docinfo files are picked up correctly from the same directory that is the source directory. -=== Source language support +== Source language support Some scenarios work on a source set of documents in a primary language and then translations of those sources into other languages. The Gradle plugin simplifies this scenario by allowing a structure such as diff --git a/docs/src/docs/asciidoc/parts/compatibility.adoc b/docs/src/docs/asciidoc/parts/compatibility.adoc index 0da929c7c..d3335a649 100644 --- a/docs/src/docs/asciidoc/parts/compatibility.adoc +++ b/docs/src/docs/asciidoc/parts/compatibility.adoc @@ -1,4 +1,4 @@ -== Compatibility += Compatibility This collection of plugins requires at least Gradle 4.9, JDK 11.0 and AsciidoctorJ 2.0.0 to run. If you need prior Gradle, JDK or {asciidoctorj-name} support please use a plugin from the 1.5.x or 1.6.x release series. diff --git a/docs/src/docs/asciidoc/parts/docinfo.adoc b/docs/src/docs/asciidoc/parts/docinfo.adoc index a5c4c5a66..4c4f075fc 100644 --- a/docs/src/docs/asciidoc/parts/docinfo.adoc +++ b/docs/src/docs/asciidoc/parts/docinfo.adoc @@ -1,4 +1,4 @@ -== Extra content for HTML & Docbook backends += Extra content for HTML & Docbook backends You may need to include extra content into the head of the exported document. For example, you might want to include jQuery inside the `` element of the HTML export. diff --git a/docs/src/docs/asciidoc/parts/exporting-slides.adoc b/docs/src/docs/asciidoc/parts/exporting-slides.adoc index 5b3690acc..074ba43ca 100644 --- a/docs/src/docs/asciidoc/parts/exporting-slides.adoc +++ b/docs/src/docs/asciidoc/parts/exporting-slides.adoc @@ -1,5 +1,5 @@ [[decktape-plugin,Decktape plugin]] -== Exporting Slides += Exporting Slides If you have created HTML slides via an Asciidoctor task you can export them to PDF/PNG/JPG. @@ -45,8 +45,8 @@ If you do .build.gradle ---- plugins { - id 'org.asciidoctor.jvm.revealjs' version '{revnumber}' - id 'org.asciidoctor.decktape.base' version '{revnumber}' + id 'org.asciidoctor.jvm.revealjs' version '{release-version}' + id 'org.asciidoctor.decktape.base' version '{release-version}' } ---- @@ -55,8 +55,8 @@ plugins { .build.gradle.kts ---- plugins { - id("org.asciidoctor.jvm.revealjs") version "{revnumber}" - id("org.asciidoctor.decktape.base") version "{revnumber}" + id("org.asciidoctor.jvm.revealjs") version "{release-version}" + id("org.asciidoctor.decktape.base") version "{release-version}" } ---- diff --git a/docs/src/docs/asciidoc/parts/kindlegen-plugin.adoc b/docs/src/docs/asciidoc/parts/kindlegen-plugin.adoc index 8542a8049..dfb179000 100644 --- a/docs/src/docs/asciidoc/parts/kindlegen-plugin.adoc +++ b/docs/src/docs/asciidoc/parts/kindlegen-plugin.adoc @@ -1,11 +1,11 @@ -== Kindlegen plugin += Kindlegen plugin [source,groovy,role="primary"] [subs=attributes+] .build.gradle ---- plugins { - id 'org.asciidoctor.kindlegen.base' version '{revnumber}' + id 'org.asciidoctor.kindlegen.base' version '{release-version}' } ---- @@ -14,7 +14,7 @@ plugins { .build.gradle.kts ---- plugins { - id("org.asciidoctor.kindlegen.base") version "{revnumber}" + id("org.asciidoctor.kindlegen.base") version "{release-version}" } ---- diff --git a/docs/src/docs/asciidoc/parts/quick-start.adoc b/docs/src/docs/asciidoc/parts/quick-start.adoc index 237be3cfa..90ef2c6e4 100644 --- a/docs/src/docs/asciidoc/parts/quick-start.adoc +++ b/docs/src/docs/asciidoc/parts/quick-start.adoc @@ -1,4 +1,4 @@ -== Quick Start += Quick Start To start you need to use one of the plugins from the following Gradle snippet @@ -7,7 +7,7 @@ To start you need to use one of the plugins from the following Gradle snippet .build.gradle ---- plugins { - id 'org.asciidoctor.jvm.convert' version '{revnumber}' + id 'org.asciidoctor.jvm.convert' version '{release-version}' } ---- @@ -16,6 +16,6 @@ plugins { .build.gradle.kts ---- plugins { - id("org.asciidoctor.jvm.convert") version "{revnumber}" + id("org.asciidoctor.jvm.convert") version "{release-version}" } ---- diff --git a/docs/src/docs/asciidoc/parts/upgrading.adoc b/docs/src/docs/asciidoc/parts/upgrading.adoc index ed352524b..96e079df8 100644 --- a/docs/src/docs/asciidoc/parts/upgrading.adoc +++ b/docs/src/docs/asciidoc/parts/upgrading.adoc @@ -1,5 +1,4 @@ - -== Upgrading From Older Versions of Asciidoctor += Upgrading From Older Versions of Asciidoctor NOTE: If you are still on a 1.5/1.6 version of the plugin, upgrade to the latest 2.x version first. @@ -21,11 +20,11 @@ If you have {asciidoctorj-name} binary extensions you'll need to recompile them Substitutable attributes means that the build script author can change those attributes by setting them explicitly. -=== Asciidoctor compatibility tasks +== Asciidoctor compatibility tasks The Asciidoctor compatibility task has been removed. You need to use the Asciidoctor task from `org.asciidoctor.jvm.convert` instead. -=== GEMs +== GEMs If you used external GEMs via the http://jruby-gradle.github.io/[JRuby Gradle plugin], you should switch over to using `org.asciidoctor.jvm.gems` instead. You should also use the `asciidoctorGems` configuration rather than the `gems` configuration. Tasks should not depend on `JRubyPrepare`, but on `AsciidoctorGemsPrepare` instead. @@ -49,7 +48,7 @@ then change it to [subs=attributes+] ---- plugins { - id 'org.asciidoctor.jvm.gems' version '{revnumber}' + id 'org.asciidoctor.jvm.gems' version '{release-version}' } repositories { @@ -57,20 +56,20 @@ repositories { } ---- -=== Reveal.js +== Reveal.js Follows the same guidelines as for GEMS above. -=== Configurations +== Configurations The `asciidoctor` configuration is no longer available. If you used that before to make artifacts available on the classpath you should use the `configurations` method on the task to add them. If you used it to manipulate versions of {asciidoctorj-name} and JRuby then you should rather use the explicit versions settings on `asciidoctorj`. -=== Multiple Asciidoctor tasks +== Multiple Asciidoctor tasks If you have more than one Asciidoctor task, decide which `options`, `attributes` and `requires` should go in the `asciidoctorj` global project extension block and which should be customised within the tasks `asciidoctor` extension block. Importantly, you probably did `import org.asciidoctor.gradle.AsciidoctorTask`. You will need to change that to `import org.asciidoctor.gradle.jvm.AsciidoctorTask`. -=== Extensions +== Extensions Extensions on the Gradle classpath are no longer detected. You need to declare them explicitly. This includes any extensions created in `buildSrc`. From d78dabbaf39279753152091cbc6be025fdf1d9be Mon Sep 17 00:00:00 2001 From: Abel Salgado Romero Date: Tue, 5 Mar 2024 15:20:05 +0100 Subject: [PATCH 02/10] Remove unused attributes --- README.adoc | 26 +++++-------------------- docs/src/docs/asciidoc/attributes.adoc | 27 +++++++++++--------------- docs/src/docs/asciidoc/index.adoc | 6 ++++-- 3 files changed, 20 insertions(+), 39 deletions(-) diff --git a/README.adoc b/README.adoc index 4810eb9de..828a328c6 100644 --- a/README.adoc +++ b/README.adoc @@ -1,24 +1,9 @@ = Asciidoctor Gradle Plugin Andres Almiray -:version: 4.0.0 -:version-published: 4.0.0-alpha.1 -:asciidoc-url: http://asciidoc.org -:asciidoctor-url: http://asciidoctor.org -:issues: https://github.com/asciidoctor/asciidoctor-gradle-plugin/issues +:asciidoc-url: https://asciidoc.org +:asciidoctor-url: https://asciidoctor.org :gradle-url: http://gradle.org/ -:asciidoctor-maven-plugin: https://github.com/asciidoctor/asciidoctor-maven-plugin -:kotlindsl: https://github.com/gradle/kotlin-dsl[Gradle Kotlin DSL] -:lightguard: https://github.com/LightGuard -:asciidoctorj: https://github.com/asciidoctor/asciidoctorj -:asciidoctorj-name: AsciidoctorJ -:asciidoctorjs-name: Asciidoctor.js -:asciidoctorj-epub-name: Asciidoctorj-EPUB -:asciidoctorj-pdf-name: Asciidoctorj-PDF -:lordofthejars: https://github.com/lordofthejars -:asciidoctor-docs: http://asciidoctor.org/docs/ :asciidoctor-development-docs: https://asciidoctor.github.io/asciidoctor-gradle-plugin/ -:plugin-name: Asciidoctor Gradle plugin -:project-name: asciidoctor-gradle-plugin :project-full-path: asciidoctor/asciidoctor-gradle-plugin :github-branch: master :linkattrs: @@ -36,9 +21,9 @@ ifdef::env-github[] endif::[] ifdef::status[] -image:https://github.com/asciidoctor/asciidoctor-gradle-plugin/workflows/Build/badge.svg[GitHub Actions Status, link=https://github.com/asciidoctor/asciidoctor-gradle-plugin/actions] -image:http://img.shields.io/coveralls/{project-full-path}/{github-branch}.svg[Coverage Status, link=https://coveralls.io/r/{project-full-path}] -image:http://img.shields.io/badge/license-ASF2-blue.svg[Apache License 2, link=http://www.apache.org/licenses/LICENSE-2.0.txt] +image:https://github.com/asciidoctor/asciidoctor-gradle-plugin/workflows/Build/badge.svg[GitHub Actions Status,link=https://github.com/asciidoctor/asciidoctor-gradle-plugin/actions] +image:http://img.shields.io/coveralls/{project-full-path}/{github-branch}.svg[Coverage Status,link=https://coveralls.io/r/{project-full-path}] +image:http://img.shields.io/badge/license-ASF2-blue.svg[Apache License 2,link=http://www.apache.org/licenses/LICENSE-2.0.txt] image:https://gitlab.com/asciidoctor/asciidoctor-gradle-plugin/badges/master/pipeline.svg[link="https://gitlab.com/asciidoctor/asciidoctor-gradle-plugin/commits/master",title="pipeline status"] endif::[] @@ -54,4 +39,3 @@ 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. endif::[] - diff --git a/docs/src/docs/asciidoc/attributes.adoc b/docs/src/docs/asciidoc/attributes.adoc index 222475efc..501a75d3a 100644 --- a/docs/src/docs/asciidoc/attributes.adoc +++ b/docs/src/docs/asciidoc/attributes.adoc @@ -1,25 +1,20 @@ -:asciidoc-url: http://asciidoc.org -:asciidoctor-docs: http://asciidoctor.org/docs/ -:asciidoctor-userguide: {asciidoctor-docs}user-manual/ -:asciidoctor-userguide-name: Asciidoctor User Manual -:asciidoctor-maven-plugin: https://github.com/asciidoctor/asciidoctor-maven-plugin[Asciidoctor Maven Plugin] -:asciidoctor-url: http://asciidoctor.org -:asciidoctorj: https://github.com/asciidoctor/asciidoctorj -:asciidoctorj-name: AsciidoctorJ +:project-name: asciidoctor-gradle-plugin +:project-full-path: asciidoctor/asciidoctor-gradle-plugin +:plugin-name: Asciidoctor Gradle plugin +:asciidoc-url: https://asciidoc.org +:asciidoctor-docs: https://docs.asciidoctor.org/asciidoctor/latest/ +:asciidoctor-maven-plugin-name: Asciidoctor Maven Plugin +:asciidoctor-maven-plugin-url: https://github.com/asciidoctor/asciidoctor-maven-plugin +:asciidoctor-url: https://asciidoctor.org :asciidoctorj-epub-name: Asciidoctorj-EPUB +:asciidoctorj-name: AsciidoctorJ :asciidoctorj-pdf-name: Asciidoctorj-PDF -:asciidoctorj-pdf-leanpub: Asciidoctorj Leanpub +:asciidoctorj-url: https://github.com/asciidoctor/asciidoctorj :asciidoctorjs-name: Asciidoctor.js -:gradle-url: http://gradle.org/ -:icons: font -:issues: https://github.com/asciidoctor/asciidoctor-gradle-plugin/issues/ +:gradle-url: https://gradle.org/ :issues-asciidoctorj: https://github.com/asciidoctor/asciidoctorj/issues/ :issues-jruby: https://github.com/asciidoctor/asciidoctorj/issues/ :jruby-name: JRuby :kotlindsl: https://github.com/gradle/kotlin-dsl[Gradle Kotlin DSL] :lightguard: https://github.com/LightGuard[Jason Porter] -:linkattrs: :lordofthejars: https://github.com/lordofthejars[Alex Soto] -:plugin-name: Asciidoctor Gradle plugin -:project-full-path: asciidoctor/asciidoctor-gradle-plugin -:project-name: asciidoctor-gradle-plugin diff --git a/docs/src/docs/asciidoc/index.adoc b/docs/src/docs/asciidoc/index.adoc index 5f691eb49..f4f2736a0 100644 --- a/docs/src/docs/asciidoc/index.adoc +++ b/docs/src/docs/asciidoc/index.adoc @@ -1,16 +1,18 @@ = Asciidoctor Gradle Plugin Suite include::attributes.adoc[] +:icons: font +:leveloffset: +1 +:linkattrs: ifdef::env-idea[] :toc: preamble endif::[] ifeval::[{env}!=idea] :toc: right endif::[] -:leveloffset: +1 The {doctitle} is the official means of using {asciidoctor-url}[Asciidoctor] to convert all your {asciidoc-url}[AsciiDoc] documentation using {gradle-url}[Gradle]. -This started as a port of the {asciidoctor-maven-plugin} project founded by {lightguard} and relies on {asciidoctorj}[{asciidoctorj-name}] which was founded by {lordofthejars}. +This started as a port of the {asciidoctor-maven-plugin-url}[asciidoctor-maven-plugin-name] project founded by {lightguard} and relies on {asciidoctorj-url}[{asciidoctorj-name}] which was founded by {lordofthejars}. In fact the 1.5.x series of the {plugin-name} can still be considered a port. However, with 2.x series came a complete departure with functionality far exceeding any lightweight markup plugins for any other build tool. With the 3.x serious allows for even more flexibility and options for the creation of a true DocuOps pipeline by bringing together Gradle as a powerful and generic build tool, and Asciidoctor as an agile and lightweight document generator. From e60d7c18709572560c80158c151224e6d40bf371 Mon Sep 17 00:00:00 2001 From: Abel Salgado Romero Date: Tue, 5 Mar 2024 15:20:21 +0100 Subject: [PATCH 03/10] docinfo.adoc fixes --- docs/src/docs/asciidoc/parts/docinfo.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/src/docs/asciidoc/parts/docinfo.adoc b/docs/src/docs/asciidoc/parts/docinfo.adoc index 4c4f075fc..86694335d 100644 --- a/docs/src/docs/asciidoc/parts/docinfo.adoc +++ b/docs/src/docs/asciidoc/parts/docinfo.adoc @@ -16,9 +16,9 @@ Then, add the `docinfo1` attribute to the attributes list in the previous exampl .build.gradle ---- asciidoctorj { // <1> - attribute 'docinfo1', '' + attribute 'docinfo', '' } ---- <1> Substitute `asciidoctorjs` if you are using the {asciidoctorjs-name} engine. -See link:{asciidoctor-userguide}#docinfo-file[{asciidoctor-userguide-name}] for more information on `docinfo` and friends. +See link:{asciidoctor-docs}/docinfo/[Asciidoctor's Docinfo File] for more information on `docinfo` and friends. From 81c41ffed76849c55b65ba66633ca3226c07c9ef Mon Sep 17 00:00:00 2001 From: Abel Salgado Romero Date: Tue, 5 Mar 2024 21:37:06 +0100 Subject: [PATCH 04/10] Fix revealJsOptions reference and invalid attributes/options references --- ...stractImplementationEngineExtension.groovy | 3 +- docs/antora/antora.yml | 13 +++--- docs/src/docs/asciidoc/attributes.adoc | 3 +- docs/src/docs/asciidoc/index.adoc | 4 +- .../parts/asciidoctorj-base-plugin.adoc | 10 ++--- .../parts/asciidoctorj-revealjs-plugin.adoc | 4 +- .../parts/common-task-configuration.adoc | 40 ++++++++++++------- .../gradle/jvm/AsciidoctorJExtension.groovy | 3 +- 8 files changed, 45 insertions(+), 35 deletions(-) diff --git a/base/src/main/groovy/org/asciidoctor/gradle/base/AbstractImplementationEngineExtension.groovy b/base/src/main/groovy/org/asciidoctor/gradle/base/AbstractImplementationEngineExtension.groovy index 7c53cfe94..d21e296b0 100644 --- a/base/src/main/groovy/org/asciidoctor/gradle/base/AbstractImplementationEngineExtension.groovy +++ b/base/src/main/groovy/org/asciidoctor/gradle/base/AbstractImplementationEngineExtension.groovy @@ -52,7 +52,8 @@ class AbstractImplementationEngineExtension tag::extension-property[] attributes:: Asciidoctor attributes. Use `attributes` to append and `setAttributes` to replace any current attributes with a new set. - Attribute values are lazy-evaluated to strings. See <> for more detail. + Attribute values are lazy-evaluated to strings. + See <> for more detail. end::extension-property[] ------------------------- */ diff --git a/docs/antora/antora.yml b/docs/antora/antora.yml index 20067859e..6ccfd8187 100644 --- a/docs/antora/antora.yml +++ b/docs/antora/antora.yml @@ -8,20 +8,17 @@ asciidoc: project-full-path: asciidoctor/asciidoctor-gradle-plugin plugin-name: Asciidoctor Gradle plugin asciidoc-url: https://asciidoc.org - asciidoc-userguide: https://docs.asciidoctor.org/asciidoc/latest/ - asciidoctor-docs: https://docs.asciidoctor.org/ - asciidoctor-maven-plugin: https://github.com/asciidoctor/asciidoctor-maven-plugin[Asciidoctor Maven Plugin] + asciidoc-docs: https://docs.asciidoctor.org/asciidoc/latest + asciidoctor-docs: https://docs.asciidoctor.org/asciidoctor/latest + asciidoctor-maven-plugin-name: Asciidoctor Maven Plugin + asciidoctor-maven-plugin-url: https://github.com/asciidoctor/asciidoctor-maven-plugin asciidoctor-url: https://asciidoctor.org - asciidoctor-userguide: https://docs.asciidoctor.org/asciidoctor/latest/ asciidoctorj-epub-name: Asciidoctorj-EPUB asciidoctorj-name: AsciidoctorJ - asciidoctorj-pdf-leanpub: Asciidoctorj Leanpub asciidoctorj-pdf-name: Asciidoctorj-PDF - asciidoctorj: https://github.com/asciidoctor/asciidoctorj + asciidoctorj-url: https://github.com/asciidoctor/asciidoctorj asciidoctorjs-name: Asciidoctor.js - groovy-dsl-name: Groovy DSL gradle-url: https://gradle.org/ - issues: https://github.com/asciidoctor/asciidoctor-gradle-plugin/issues/ issues-asciidoctorj: https://github.com/asciidoctor/asciidoctorj/issues/ issues-jruby: https://github.com/asciidoctor/asciidoctorj/issues/ jruby-name: JRuby diff --git a/docs/src/docs/asciidoc/attributes.adoc b/docs/src/docs/asciidoc/attributes.adoc index 501a75d3a..9750e96d5 100644 --- a/docs/src/docs/asciidoc/attributes.adoc +++ b/docs/src/docs/asciidoc/attributes.adoc @@ -2,7 +2,8 @@ :project-full-path: asciidoctor/asciidoctor-gradle-plugin :plugin-name: Asciidoctor Gradle plugin :asciidoc-url: https://asciidoc.org -:asciidoctor-docs: https://docs.asciidoctor.org/asciidoctor/latest/ +:asciidoc-docs: https://docs.asciidoctor.org/asciidoc/latest +:asciidoctor-docs: https://docs.asciidoctor.org/asciidoctor/latest :asciidoctor-maven-plugin-name: Asciidoctor Maven Plugin :asciidoctor-maven-plugin-url: https://github.com/asciidoctor/asciidoctor-maven-plugin :asciidoctor-url: https://asciidoctor.org diff --git a/docs/src/docs/asciidoc/index.adoc b/docs/src/docs/asciidoc/index.adoc index f4f2736a0..17251c2ad 100644 --- a/docs/src/docs/asciidoc/index.adoc +++ b/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[] diff --git a/docs/src/docs/asciidoc/parts/asciidoctorj-base-plugin.adoc b/docs/src/docs/asciidoc/parts/asciidoctorj-base-plugin.adoc index dbba3bc8f..0b3ec6ccd 100644 --- a/docs/src/docs/asciidoc/parts/asciidoctorj-base-plugin.adoc +++ b/docs/src/docs/asciidoc/parts/asciidoctorj-base-plugin.adoc @@ -48,8 +48,7 @@ The following common entities can also be set: include::{plugin-base}/main/groovy/org/asciidoctor/gradle/base/AbstractImplementationEngineExtension.groovy[indent=0,tags="extension-property"] // TODO: Split attributes into a standalone section that is not part of base plugin. -[[attributes,Setting Attributes]] -[[options,Setting Options]] +[#options-and-attributes] == Options & Attributes The following options may be set using the extension's `options` property @@ -108,10 +107,9 @@ These attributes may be overridden by explicit user input. Refer to the {asciidoctor-docs}[Asciidoctor documentation] to learn more about these options and attributes. -Attribute values defined on the build file will win over values defined on the documents themselves. You can change -this behavior by appending an `@` at the end of the value when defined in the build file. Please refer to -link:{asciidoctor-userguide}#attribute-assignment-precedence[Attribute assignment precedence, window="_blank"] -for more information. +Attribute values defined on the build file will win over values defined on the documents themselves. +You can change this behavior by appending an `@` at the end of the value when defined in the build file. +Please refer to link:{asciidoc-docs}/attributes/assignment-precedence#altering-the-assignment-precedence[Attribute assignment precedence, window="_blank"] for more information. [[asciidoctorj-modules,{asciidoctorj-name} Modules]] == Versions of modules diff --git a/docs/src/docs/asciidoc/parts/asciidoctorj-revealjs-plugin.adoc b/docs/src/docs/asciidoc/parts/asciidoctorj-revealjs-plugin.adoc index fe894d560..23d377420 100644 --- a/docs/src/docs/asciidoc/parts/asciidoctorj-revealjs-plugin.adoc +++ b/docs/src/docs/asciidoc/parts/asciidoctorj-revealjs-plugin.adoc @@ -32,7 +32,7 @@ The `AsciidoctorRevealJSTask` task type has the following additional methods: [horizontal] revealjsOptions:: Configure special Reveal.js options. - Can be configured via Closure or Action. See <> for more details. + Can be configured via Closure or Action. See <> for more details. templateDir:: Location where the template directory will be located on disk before Asciidoctor processing starts. theme:: The Reveal.js theme to use. The theme must match one from the template. @@ -56,8 +56,8 @@ revealjs { If not specified, sensible defaults are provided. -== Reveal.js Options [[RevealJsOptions]] +== Reveal.js Options Various options can be configured for Reveal.js. Although these can be set as attributes directly, it is far better to set them on the task as advantage can be taken of Gradle task caching and file resolving. diff --git a/docs/src/docs/asciidoc/parts/common-task-configuration.adoc b/docs/src/docs/asciidoc/parts/common-task-configuration.adoc index a66aec581..68ac0bdfd 100644 --- a/docs/src/docs/asciidoc/parts/common-task-configuration.adoc +++ b/docs/src/docs/asciidoc/parts/common-task-configuration.adoc @@ -5,7 +5,8 @@ All Asciidoctor tasks will have the following methods and properties: .Properties and methods common all {asciidoctorj-name} tasks [horizontal] asciidoctorj:: a task extension which allows a task to extend of override global configuration for Asciidoctor tasks. - This allow extensive flexibility. Any thing that can be configured in the global `asciidoctorj` extension can also be configured here. + This allows extensive flexibility. + Any thing that can be configured in the global `asciidoctorj` extension can also be configured here. attributes:: A shortcut for `asciidoctorj.attributes` and `asciidoctorjs.attributes`. baseDir:: Base directory for asciidoctor document conversion and root document inclusion. The base directory will be the project directory by default, but can be set to any other directory. @@ -29,10 +30,12 @@ outputDir:: where generated docs go. Type: File, but any object convertible with `project.file` can be passed. Default: `$buildDir/asciidoc`. parallelMode:: Specifies whether each backend or other variant of a converting tasks should be run in parallel or sequential. - Sequential conversions might have less initialisation overhead, but may suffer from `gemPath` and extension pollution. Default: `true` (parallel). + Sequential conversions might have less initialisation overhead, but may suffer from `gemPath` and extension pollution. + Default: `true` (parallel). resources:: specify which additional files (image etc.) must be copied to output directory using a http://www.gradle.org/docs/current/javadoc/org/gradle/api/file/CopySpec.html[CopySpec]. -secondarySources: Specify which source files should be monitor for change. These are typically files which are included by top-level files as well as doctype files. +secondarySources:: Specify which source files should be monitored for change. + These are typically files which are included by top-level files as well as doctype files. Default: All files in sourceDir which matches `getDefaultSourceDocumentPattern()` as well as doctype files. sourceDir:: where the asciidoc sources are. Use either `sourceDir path`, `setSourceDir path` or `sourceDir=path` @@ -41,9 +44,13 @@ sourceDir:: where the asciidoc sources are. sources:: Specify which Asciidoctor source files to include as toplevel documents. It uses an http://www.gradle.org/docs/current/javadoc/org/gradle/api/tasks/util/PatternSet.html[Ant-style PatternSet]. useIntermediateWorkDir:: Use an intermediate work directory for sources ances. - Some extensions such as `ditaa` will write content into the source directory. In order to keep the project source directory pristine an intermediate work directory can be used. All sources and resources will be copied there prior the executing Asciidoctor. + Some extensions such as `ditaa` will write content into the source directory. + In order to keep the project source directory pristine an intermediate work directory can be used. + All sources and resources will be copied there prior the executing Asciidoctor. withIntermediateArtifacts:: Add intermediate artifacts to output directory. - If the document conversion process creates intermediate artifacts which needs to be added to the output directory, then the pattern set with a closure or `Action`. This implies `useIntermediateWorkDir`. An example of such a case is the use of `ditaa`. + If the document conversion process creates intermediate artifacts which needs to be added to the output directory, then the pattern set with a closure or `Action`. + This implies `useIntermediateWorkDir`. + An example of such a case is the use of `ditaa`. IMPORTANT: You will have to configure the properties for each plugin as they are not inherited from one to another. For example you will have to configure `languages` for both `org.asciidoctor.jvm.convert` and `org.asciidoctor.jvm.pdf` plugins if you want multi language pdf and html. @@ -61,7 +68,7 @@ backends:: the backends to use. separateOutputDirs:: specifies whether each backend should use a separate subfolder under `outputDir`. Default: `true` -=== Defining Sources +== Defining Sources The plugin will search for sources under `sourceDir`. Sources may have any of the following extensions in order to be discovered: @@ -104,7 +111,7 @@ tasks { Paths defined in this PatternSet are resolved relative to the `sourceDir`. -=== Processing Auxiliary Files +== Processing Auxiliary Files Some backends require that additional files be copied across. The most common example are images for HTML backends. For this the `resources` method is used. It is provided with a closure that configures an org.asciidoctor.gradle.jvm.epub.internal @@ -181,7 +188,7 @@ If you do not want this behaviour, then it can be turned off by doing copyNoResources() ---- -If you are using multiple languages and you have identical resource patterns for each languages within `sourceDir/${lang}` you need to explicitly declare those on a per-language basis: +If you are using multiple languages and you have identical resource patterns for each language within `sourceDir/${lang}` you need to explicitly declare those on a per-language basis: [source,groovy,role="primary"] .build.gradle @@ -222,11 +229,13 @@ asciidoctor { == Docinfo processing -When using the `docinfo` attribute with `html` and `docbook` backends, it is recommended that `baseDirFollowsSourceDir()` is always set. This will ensure that the docinfo files are picked up correctly from the same directory that is the source directory. +When using the `docinfo` attribute with `html` and `docbook` backends, it is recommended that `baseDirFollowsSourceDir()` is always set. +This will ensure that the docinfo files are picked up correctly from the same directory that is the source directory. == Source language support -Some scenarios work on a source set of documents in a primary language and then translations of those sources into other languages. The Gradle plugin simplifies this scenario by allowing a structure such as +Some scenarios work on a source set of documents in a primary language and then translations of those sources into other languages. +The Gradle plugin simplifies this scenario by allowing a structure such as [source] ---- @@ -247,7 +256,9 @@ asciidoctor { } ---- -Gradle will then process both the `en` and the `es` source set and output to the output directory using the same languages names. Intermediate working directories and multiple backends are also covered. In this case the `lang` attribute will be injected with the specific language as the value. +Gradle will then process both the `en` and the `es` source set and output to the output directory using the same languages names. +Intermediate working directories and multiple backends are also covered. +In this case the `lang` attribute will be injected with the specific language as the value. It is also possible to specify additional attributes that will only be added when a specific language is processed @@ -260,17 +271,18 @@ asciidoctorj { // <1> asciidoctorjs { // <2> attributesForLang 'en', langName : 'English' - attributesForLang 'ca', langName : 'Catala' + attributesForLang 'ca', langName : 'Catala'F } ---- <1> Configuration when using {asciidoctorj-name} <2> Configuration when using {asciidoctorjs-name} -=== Choosing a Process Mode for {asciidoctorj-name} +== Choosing a Process Mode for {asciidoctorj-name} All {asciidoctorj-name}-based tasks can control how Asciidoctor conversions are being run via the `inProcess` property. This is early days, and a choice for your build will depend very much on your context, but the following has already become clear: * `IN_PROCESS` and `OUT_OF_PROCESS` should theoretically run faster, especially if you continuously rebuild the same documentation. Gradle workers are the underlying implementation for these two options * The safe option is always `JAVA_EXEC`. For lower memory consumption this is by far the safer option. (It is also the only way we can get the Windows-based tests for this plugin to complete on Appveyor & Travis CI). It you run a lot of builds the penalty start-up time might become an issue for you. -NOTE: In certain cases the plugin will overrule your choice as it has some built-in rules for special cases. In such cases it will log a warning that it has done that. +NOTE: In certain cases the plugin will overrule your choice as it has some built-in rules for special cases. +In such cases it will log a warning that it has done that. diff --git a/jvm/src/main/groovy/org/asciidoctor/gradle/jvm/AsciidoctorJExtension.groovy b/jvm/src/main/groovy/org/asciidoctor/gradle/jvm/AsciidoctorJExtension.groovy index 00b57d168..0467565b7 100644 --- a/jvm/src/main/groovy/org/asciidoctor/gradle/jvm/AsciidoctorJExtension.groovy +++ b/jvm/src/main/groovy/org/asciidoctor/gradle/jvm/AsciidoctorJExtension.groovy @@ -481,7 +481,8 @@ class AsciidoctorJExtension extends AbstractImplementationEngineExtension { tag::extension-property[] options:: {asciidoctorj-name} options. Use `options` to append and `setOptions` to replace any current options with a new set. - Options are evaluated as late as possible. See <> for more details. + Options are evaluated as late as possible. + See <> for more details. end::extension-property[] ------------------------- */ From 6f21ce56fece86fbf6dbfc49231542ad9e310310 Mon Sep 17 00:00:00 2001 From: Abel Salgado Romero Date: Tue, 5 Mar 2024 22:09:32 +0100 Subject: [PATCH 05/10] Prepare appendices Antora module * Update hacking with branch description from README --- docs/antora/antora.yml | 3 +- docs/antora/docs/modules/ROOT/nav.adoc | 6 +- .../modules/appendices/pages/hacking.adoc | 10 +++ .../appendices/pages/known-limitations.adoc | 9 +++ .../appendices/pages/tips-and-tricks.adoc | 75 +++++++++++++++++++ docs/src/docs/asciidoc/appendix/hacking.adoc | 9 ++- docs/src/docs/asciidoc/attributes.adoc | 3 +- docs/src/docs/asciidoc/index.adoc | 4 +- 8 files changed, 112 insertions(+), 7 deletions(-) create mode 100644 docs/antora/docs/modules/appendices/pages/hacking.adoc create mode 100644 docs/antora/docs/modules/appendices/pages/known-limitations.adoc create mode 100644 docs/antora/docs/modules/appendices/pages/tips-and-tricks.adoc diff --git a/docs/antora/antora.yml b/docs/antora/antora.yml index 6ccfd8187..6f1aaba50 100644 --- a/docs/antora/antora.yml +++ b/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 diff --git a/docs/antora/docs/modules/ROOT/nav.adoc b/docs/antora/docs/modules/ROOT/nav.adoc index 1950d77c5..3974edcf5 100644 --- a/docs/antora/docs/modules/ROOT/nav.adoc +++ b/docs/antora/docs/modules/ROOT/nav.adoc @@ -1,4 +1,5 @@ * xref:compatibility.adoc[] +* xref:compatibility.adoc[] * xref:quick-start.adoc[] * xref:common-task-configuration.adoc[] * xref:asciidoctorj-base-plugin.adoc[] @@ -6,11 +7,12 @@ * 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[] diff --git a/docs/antora/docs/modules/appendices/pages/hacking.adoc b/docs/antora/docs/modules/appendices/pages/hacking.adoc new file mode 100644 index 000000000..ecfc718ef --- /dev/null +++ b/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. diff --git a/docs/antora/docs/modules/appendices/pages/known-limitations.adoc b/docs/antora/docs/modules/appendices/pages/known-limitations.adoc new file mode 100644 index 000000000..477ce526c --- /dev/null +++ b/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]). diff --git a/docs/antora/docs/modules/appendices/pages/tips-and-tricks.adoc b/docs/antora/docs/modules/appendices/pages/tips-and-tricks.adoc new file mode 100644 index 000000000..f3d7d4258 --- /dev/null +++ b/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' + } +} +---- diff --git a/docs/src/docs/asciidoc/appendix/hacking.adoc b/docs/src/docs/asciidoc/appendix/hacking.adoc index e54682de0..6d9f2f6b4 100644 --- a/docs/src/docs/asciidoc/appendix/hacking.adoc +++ b/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. diff --git a/docs/src/docs/asciidoc/attributes.adoc b/docs/src/docs/asciidoc/attributes.adoc index 9750e96d5..797d52847 100644 --- a/docs/src/docs/asciidoc/attributes.adoc +++ b/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 diff --git a/docs/src/docs/asciidoc/index.adoc b/docs/src/docs/asciidoc/index.adoc index 17251c2ad..86473b354 100644 --- a/docs/src/docs/asciidoc/index.adoc +++ b/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[] From 99675b20da1e3a5713a537b57be37bd89bf4a741 Mon Sep 17 00:00:00 2001 From: Abel Salgado Romero Date: Wed, 6 Mar 2024 22:21:29 +0100 Subject: [PATCH 06/10] WIP: testing --- docs/antora/antora.yml | 9 ++- docs/antora/modules/ROOT/examples/base | 1 + docs/antora/modules/ROOT/examples/jvm | 1 + docs/antora/{docs => }/modules/ROOT/nav.adoc | 4 +- .../ROOT/pages}/asciidoctor-diagram.adoc | 1 - .../asciidoctoreditorconfig-plugin.adoc | 0 .../ROOT/pages}/asciidoctorj-base-plugin.adoc | 17 +++-- .../asciidoctorj-compatiblity-plugin.adoc | 0 .../asciidoctorj-custom-extensions.adoc | 1 - .../ROOT/pages}/asciidoctorj-epub-plugin.adoc | 5 +- .../ROOT/pages}/asciidoctorj-gems-plugin.adoc | 3 +- .../pages}/asciidoctorj-leanpub-plugin.adoc | 5 +- .../ROOT/pages}/asciidoctorj-pdf-plugin.adoc | 6 +- .../ROOT/pages}/asciidoctorj-plugin.adoc | 6 +- .../pages}/asciidoctorj-revealjs-plugin.adoc | 7 +- .../ROOT/pages}/asciidoctorjs-plugin.adoc | 3 +- .../pages}/common-task-configuration.adoc | 2 +- .../modules/ROOT/pages}/compatibility.adoc | 0 .../modules/ROOT/pages}/docinfo.adoc | 0 .../modules/ROOT/pages}/exporting-slides.adoc | 6 +- docs/antora/modules/ROOT/pages/index.adoc | 10 +++ .../modules/ROOT/pages}/kindlegen-plugin.adoc | 0 .../modules/ROOT/pages}/quick-start.adoc | 0 .../modules/ROOT/pages}/upgrading.adoc | 0 .../{docs => }/modules/appendices/nav.adoc | 0 .../modules/appendices/pages/hacking.adoc | 0 .../appendices/pages/known-limitations.adoc | 0 .../appendices/pages/tips-and-tricks.adoc | 0 docs/antora/modules/file.adoc | 1 + docs/src/docs/asciidoc/appendix/hacking.adoc | 11 --- .../asciidoc/appendix/known-limitations.adoc | 10 --- .../asciidoc/appendix/tips-and-tricks.adoc | 76 ------------------- docs/src/docs/asciidoc/attributes.adoc | 22 ------ docs/src/docs/asciidoc/index.adoc | 58 -------------- 34 files changed, 48 insertions(+), 217 deletions(-) create mode 120000 docs/antora/modules/ROOT/examples/base create mode 120000 docs/antora/modules/ROOT/examples/jvm rename docs/antora/{docs => }/modules/ROOT/nav.adoc (95%) rename docs/{src/docs/asciidoc/parts => antora/modules/ROOT/pages}/asciidoctor-diagram.adoc (99%) rename docs/{src/docs/asciidoc/parts => antora/modules/ROOT/pages}/asciidoctoreditorconfig-plugin.adoc (100%) rename docs/{src/docs/asciidoc/parts => antora/modules/ROOT/pages}/asciidoctorj-base-plugin.adoc (78%) rename docs/{src/docs/asciidoc/parts => antora/modules/ROOT/pages}/asciidoctorj-compatiblity-plugin.adoc (100%) rename docs/{src/docs/asciidoc/parts => antora/modules/ROOT/pages}/asciidoctorj-custom-extensions.adoc (98%) rename docs/{src/docs/asciidoc/parts => antora/modules/ROOT/pages}/asciidoctorj-epub-plugin.adoc (89%) rename docs/{src/docs/asciidoc/parts => antora/modules/ROOT/pages}/asciidoctorj-gems-plugin.adoc (91%) rename docs/{src/docs/asciidoc/parts => antora/modules/ROOT/pages}/asciidoctorj-leanpub-plugin.adoc (80%) rename docs/{src/docs/asciidoc/parts => antora/modules/ROOT/pages}/asciidoctorj-pdf-plugin.adoc (93%) rename docs/{src/docs/asciidoc/parts => antora/modules/ROOT/pages}/asciidoctorj-plugin.adoc (87%) rename docs/{src/docs/asciidoc/parts => antora/modules/ROOT/pages}/asciidoctorj-revealjs-plugin.adoc (94%) rename docs/{src/docs/asciidoc/parts => antora/modules/ROOT/pages}/asciidoctorjs-plugin.adoc (78%) rename docs/{src/docs/asciidoc/parts => antora/modules/ROOT/pages}/common-task-configuration.adoc (98%) rename docs/{src/docs/asciidoc/parts => antora/modules/ROOT/pages}/compatibility.adoc (100%) rename docs/{src/docs/asciidoc/parts => antora/modules/ROOT/pages}/docinfo.adoc (100%) rename docs/{src/docs/asciidoc/parts => antora/modules/ROOT/pages}/exporting-slides.adoc (87%) create mode 100644 docs/antora/modules/ROOT/pages/index.adoc rename docs/{src/docs/asciidoc/parts => antora/modules/ROOT/pages}/kindlegen-plugin.adoc (100%) rename docs/{src/docs/asciidoc/parts => antora/modules/ROOT/pages}/quick-start.adoc (100%) rename docs/{src/docs/asciidoc/parts => antora/modules/ROOT/pages}/upgrading.adoc (100%) rename docs/antora/{docs => }/modules/appendices/nav.adoc (100%) rename docs/antora/{docs => }/modules/appendices/pages/hacking.adoc (100%) rename docs/antora/{docs => }/modules/appendices/pages/known-limitations.adoc (100%) rename docs/antora/{docs => }/modules/appendices/pages/tips-and-tricks.adoc (100%) create mode 100644 docs/antora/modules/file.adoc delete mode 100644 docs/src/docs/asciidoc/appendix/hacking.adoc delete mode 100644 docs/src/docs/asciidoc/appendix/known-limitations.adoc delete mode 100644 docs/src/docs/asciidoc/appendix/tips-and-tricks.adoc delete mode 100644 docs/src/docs/asciidoc/attributes.adoc delete mode 100644 docs/src/docs/asciidoc/index.adoc diff --git a/docs/antora/antora.yml b/docs/antora/antora.yml index 6f1aaba50..7811dcac5 100644 --- a/docs/antora/antora.yml +++ b/docs/antora/antora.yml @@ -1,6 +1,6 @@ name: gradle-plugin title: Gradle Plugin Suite -version: 4.0 +version: '4.0' asciidoc: attributes: release-version: 4.0.2 @@ -14,11 +14,14 @@ asciidoc: asciidoctor-maven-plugin-name: Asciidoctor Maven Plugin asciidoctor-maven-plugin-url: https://github.com/asciidoctor/asciidoctor-maven-plugin asciidoctor-url: https://asciidoctor.org - asciidoctorj-epub-name: Asciidoctorj-EPUB + asciidoctorj-epub-name: Asciidoctorj EPUB3 + asciidoctorj-epub-url: https://github.com/asciidoctor/asciidoctorj-epub3 asciidoctorj-name: AsciidoctorJ - asciidoctorj-pdf-name: Asciidoctorj-PDF + asciidoctorj-pdf-name: Asciidoctorj PDF + asciidoctorj-pdf-url: https://github.com/asciidoctor/asciidoctorj-pdf asciidoctorj-url: https://github.com/asciidoctor/asciidoctorj asciidoctorjs-name: Asciidoctor.js + asciidoctorjs-url: https://github.com/asciidoctor/asciidoctor.js gradle-url: https://gradle.org/ issues-asciidoctorj: https://github.com/asciidoctor/asciidoctorj/issues/ issues-jruby: https://github.com/asciidoctor/asciidoctorj/issues/ diff --git a/docs/antora/modules/ROOT/examples/base b/docs/antora/modules/ROOT/examples/base new file mode 120000 index 000000000..48681542e --- /dev/null +++ b/docs/antora/modules/ROOT/examples/base @@ -0,0 +1 @@ +../../../../../base \ No newline at end of file diff --git a/docs/antora/modules/ROOT/examples/jvm b/docs/antora/modules/ROOT/examples/jvm new file mode 120000 index 000000000..f67484124 --- /dev/null +++ b/docs/antora/modules/ROOT/examples/jvm @@ -0,0 +1 @@ +../../../../../jvm \ No newline at end of file diff --git a/docs/antora/docs/modules/ROOT/nav.adoc b/docs/antora/modules/ROOT/nav.adoc similarity index 95% rename from docs/antora/docs/modules/ROOT/nav.adoc rename to docs/antora/modules/ROOT/nav.adoc index 3974edcf5..c39e8c4aa 100644 --- a/docs/antora/docs/modules/ROOT/nav.adoc +++ b/docs/antora/modules/ROOT/nav.adoc @@ -1,4 +1,4 @@ -* xref:compatibility.adoc[] +* xref:index.adoc[] * xref:compatibility.adoc[] * xref:quick-start.adoc[] * xref:common-task-configuration.adoc[] @@ -8,8 +8,8 @@ * xref:asciidoctorj-epub-plugin.adoc[] * xref:asciidoctorj-revealjs-plugin.adoc[] // * xref:asciidoctorj-leanpub-plugin.adoc[] -* xref:asciidoctor-diagram.adoc[] * xref:asciidoctorj-gems-plugin.adoc[] +* xref:asciidoctor-diagram.adoc[] // * xref:kindlegen-plugin.adoc[] * xref:asciidoctorj-custom-extensions.adoc[] * xref:asciidoctorjs-plugin.adoc[] diff --git a/docs/src/docs/asciidoc/parts/asciidoctor-diagram.adoc b/docs/antora/modules/ROOT/pages/asciidoctor-diagram.adoc similarity index 99% rename from docs/src/docs/asciidoc/parts/asciidoctor-diagram.adoc rename to docs/antora/modules/ROOT/pages/asciidoctor-diagram.adoc index 4cdfac2d2..73dfb8229 100644 --- a/docs/src/docs/asciidoc/parts/asciidoctor-diagram.adoc +++ b/docs/antora/modules/ROOT/pages/asciidoctor-diagram.adoc @@ -1,4 +1,3 @@ -[[diagram]] = Using AsciidoctorJ Diagram The new plugins have built-in support for `asciidoctorj-diagram`. Simply add the following to the project or task extension and diff --git a/docs/src/docs/asciidoc/parts/asciidoctoreditorconfig-plugin.adoc b/docs/antora/modules/ROOT/pages/asciidoctoreditorconfig-plugin.adoc similarity index 100% rename from docs/src/docs/asciidoc/parts/asciidoctoreditorconfig-plugin.adoc rename to docs/antora/modules/ROOT/pages/asciidoctoreditorconfig-plugin.adoc diff --git a/docs/src/docs/asciidoc/parts/asciidoctorj-base-plugin.adoc b/docs/antora/modules/ROOT/pages/asciidoctorj-base-plugin.adoc similarity index 78% rename from docs/src/docs/asciidoc/parts/asciidoctorj-base-plugin.adoc rename to docs/antora/modules/ROOT/pages/asciidoctorj-base-plugin.adoc index 0b3ec6ccd..770c83554 100644 --- a/docs/src/docs/asciidoc/parts/asciidoctorj-base-plugin.adoc +++ b/docs/antora/modules/ROOT/pages/asciidoctorj-base-plugin.adoc @@ -40,12 +40,12 @@ asciidoctor { The {asciidoctorj-name}-specific entities that can be set are: [horizontal] -include::{plugin-jvm}/main/groovy/org/asciidoctor/gradle/jvm/AsciidoctorJExtension.groovy[indent=0,tags="extension-property"] +include::ROOT:example$jvm/src/main/groovy/org/asciidoctor/gradle/jvm/AsciidoctorJExtension.groovy[indent=0,tags="extension-property"] The following common entities can also be set: [horizontal] -include::{plugin-base}/main/groovy/org/asciidoctor/gradle/base/AbstractImplementationEngineExtension.groovy[indent=0,tags="extension-property"] +include::ROOT:example$base/src/main/groovy/org/asciidoctor/gradle/base/AbstractImplementationEngineExtension.groovy[indent=0,tags="extension-property"] // TODO: Split attributes into a standalone section that is not part of base plugin. [#options-and-attributes] @@ -139,13 +139,14 @@ asciidoctorj { } } ---- -<1> {asciidoctorj-epub-name} version. If not specified asciidoctorj-epub will not be on the classpath. If you plan to use the EPUB backend and not using the EPUB plugin, then you need to set a version here. -<2> {asciidoctorj-pdf-name} version. If not specified asciidoctorj-pdf will not be on the classpath. If you plan to use the PDF backend and not using the PDF plugin, then you need to set a version here. -<3> See <>, -<4> Version of Groovy Extensions DSL. If not specified and no extensions are specified, Groovy DSL will not be used. However, if any extensions are added without setting an explicit version and default version will be used. -<5> {asciidoctorj-leanpub-name} version. If not specified asciidoctorj-leanpub will not be on the classpath. If you plan to use the Leanpub backend and not using the Leanpub plugin, then you need to set a version here. +<1> {asciidoctorj-pdf-url}[{asciidoctorj-pdf-name}] version. If not specified asciidoctorj-pdf will not be on the classpath. If you plan to use the PDF backend and not using the PDF plugin, then you need to set a version here. +<2> {asciidoctorj-epub-url}[{asciidoctorj-epub-name}] version. If not specified asciidoctorj-epub will not be on the classpath. If you plan to use the EPUB backend and not using the EPUB plugin, then you need to set a version here. +<3> See xref:page$asciidoctor-diagram.adoc[]. +<4> Version of https://github.com/asciidoctor/asciidoctorj-groovy-dsl[Groovy Extensions DSL]. If not specified and no extensions are specified, Groovy DSL will not be used. However, if any extensions are added without setting an explicit version and default version will be used. +<5> https://github.com/asciidoctor/asciidoctor-leanpub-converter[Asciidoctor Leanpub Converter] version. If not specified asciidoctorj-leanpub will not be on the classpath. If you plan to use the Leanpub backend and not using the Leanpub plugin, then you need to set a version here. -When using the {kotlin-dsl} the same settings can be achieved use something similar `getModules().getPdf().version("1.2.3")`. In a similar fashion shortcuts can be achieved in the {groovy-dsl}: +When using the Kotlin DSL the same settings can be achieved use something similar `getModules().getPdf().version("1.2.3")`. +In a similar fashion shortcuts can be achieved in the Groovy DSL: [source,groovy,role="primary"] .build.gradle diff --git a/docs/src/docs/asciidoc/parts/asciidoctorj-compatiblity-plugin.adoc b/docs/antora/modules/ROOT/pages/asciidoctorj-compatiblity-plugin.adoc similarity index 100% rename from docs/src/docs/asciidoc/parts/asciidoctorj-compatiblity-plugin.adoc rename to docs/antora/modules/ROOT/pages/asciidoctorj-compatiblity-plugin.adoc diff --git a/docs/src/docs/asciidoc/parts/asciidoctorj-custom-extensions.adoc b/docs/antora/modules/ROOT/pages/asciidoctorj-custom-extensions.adoc similarity index 98% rename from docs/src/docs/asciidoc/parts/asciidoctorj-custom-extensions.adoc rename to docs/antora/modules/ROOT/pages/asciidoctorj-custom-extensions.adoc index e65f3fd63..ae8ed88c4 100644 --- a/docs/src/docs/asciidoc/parts/asciidoctorj-custom-extensions.adoc +++ b/docs/antora/modules/ROOT/pages/asciidoctorj-custom-extensions.adoc @@ -1,4 +1,3 @@ -[[asciidoctorj-extensions,Adding custom {asciidoctorj-name} extensions]] = Adding Custom Extensions Starting with version 1.5.0 you were able to write your own Asciidoctor extensions in Groovy, or any other JVM language diff --git a/docs/src/docs/asciidoc/parts/asciidoctorj-epub-plugin.adoc b/docs/antora/modules/ROOT/pages/asciidoctorj-epub-plugin.adoc similarity index 89% rename from docs/src/docs/asciidoc/parts/asciidoctorj-epub-plugin.adoc rename to docs/antora/modules/ROOT/pages/asciidoctorj-epub-plugin.adoc index c8ba94f28..31e71df83 100644 --- a/docs/src/docs/asciidoc/parts/asciidoctorj-epub-plugin.adoc +++ b/docs/antora/modules/ROOT/pages/asciidoctorj-epub-plugin.adoc @@ -1,5 +1,4 @@ -[[asciidoctorj-epub-plugin,{asciidoctorj-name} EPUB plugin]] -= The AsciidoctorEpub Plugin += {asciidoctorj-name} EPUB plugin INFO: As from version 3.3 support for KindleGen is dropped as Amazon no longer has the binary available for download. @@ -22,7 +21,7 @@ plugins { ---- When applying `org.asciidoctor.jvm.epub` it creates a single task of type `org.asciidoctor.gradle.jvm.epub.AsciidoctorEpubTask` which is then configured to: -* Output source to "${buildDir}/docs/asciidocEpub" +* Output source to "$\{buildDir}/docs/asciidocEpub" * Not to copy any resources to the output directory * It will set also a default version for `asciidoctorj-epub` artifact. To override set `asciidoctorj.epubVersion` or `asciidoctorEpub.asciidoctorj.epubVersion`. diff --git a/docs/src/docs/asciidoc/parts/asciidoctorj-gems-plugin.adoc b/docs/antora/modules/ROOT/pages/asciidoctorj-gems-plugin.adoc similarity index 91% rename from docs/src/docs/asciidoc/parts/asciidoctorj-gems-plugin.adoc rename to docs/antora/modules/ROOT/pages/asciidoctorj-gems-plugin.adoc index ca4293c06..c4f18350f 100644 --- a/docs/src/docs/asciidoc/parts/asciidoctorj-gems-plugin.adoc +++ b/docs/antora/modules/ROOT/pages/asciidoctorj-gems-plugin.adoc @@ -1,5 +1,4 @@ -[[asciidoctorj-gems-plugin,AsciidoctorJ GEMs plugin]] -= Ruby GEM support += AsciidoctorJ GEMs plugin GEM support is simplified via the `org.asciidoctor.jvm.gems` plugin. diff --git a/docs/src/docs/asciidoc/parts/asciidoctorj-leanpub-plugin.adoc b/docs/antora/modules/ROOT/pages/asciidoctorj-leanpub-plugin.adoc similarity index 80% rename from docs/src/docs/asciidoc/parts/asciidoctorj-leanpub-plugin.adoc rename to docs/antora/modules/ROOT/pages/asciidoctorj-leanpub-plugin.adoc index 3dd5d3707..52fad8cd9 100644 --- a/docs/src/docs/asciidoc/parts/asciidoctorj-leanpub-plugin.adoc +++ b/docs/antora/modules/ROOT/pages/asciidoctorj-leanpub-plugin.adoc @@ -1,9 +1,8 @@ -[[asciidoctorj-leanpub-plugin,{asciidoctorj-name} Leanpub plugin]] -= The AsciidoctorLeanpub Plugin += {asciidoctorj-name} Leanpub plugin When applying `org.asciidoctor.jvm.leanpub` it creates a single task of type `org.asciidoctor.gradle.jvm.epub.AsciidoctorLeanTask` which is then configured to: -* Output source to "${buildDir}/docs/asciidocLeanpub". +* Output source to "$\{buildDir}/docs/asciidocLeanpub". * Set also a default version for `asciidoctor-leanpub-backend` artifact. To override set `asciidoctorj.leanpubVersion` or `asciidoctorLeanpub.asciidoctorj.leanpubVersion`. diff --git a/docs/src/docs/asciidoc/parts/asciidoctorj-pdf-plugin.adoc b/docs/antora/modules/ROOT/pages/asciidoctorj-pdf-plugin.adoc similarity index 93% rename from docs/src/docs/asciidoc/parts/asciidoctorj-pdf-plugin.adoc rename to docs/antora/modules/ROOT/pages/asciidoctorj-pdf-plugin.adoc index bc92dea38..49c9c910f 100644 --- a/docs/src/docs/asciidoc/parts/asciidoctorj-pdf-plugin.adoc +++ b/docs/antora/modules/ROOT/pages/asciidoctorj-pdf-plugin.adoc @@ -1,6 +1,4 @@ -:AsciidoctorPdfTask-url: {groovydoc-jvm}/AsciidoctorPdfTask.html -[[asciidoctorj-pdf-plugin,AsciidoctorJ PDF plugin]] -= The AsciidoctorPdf Plugin += {asciidoctorj-pdf-name} plugin [source,groovy,role="primary"] [subs=attributes+] @@ -24,7 +22,7 @@ When applying `org.asciidoctor.jvm.pdf` it creates a single task of type `org.as The default task is named `asciidoctorPdf` and is configured to: -* Output source to "${buildDir}/docs/asciidocPdf". +* Output source to "$\{buildDir}/docs/asciidocPdf". * Not to copy any resources to the output directory. * It will set also a default version for `asciidoctorj-pdf` artifact. To override set `asciidoctorj.pdfVersion` or `asciidoctorPdf.asciidoctorj.pdfVersion`. diff --git a/docs/src/docs/asciidoc/parts/asciidoctorj-plugin.adoc b/docs/antora/modules/ROOT/pages/asciidoctorj-plugin.adoc similarity index 87% rename from docs/src/docs/asciidoc/parts/asciidoctorj-plugin.adoc rename to docs/antora/modules/ROOT/pages/asciidoctorj-plugin.adoc index ef195f431..3e318ebaf 100644 --- a/docs/src/docs/asciidoc/parts/asciidoctorj-plugin.adoc +++ b/docs/antora/modules/ROOT/pages/asciidoctorj-plugin.adoc @@ -1,4 +1,4 @@ -= The New AsciidoctorJ Plugin += AsciidoctorJ Plugin [source,groovy,role="primary"] [subs=attributes+] @@ -21,6 +21,6 @@ plugins { When applying `org.asciidoctor.jvm.convert` it creates a single task of type `org.asciidoctor.gradle.jvm.AsciidoctorTask` called `asciidoctor`. By convention, it sets the -* `sourceDir` to `src/docs/asciidoc` -* `outputDir` to `${buildDir}/docs/asciidoc` +* `sourceDir` to `src/docs/asciidoc` +* `outputDir` to `$\{buildDir}/docs/asciidoc` diff --git a/docs/src/docs/asciidoc/parts/asciidoctorj-revealjs-plugin.adoc b/docs/antora/modules/ROOT/pages/asciidoctorj-revealjs-plugin.adoc similarity index 94% rename from docs/src/docs/asciidoc/parts/asciidoctorj-revealjs-plugin.adoc rename to docs/antora/modules/ROOT/pages/asciidoctorj-revealjs-plugin.adoc index 23d377420..c1554d1d4 100644 --- a/docs/src/docs/asciidoc/parts/asciidoctorj-revealjs-plugin.adoc +++ b/docs/antora/modules/ROOT/pages/asciidoctorj-revealjs-plugin.adoc @@ -1,5 +1,4 @@ -[[asciidoctorj-revealjs-plugin,AsciidoctorJ Reveal.js plugin]] -= The AsciidoctorJ Reveal.js Plugin += AsciidoctorJ Reveal.js plugin [source,groovy,role="primary"] [subs=attributes+] @@ -24,7 +23,7 @@ When applying `org.asciidoctor.jvm.revealjs` support is added for creating slide * Create a task called `asciidoctorRevealJs`. * Create an extension called `revealjs` which is used for configuring the version of Reveal.js as well as a template. * Create an extension called `revealjsPlugins` which will allow for downloading additional Reveal.js plugins. -* Output source to "${buildDir}/docs/asciidocRevealJs" +* Output source to "$\{buildDir}/docs/asciidocRevealJs" * Copy all resources to the output directory including Reveal.js templates. * Apply the `org.asciidoctor.jvm.gems` plugin as GEM support is required. @@ -32,7 +31,7 @@ The `AsciidoctorRevealJSTask` task type has the following additional methods: [horizontal] revealjsOptions:: Configure special Reveal.js options. - Can be configured via Closure or Action. See <> for more details. + Can be configured via Closure or Action. See xref:#RevealJsOptions[] for more details. templateDir:: Location where the template directory will be located on disk before Asciidoctor processing starts. theme:: The Reveal.js theme to use. The theme must match one from the template. diff --git a/docs/src/docs/asciidoc/parts/asciidoctorjs-plugin.adoc b/docs/antora/modules/ROOT/pages/asciidoctorjs-plugin.adoc similarity index 78% rename from docs/src/docs/asciidoc/parts/asciidoctorjs-plugin.adoc rename to docs/antora/modules/ROOT/pages/asciidoctorjs-plugin.adoc index ec808787a..1f8325f71 100644 --- a/docs/src/docs/asciidoc/parts/asciidoctorjs-plugin.adoc +++ b/docs/antora/modules/ROOT/pages/asciidoctorjs-plugin.adoc @@ -1,7 +1,6 @@ -[[asciidoctorjs-plugin,{asciidoctorjs-name} plugin]] = Working with Asciidoctor.js instead -Instead of {asciidoctorj-name}, {asciidoctorjs-name} can be used as a rendering engine as from 3.0. +Instead of {asciidoctorj-name}, {asciidoctorjs-url}[{asciidoctorjs-name}] can be used as a rendering engine from 3.0. The configuration follows much the same as for {asciidoctorj-name}, but will a couple of differences. diff --git a/docs/src/docs/asciidoc/parts/common-task-configuration.adoc b/docs/antora/modules/ROOT/pages/common-task-configuration.adoc similarity index 98% rename from docs/src/docs/asciidoc/parts/common-task-configuration.adoc rename to docs/antora/modules/ROOT/pages/common-task-configuration.adoc index 68ac0bdfd..e4580797f 100644 --- a/docs/src/docs/asciidoc/parts/common-task-configuration.adoc +++ b/docs/antora/modules/ROOT/pages/common-task-configuration.adoc @@ -188,7 +188,7 @@ If you do not want this behaviour, then it can be turned off by doing copyNoResources() ---- -If you are using multiple languages and you have identical resource patterns for each language within `sourceDir/${lang}` you need to explicitly declare those on a per-language basis: +If you are using multiple languages and you have identical resource patterns for each language within `sourceDir/$\{lang}` you need to explicitly declare those on a per-language basis: [source,groovy,role="primary"] .build.gradle diff --git a/docs/src/docs/asciidoc/parts/compatibility.adoc b/docs/antora/modules/ROOT/pages/compatibility.adoc similarity index 100% rename from docs/src/docs/asciidoc/parts/compatibility.adoc rename to docs/antora/modules/ROOT/pages/compatibility.adoc diff --git a/docs/src/docs/asciidoc/parts/docinfo.adoc b/docs/antora/modules/ROOT/pages/docinfo.adoc similarity index 100% rename from docs/src/docs/asciidoc/parts/docinfo.adoc rename to docs/antora/modules/ROOT/pages/docinfo.adoc diff --git a/docs/src/docs/asciidoc/parts/exporting-slides.adoc b/docs/antora/modules/ROOT/pages/exporting-slides.adoc similarity index 87% rename from docs/src/docs/asciidoc/parts/exporting-slides.adoc rename to docs/antora/modules/ROOT/pages/exporting-slides.adoc index 074ba43ca..db8f645d3 100644 --- a/docs/src/docs/asciidoc/parts/exporting-slides.adoc +++ b/docs/antora/modules/ROOT/pages/exporting-slides.adoc @@ -34,9 +34,9 @@ task standalonePdfConverter(type: DeckTapeTask) { <3> If screenshots are activated, then screenshot images of the slides are also produced. <4> Image format. PMG and JPG are supported. <5> Width and height of the exported slides. -<6> Range of slides to export. By default all are exported. +<6> Range of slides to export. By default, all are exported. -=== Combining with Reveal.js plugin +== Combining with Reveal.js plugin If you do @@ -60,6 +60,6 @@ plugins { } ---- -a little bit of _magic_ happens. A task called on `asciidoctorRevealJsExport` is created on demand from a rule and all of the appropriate properties are set on it so that it can export slides created by the `asciidoctorRevealJs` task. +a little bit of _magic_ happens. A task called on `asciidoctorRevealJsExport` is created on demand from a rule and all the appropriate properties are set on it so that it can export slides created by the `asciidoctorRevealJs` task. You can configure the `asciidoctorRevealJsExport` task like any other `DeckTapeTask`. diff --git a/docs/antora/modules/ROOT/pages/index.adoc b/docs/antora/modules/ROOT/pages/index.adoc new file mode 100644 index 000000000..2edc06d37 --- /dev/null +++ b/docs/antora/modules/ROOT/pages/index.adoc @@ -0,0 +1,10 @@ += Asciidoctor Gradle Plugin Suite +:navtitle: Introduction + +The {doctitle} is the official means of using {asciidoctor-url}[Asciidoctor] to convert all your {asciidoc-url}[AsciiDoc] documentation using {gradle-url}[Gradle]. + +This started as a port of the {asciidoctor-maven-plugin-url}[asciidoctor-maven-plugin-name] project founded by {lightguard} and relies on {asciidoctorj-url}[{asciidoctorj-name}] which was founded by {lordofthejars}. +In fact the 1.5.x series of the {plugin-name} can still be considered a port. + +However, with 2.x series came a complete departure with functionality far exceeding any lightweight markup plugins for any other build tool. +With the 3.x serious allows for even more flexibility and options for the creation of a true DocuOps pipeline by bringing together Gradle as a powerful and generic build tool, and Asciidoctor as an agile and lightweight document generator. diff --git a/docs/src/docs/asciidoc/parts/kindlegen-plugin.adoc b/docs/antora/modules/ROOT/pages/kindlegen-plugin.adoc similarity index 100% rename from docs/src/docs/asciidoc/parts/kindlegen-plugin.adoc rename to docs/antora/modules/ROOT/pages/kindlegen-plugin.adoc diff --git a/docs/src/docs/asciidoc/parts/quick-start.adoc b/docs/antora/modules/ROOT/pages/quick-start.adoc similarity index 100% rename from docs/src/docs/asciidoc/parts/quick-start.adoc rename to docs/antora/modules/ROOT/pages/quick-start.adoc diff --git a/docs/src/docs/asciidoc/parts/upgrading.adoc b/docs/antora/modules/ROOT/pages/upgrading.adoc similarity index 100% rename from docs/src/docs/asciidoc/parts/upgrading.adoc rename to docs/antora/modules/ROOT/pages/upgrading.adoc diff --git a/docs/antora/docs/modules/appendices/nav.adoc b/docs/antora/modules/appendices/nav.adoc similarity index 100% rename from docs/antora/docs/modules/appendices/nav.adoc rename to docs/antora/modules/appendices/nav.adoc diff --git a/docs/antora/docs/modules/appendices/pages/hacking.adoc b/docs/antora/modules/appendices/pages/hacking.adoc similarity index 100% rename from docs/antora/docs/modules/appendices/pages/hacking.adoc rename to docs/antora/modules/appendices/pages/hacking.adoc diff --git a/docs/antora/docs/modules/appendices/pages/known-limitations.adoc b/docs/antora/modules/appendices/pages/known-limitations.adoc similarity index 100% rename from docs/antora/docs/modules/appendices/pages/known-limitations.adoc rename to docs/antora/modules/appendices/pages/known-limitations.adoc diff --git a/docs/antora/docs/modules/appendices/pages/tips-and-tricks.adoc b/docs/antora/modules/appendices/pages/tips-and-tricks.adoc similarity index 100% rename from docs/antora/docs/modules/appendices/pages/tips-and-tricks.adoc rename to docs/antora/modules/appendices/pages/tips-and-tricks.adoc diff --git a/docs/antora/modules/file.adoc b/docs/antora/modules/file.adoc new file mode 100644 index 000000000..7b57bd29e --- /dev/null +++ b/docs/antora/modules/file.adoc @@ -0,0 +1 @@ +some text diff --git a/docs/src/docs/asciidoc/appendix/hacking.adoc b/docs/src/docs/asciidoc/appendix/hacking.adoc deleted file mode 100644 index 6d9f2f6b4..000000000 --- a/docs/src/docs/asciidoc/appendix/hacking.adoc +++ /dev/null @@ -1,11 +0,0 @@ -[appendix] -= 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. diff --git a/docs/src/docs/asciidoc/appendix/known-limitations.adoc b/docs/src/docs/asciidoc/appendix/known-limitations.adoc deleted file mode 100644 index 98d5f335b..000000000 --- a/docs/src/docs/asciidoc/appendix/known-limitations.adoc +++ /dev/null @@ -1,10 +0,0 @@ -[appendix] -= 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]). diff --git a/docs/src/docs/asciidoc/appendix/tips-and-tricks.adoc b/docs/src/docs/asciidoc/appendix/tips-and-tricks.adoc deleted file mode 100644 index dbdd6ca53..000000000 --- a/docs/src/docs/asciidoc/appendix/tips-and-tricks.adoc +++ /dev/null @@ -1,76 +0,0 @@ -[appendix] -= 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' - } -} ----- diff --git a/docs/src/docs/asciidoc/attributes.adoc b/docs/src/docs/asciidoc/attributes.adoc deleted file mode 100644 index 797d52847..000000000 --- a/docs/src/docs/asciidoc/attributes.adoc +++ /dev/null @@ -1,22 +0,0 @@ -: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 -:asciidoctor-docs: https://docs.asciidoctor.org/asciidoctor/latest -:asciidoctor-maven-plugin-name: Asciidoctor Maven Plugin -:asciidoctor-maven-plugin-url: https://github.com/asciidoctor/asciidoctor-maven-plugin -:asciidoctor-url: https://asciidoctor.org -:asciidoctorj-epub-name: Asciidoctorj-EPUB -:asciidoctorj-name: AsciidoctorJ -:asciidoctorj-pdf-name: Asciidoctorj-PDF -:asciidoctorj-url: https://github.com/asciidoctor/asciidoctorj -:asciidoctorjs-name: Asciidoctor.js -:gradle-url: https://gradle.org/ -:issues-asciidoctorj: https://github.com/asciidoctor/asciidoctorj/issues/ -:issues-jruby: https://github.com/asciidoctor/asciidoctorj/issues/ -:jruby-name: JRuby -:kotlindsl: https://github.com/gradle/kotlin-dsl[Gradle Kotlin DSL] -:lightguard: https://github.com/LightGuard[Jason Porter] -:lordofthejars: https://github.com/lordofthejars[Alex Soto] diff --git a/docs/src/docs/asciidoc/index.adoc b/docs/src/docs/asciidoc/index.adoc deleted file mode 100644 index 86473b354..000000000 --- a/docs/src/docs/asciidoc/index.adoc +++ /dev/null @@ -1,58 +0,0 @@ -= Asciidoctor Gradle Plugin Suite -include::attributes.adoc[] -:icons: font -:leveloffset: +1 -:linkattrs: -ifdef::env-idea[] -:toc: preamble -endif::[] -ifeval::[{env}!=idea] -:toc: right -endif::[] - -The {doctitle} is the official means of using {asciidoctor-url}[Asciidoctor] to convert all your {asciidoc-url}[AsciiDoc] documentation using {gradle-url}[Gradle]. - -This started as a port of the {asciidoctor-maven-plugin-url}[asciidoctor-maven-plugin-name] project founded by {lightguard} and relies on {asciidoctorj-url}[{asciidoctorj-name}] which was founded by {lordofthejars}. -In fact the 1.5.x series of the {plugin-name} can still be considered a port. -However, with 2.x series came a complete departure with functionality far exceeding any lightweight markup plugins for any other build tool. -With the 3.x serious allows for even more flexibility and options for the creation of a true DocuOps pipeline by bringing together Gradle as a powerful and generic build tool, and Asciidoctor as an agile and lightweight document generator. - -include::parts/compatibility.adoc[] - -include::parts/quick-start.adoc[] - -include::parts/common-task-configuration.adoc[] - -include::parts/asciidoctorj-base-plugin.adoc[] - -include::parts/asciidoctorj-plugin.adoc[] - -include::parts/asciidoctorj-pdf-plugin.adoc[] - -include::parts/asciidoctorj-epub-plugin.adoc[] - -include::parts/asciidoctorj-revealjs-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/asciidoctorj-custom-extensions.adoc[] - -include::parts/asciidoctorjs-plugin.adoc[] - -include::parts/asciidoctoreditorconfig-plugin.adoc[] - -include::parts/docinfo.adoc[] - -include::parts/upgrading.adoc[] - -include::appendix/tips-and-tricks.adoc[] - -include::appendix/known-limitations.adoc[] - -include::appendix/hacking.adoc[] From 0c45812ed786435bda1374a1cad0fa794564a0a5 Mon Sep 17 00:00:00 2001 From: Abel Salgado Romero Date: Sat, 9 Mar 2024 21:23:49 +0100 Subject: [PATCH 07/10] Remove unnecessary gralde docs modules --- .github/workflows/push-documentation.yml | 34 ---- docs/README-IntelliJ.adoc | 10 -- docs/antora/modules/ROOT/examples/base | 1 - docs/antora/modules/ROOT/examples/jvm | 1 - docs/build.gradle | 149 ------------------ docs/gh-pages/build.gradle | 35 ---- docs/gradle.properties | 1 - docs/gradle/load-properties.gradle | 13 -- docs/gradle/wrapper | 1 - docs/gradlew | 2 - docs/gradlew.bat | 8 - docs/modules/ROOT/examples/base | 1 + docs/modules/ROOT/examples/jvm | 1 + docs/{antora => }/modules/ROOT/nav.adoc | 0 .../ROOT/pages/asciidoctor-diagram.adoc | 0 .../pages/asciidoctoreditorconfig-plugin.adoc | 0 .../ROOT/pages/asciidoctorj-base-plugin.adoc | 0 .../asciidoctorj-compatiblity-plugin.adoc | 0 .../pages/asciidoctorj-custom-extensions.adoc | 0 .../ROOT/pages/asciidoctorj-epub-plugin.adoc | 0 .../ROOT/pages/asciidoctorj-gems-plugin.adoc | 0 .../pages/asciidoctorj-leanpub-plugin.adoc | 0 .../ROOT/pages/asciidoctorj-pdf-plugin.adoc | 0 .../ROOT/pages/asciidoctorj-plugin.adoc | 0 .../pages/asciidoctorj-revealjs-plugin.adoc | 0 .../ROOT/pages/asciidoctorjs-plugin.adoc | 0 .../ROOT/pages/common-task-configuration.adoc | 0 .../modules/ROOT/pages/compatibility.adoc | 0 .../modules/ROOT/pages/docinfo.adoc | 0 .../modules/ROOT/pages/exporting-slides.adoc | 0 .../modules/ROOT/pages/index.adoc | 0 .../modules/ROOT/pages/kindlegen-plugin.adoc | 0 .../modules/ROOT/pages/quick-start.adoc | 0 .../modules/ROOT/pages/upgrading.adoc | 0 docs/{antora => modules}/antora.yml | 0 docs/{antora => }/modules/appendices/nav.adoc | 0 .../modules/appendices/pages/hacking.adoc | 0 .../appendices/pages/known-limitations.adoc | 0 .../appendices/pages/tips-and-tricks.adoc | 0 docs/{antora => }/modules/file.adoc | 0 docs/publish-docs-from-travis | 15 -- docs/settings.gradle | 4 - 42 files changed, 2 insertions(+), 274 deletions(-) delete mode 100644 .github/workflows/push-documentation.yml delete mode 100644 docs/README-IntelliJ.adoc delete mode 120000 docs/antora/modules/ROOT/examples/base delete mode 120000 docs/antora/modules/ROOT/examples/jvm delete mode 100644 docs/build.gradle delete mode 100644 docs/gh-pages/build.gradle delete mode 100644 docs/gradle.properties delete mode 100644 docs/gradle/load-properties.gradle delete mode 120000 docs/gradle/wrapper delete mode 100755 docs/gradlew delete mode 100644 docs/gradlew.bat create mode 120000 docs/modules/ROOT/examples/base create mode 120000 docs/modules/ROOT/examples/jvm rename docs/{antora => }/modules/ROOT/nav.adoc (100%) rename docs/{antora => }/modules/ROOT/pages/asciidoctor-diagram.adoc (100%) rename docs/{antora => }/modules/ROOT/pages/asciidoctoreditorconfig-plugin.adoc (100%) rename docs/{antora => }/modules/ROOT/pages/asciidoctorj-base-plugin.adoc (100%) rename docs/{antora => }/modules/ROOT/pages/asciidoctorj-compatiblity-plugin.adoc (100%) rename docs/{antora => }/modules/ROOT/pages/asciidoctorj-custom-extensions.adoc (100%) rename docs/{antora => }/modules/ROOT/pages/asciidoctorj-epub-plugin.adoc (100%) rename docs/{antora => }/modules/ROOT/pages/asciidoctorj-gems-plugin.adoc (100%) rename docs/{antora => }/modules/ROOT/pages/asciidoctorj-leanpub-plugin.adoc (100%) rename docs/{antora => }/modules/ROOT/pages/asciidoctorj-pdf-plugin.adoc (100%) rename docs/{antora => }/modules/ROOT/pages/asciidoctorj-plugin.adoc (100%) rename docs/{antora => }/modules/ROOT/pages/asciidoctorj-revealjs-plugin.adoc (100%) rename docs/{antora => }/modules/ROOT/pages/asciidoctorjs-plugin.adoc (100%) rename docs/{antora => }/modules/ROOT/pages/common-task-configuration.adoc (100%) rename docs/{antora => }/modules/ROOT/pages/compatibility.adoc (100%) rename docs/{antora => }/modules/ROOT/pages/docinfo.adoc (100%) rename docs/{antora => }/modules/ROOT/pages/exporting-slides.adoc (100%) rename docs/{antora => }/modules/ROOT/pages/index.adoc (100%) rename docs/{antora => }/modules/ROOT/pages/kindlegen-plugin.adoc (100%) rename docs/{antora => }/modules/ROOT/pages/quick-start.adoc (100%) rename docs/{antora => }/modules/ROOT/pages/upgrading.adoc (100%) rename docs/{antora => modules}/antora.yml (100%) rename docs/{antora => }/modules/appendices/nav.adoc (100%) rename docs/{antora => }/modules/appendices/pages/hacking.adoc (100%) rename docs/{antora => }/modules/appendices/pages/known-limitations.adoc (100%) rename docs/{antora => }/modules/appendices/pages/tips-and-tricks.adoc (100%) rename docs/{antora => }/modules/file.adoc (100%) delete mode 100755 docs/publish-docs-from-travis delete mode 100644 docs/settings.gradle diff --git a/.github/workflows/push-documentation.yml b/.github/workflows/push-documentation.yml deleted file mode 100644 index 62907150a..000000000 --- a/.github/workflows/push-documentation.yml +++ /dev/null @@ -1,34 +0,0 @@ -name: Push documentation -on: - push: - branches: - - master - - development-4.x -permissions: - contents: write -jobs: - push-docs: - runs-on: ubuntu-latest - if: github.repository == 'asciidoctor/asciidoctor-gradle-plugin' - steps: - - uses: actions/checkout@v4 - - uses: actions/setup-java@v4 - with: - java-version: 11 - distribution: temurin - - uses: gradle/actions/setup-gradle@v3 - with: - gradle-home-cache-cleanup: true - - name: Combine documentation - run: | - cd docs - ./gradlew --console=plain -q combineDocs - - name: Publish documentation - env: - CI_BRANCH: ${{ github.ref_name }} - REPO_URL: ${{ github.server_url }}/${{ github.repository }} - GRGIT_USER: 'GH Action User' - GRGIT_PASS: ${{ secrets.GITHUB_TOKEN }} - run: | - cd docs - ./gradlew --console=plain :gh-pages:publishDocs --info --stacktrace diff --git a/docs/README-IntelliJ.adoc b/docs/README-IntelliJ.adoc deleted file mode 100644 index 7c637c035..000000000 --- a/docs/README-IntelliJ.adoc +++ /dev/null @@ -1,10 +0,0 @@ -= IntelliJ support - -In order to edit the documents in IntelliJ add the `docs folder as a new module in IntelliJ. Check the `auto-import` box and use the `Gradle Wrapper` option. - -In order to have the correct attributes made available to the Asciidoctor preview in IntelliJ, do - -[listing.terminal] ----- -$ cd docs && ./gradlew asciidoctorEditorConfig ----- \ No newline at end of file diff --git a/docs/antora/modules/ROOT/examples/base b/docs/antora/modules/ROOT/examples/base deleted file mode 120000 index 48681542e..000000000 --- a/docs/antora/modules/ROOT/examples/base +++ /dev/null @@ -1 +0,0 @@ -../../../../../base \ No newline at end of file diff --git a/docs/antora/modules/ROOT/examples/jvm b/docs/antora/modules/ROOT/examples/jvm deleted file mode 120000 index f67484124..000000000 --- a/docs/antora/modules/ROOT/examples/jvm +++ /dev/null @@ -1 +0,0 @@ -../../../../../jvm \ No newline at end of file diff --git a/docs/build.gradle b/docs/build.gradle deleted file mode 100644 index bd3519fb2..000000000 --- a/docs/build.gradle +++ /dev/null @@ -1,149 +0,0 @@ -plugins { - id 'idea' - id 'org.asciidoctor.jvm.convert' apply false - id 'org.asciidoctor.editorconfig' apply false - id 'org.ajoberstar.git-publish' version '4.2.2' apply false -} - -repositories { - mavenCentral() -} - -ext { - asciidoctorSourceSyncDir = file("${buildDir}/docs/sources") - asciidoctorCombinedDocsDir = file("${buildDir}/docs/combined") - - docProjects = [ - new IncludedProject(name: 'asciidoctoreditorconfig', dir: 'asciidoctoreditorconfig'), - new IncludedProject(name: 'asciidoctor-gradle-base', dir: 'base'), - new IncludedProject(name: 'asciidoctor-gradle-jvm-gems', dir: 'gems'), - new IncludedProject(name: 'asciidoctor-gradle-js', dir: 'js'), - new IncludedProject(name: 'asciidoctor-gradle-jvm', dir: 'jvm'), - new IncludedProject(name: 'asciidoctor-gradle-jvm-epub', dir: 'jvm-epub'), - new IncludedProject(name: 'asciidoctor-gradle-jvm-pdf', dir: 'jvm-pdf'), - ] -} - -allprojects { - apply from: "${rootDir}/gradle/load-properties.gradle" - version = pluginsGradleProperties.version -} - -apply plugin: 'org.asciidoctor.jvm.convert' -apply plugin: 'org.asciidoctor.editorconfig' - -configurations { - asciidocExtensions -} - -dependencies { -// asciidocExtensions 'com.bmuschko:asciidoctorj-tabbed-code-extension:0.1' -} - -task prepareSources(type: Sync) { - group 'documentation' - description 'Copy sources from all plugin projects' - into asciidoctorSourceSyncDir - - docProjects.each { proj -> - from pluginProjectDir(proj), { - into proj.dir - include 'src/**' - exclude '**/META-INF/**' - } - } -} - -asciidoctorj { - fatalWarnings missingIncludes() -} - -asciidoctor { - group 'documentation' - description 'Build HTML documentation' - - dependsOn prepareSources - baseDirFollowsSourceDir() - // configurations 'asciidocExtensions' - sourceDir 'src/docs/asciidoc' - sources { include 'index.adoc' } - attributes toc: 'right', - toclevels: 2, - 'source-highlighter': 'rouge', - 'release-version': project.version - - docProjects.each { proj -> - attributes "plugin-${proj.dir}": file("${prepareSources.destinationDir}/${proj.dir}/src") - } -} - -task generateIndex { - group 'documentation' - description 'Generate index source file' - ext { - outputFile = file("${buildDir}/docs/index-source/index.adoc") - } - - inputs.property 'docProjects', docProjects - outputs.file outputFile - - doLast { - outputFile.parentFile.mkdirs() - outputFile.withWriter { w -> - w.println "= Asciidoctor Gradle Plugin Suite v${version}" - w.println '' - w.println "* link:./user-guide/[User guide]" - - docProjects*.dir.sort().each { projDir -> - w.println "* link:./api-${projDir}/[API: ${projDir}]" - } - } - } -} - -task asciidocIndex(type: org.asciidoctor.gradle.jvm.AsciidoctorTask) { - group 'documentation' - description 'Generate HTML index' - - dependsOn generateIndex - sourceDir generateIndex.outputFile.parentFile - outputDir "${buildDir}/docs/index" -} - -task combineDocs(type: Sync) { - group 'documentation' - description 'Combine all generated documentation into a single tree' - - dependsOn docProjects.collect { includedBuildTask(it, 'groovydoc') } - into asciidoctorCombinedDocsDir - from asciidocIndex - from asciidoctor, { - into 'user-guide' - } - - docProjects.each { proj -> - from "${pluginProjectDir(proj)}/build/docs/groovydoc", { - into "api-${proj.dir}" - } - } -} - -asciidoctorEditorConfig { - attributes revnumber: project.version - additionalAttributes 'src/docs/asciidoc/attributes.adoc' - additionalAttributes asciidoctor.asciidoctorj - dependsOn prepareSources -} - -class IncludedProject implements Serializable { - String name - String dir -} - -File pluginProjectDir(IncludedProject pluginName) { - new File(rootProject.projectDir.parentFile, pluginName.dir) -} - -TaskReference includedBuildTask(IncludedProject proj, String task) { - gradle.includedBuild('asciidoctor-gradle-plugin').task(":${proj.name}:${task}") -} diff --git a/docs/gh-pages/build.gradle b/docs/gh-pages/build.gradle deleted file mode 100644 index 719bcaa78..000000000 --- a/docs/gh-pages/build.gradle +++ /dev/null @@ -1,35 +0,0 @@ -plugins { - id 'base' - id 'org.ajoberstar.git-publish' -} - -ext { - currentBranch = System.getenv('CI_BRANCH') ?: 'not-on-ci' - pushDocs = currentBranch.matches(~/^master|development-.+|maintenance-.+$/) -} - -gitPublish { - repoUri = System.getenv('REPO_URL') ?: gitHubRepoUri - branch = 'gh-pages' - - contents { - into currentBranch - from rootProject.tasks.combineDocs - } - - preserve { - include '**' - exclude "${currentBranch}/**" - } - - commitMessage = "Updating SNAPSHOT documentation for ${currentBranch} at ${version}" -} - -task publishDocs { - if (pushDocs) { - dependsOn gitPublishPush - } - doFirst { - logger.lifecycle "${currentBranch} is ${pushDocs ? 'a match. Push attempted' : 'not a match. Push skipped.'}" - } -} diff --git a/docs/gradle.properties b/docs/gradle.properties deleted file mode 100644 index f7cdd9ca9..000000000 --- a/docs/gradle.properties +++ /dev/null @@ -1 +0,0 @@ -gitHubRepoUri=git@github.com:abelsromero/asciidoctor-gradle-plugin.git diff --git a/docs/gradle/load-properties.gradle b/docs/gradle/load-properties.gradle deleted file mode 100644 index 20169fbbb..000000000 --- a/docs/gradle/load-properties.gradle +++ /dev/null @@ -1,13 +0,0 @@ -class LoadProperties { - static Properties get(File path) { - def props = new Properties() - path.withInputStream { strm -> - props.load(strm) - } - props - } -} - -ext { - pluginsGradleProperties = LoadProperties.get(file("${rootDir}/../gradle.properties")) -} \ No newline at end of file diff --git a/docs/gradle/wrapper b/docs/gradle/wrapper deleted file mode 120000 index cbfd2e1d3..000000000 --- a/docs/gradle/wrapper +++ /dev/null @@ -1 +0,0 @@ -../../gradle/wrapper/ \ No newline at end of file diff --git a/docs/gradlew b/docs/gradlew deleted file mode 100755 index 7bd0f031c..000000000 --- a/docs/gradlew +++ /dev/null @@ -1,2 +0,0 @@ -#!/usr/bin/env bash -exec $(dirname $0)/../gradlew $@ \ No newline at end of file diff --git a/docs/gradlew.bat b/docs/gradlew.bat deleted file mode 100644 index be82f97e0..000000000 --- a/docs/gradlew.bat +++ /dev/null @@ -1,8 +0,0 @@ -@rem -@rem Credits to Jez Higgins (@jezhiggins) & Ralph McArdell (@ralph-mcardell) -@rem for hints on how to have a very simplified batch file. -@rem -@echo off - -setlocal enableextensions -%~p0\..\gradlew.bat %* \ No newline at end of file diff --git a/docs/modules/ROOT/examples/base b/docs/modules/ROOT/examples/base new file mode 120000 index 000000000..393ad7fc9 --- /dev/null +++ b/docs/modules/ROOT/examples/base @@ -0,0 +1 @@ +../../../../base \ No newline at end of file diff --git a/docs/modules/ROOT/examples/jvm b/docs/modules/ROOT/examples/jvm new file mode 120000 index 000000000..401facfb7 --- /dev/null +++ b/docs/modules/ROOT/examples/jvm @@ -0,0 +1 @@ +../../../../jvm \ No newline at end of file diff --git a/docs/antora/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc similarity index 100% rename from docs/antora/modules/ROOT/nav.adoc rename to docs/modules/ROOT/nav.adoc diff --git a/docs/antora/modules/ROOT/pages/asciidoctor-diagram.adoc b/docs/modules/ROOT/pages/asciidoctor-diagram.adoc similarity index 100% rename from docs/antora/modules/ROOT/pages/asciidoctor-diagram.adoc rename to docs/modules/ROOT/pages/asciidoctor-diagram.adoc diff --git a/docs/antora/modules/ROOT/pages/asciidoctoreditorconfig-plugin.adoc b/docs/modules/ROOT/pages/asciidoctoreditorconfig-plugin.adoc similarity index 100% rename from docs/antora/modules/ROOT/pages/asciidoctoreditorconfig-plugin.adoc rename to docs/modules/ROOT/pages/asciidoctoreditorconfig-plugin.adoc diff --git a/docs/antora/modules/ROOT/pages/asciidoctorj-base-plugin.adoc b/docs/modules/ROOT/pages/asciidoctorj-base-plugin.adoc similarity index 100% rename from docs/antora/modules/ROOT/pages/asciidoctorj-base-plugin.adoc rename to docs/modules/ROOT/pages/asciidoctorj-base-plugin.adoc diff --git a/docs/antora/modules/ROOT/pages/asciidoctorj-compatiblity-plugin.adoc b/docs/modules/ROOT/pages/asciidoctorj-compatiblity-plugin.adoc similarity index 100% rename from docs/antora/modules/ROOT/pages/asciidoctorj-compatiblity-plugin.adoc rename to docs/modules/ROOT/pages/asciidoctorj-compatiblity-plugin.adoc diff --git a/docs/antora/modules/ROOT/pages/asciidoctorj-custom-extensions.adoc b/docs/modules/ROOT/pages/asciidoctorj-custom-extensions.adoc similarity index 100% rename from docs/antora/modules/ROOT/pages/asciidoctorj-custom-extensions.adoc rename to docs/modules/ROOT/pages/asciidoctorj-custom-extensions.adoc diff --git a/docs/antora/modules/ROOT/pages/asciidoctorj-epub-plugin.adoc b/docs/modules/ROOT/pages/asciidoctorj-epub-plugin.adoc similarity index 100% rename from docs/antora/modules/ROOT/pages/asciidoctorj-epub-plugin.adoc rename to docs/modules/ROOT/pages/asciidoctorj-epub-plugin.adoc diff --git a/docs/antora/modules/ROOT/pages/asciidoctorj-gems-plugin.adoc b/docs/modules/ROOT/pages/asciidoctorj-gems-plugin.adoc similarity index 100% rename from docs/antora/modules/ROOT/pages/asciidoctorj-gems-plugin.adoc rename to docs/modules/ROOT/pages/asciidoctorj-gems-plugin.adoc diff --git a/docs/antora/modules/ROOT/pages/asciidoctorj-leanpub-plugin.adoc b/docs/modules/ROOT/pages/asciidoctorj-leanpub-plugin.adoc similarity index 100% rename from docs/antora/modules/ROOT/pages/asciidoctorj-leanpub-plugin.adoc rename to docs/modules/ROOT/pages/asciidoctorj-leanpub-plugin.adoc diff --git a/docs/antora/modules/ROOT/pages/asciidoctorj-pdf-plugin.adoc b/docs/modules/ROOT/pages/asciidoctorj-pdf-plugin.adoc similarity index 100% rename from docs/antora/modules/ROOT/pages/asciidoctorj-pdf-plugin.adoc rename to docs/modules/ROOT/pages/asciidoctorj-pdf-plugin.adoc diff --git a/docs/antora/modules/ROOT/pages/asciidoctorj-plugin.adoc b/docs/modules/ROOT/pages/asciidoctorj-plugin.adoc similarity index 100% rename from docs/antora/modules/ROOT/pages/asciidoctorj-plugin.adoc rename to docs/modules/ROOT/pages/asciidoctorj-plugin.adoc diff --git a/docs/antora/modules/ROOT/pages/asciidoctorj-revealjs-plugin.adoc b/docs/modules/ROOT/pages/asciidoctorj-revealjs-plugin.adoc similarity index 100% rename from docs/antora/modules/ROOT/pages/asciidoctorj-revealjs-plugin.adoc rename to docs/modules/ROOT/pages/asciidoctorj-revealjs-plugin.adoc diff --git a/docs/antora/modules/ROOT/pages/asciidoctorjs-plugin.adoc b/docs/modules/ROOT/pages/asciidoctorjs-plugin.adoc similarity index 100% rename from docs/antora/modules/ROOT/pages/asciidoctorjs-plugin.adoc rename to docs/modules/ROOT/pages/asciidoctorjs-plugin.adoc diff --git a/docs/antora/modules/ROOT/pages/common-task-configuration.adoc b/docs/modules/ROOT/pages/common-task-configuration.adoc similarity index 100% rename from docs/antora/modules/ROOT/pages/common-task-configuration.adoc rename to docs/modules/ROOT/pages/common-task-configuration.adoc diff --git a/docs/antora/modules/ROOT/pages/compatibility.adoc b/docs/modules/ROOT/pages/compatibility.adoc similarity index 100% rename from docs/antora/modules/ROOT/pages/compatibility.adoc rename to docs/modules/ROOT/pages/compatibility.adoc diff --git a/docs/antora/modules/ROOT/pages/docinfo.adoc b/docs/modules/ROOT/pages/docinfo.adoc similarity index 100% rename from docs/antora/modules/ROOT/pages/docinfo.adoc rename to docs/modules/ROOT/pages/docinfo.adoc diff --git a/docs/antora/modules/ROOT/pages/exporting-slides.adoc b/docs/modules/ROOT/pages/exporting-slides.adoc similarity index 100% rename from docs/antora/modules/ROOT/pages/exporting-slides.adoc rename to docs/modules/ROOT/pages/exporting-slides.adoc diff --git a/docs/antora/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc similarity index 100% rename from docs/antora/modules/ROOT/pages/index.adoc rename to docs/modules/ROOT/pages/index.adoc diff --git a/docs/antora/modules/ROOT/pages/kindlegen-plugin.adoc b/docs/modules/ROOT/pages/kindlegen-plugin.adoc similarity index 100% rename from docs/antora/modules/ROOT/pages/kindlegen-plugin.adoc rename to docs/modules/ROOT/pages/kindlegen-plugin.adoc diff --git a/docs/antora/modules/ROOT/pages/quick-start.adoc b/docs/modules/ROOT/pages/quick-start.adoc similarity index 100% rename from docs/antora/modules/ROOT/pages/quick-start.adoc rename to docs/modules/ROOT/pages/quick-start.adoc diff --git a/docs/antora/modules/ROOT/pages/upgrading.adoc b/docs/modules/ROOT/pages/upgrading.adoc similarity index 100% rename from docs/antora/modules/ROOT/pages/upgrading.adoc rename to docs/modules/ROOT/pages/upgrading.adoc diff --git a/docs/antora/antora.yml b/docs/modules/antora.yml similarity index 100% rename from docs/antora/antora.yml rename to docs/modules/antora.yml diff --git a/docs/antora/modules/appendices/nav.adoc b/docs/modules/appendices/nav.adoc similarity index 100% rename from docs/antora/modules/appendices/nav.adoc rename to docs/modules/appendices/nav.adoc diff --git a/docs/antora/modules/appendices/pages/hacking.adoc b/docs/modules/appendices/pages/hacking.adoc similarity index 100% rename from docs/antora/modules/appendices/pages/hacking.adoc rename to docs/modules/appendices/pages/hacking.adoc diff --git a/docs/antora/modules/appendices/pages/known-limitations.adoc b/docs/modules/appendices/pages/known-limitations.adoc similarity index 100% rename from docs/antora/modules/appendices/pages/known-limitations.adoc rename to docs/modules/appendices/pages/known-limitations.adoc diff --git a/docs/antora/modules/appendices/pages/tips-and-tricks.adoc b/docs/modules/appendices/pages/tips-and-tricks.adoc similarity index 100% rename from docs/antora/modules/appendices/pages/tips-and-tricks.adoc rename to docs/modules/appendices/pages/tips-and-tricks.adoc diff --git a/docs/antora/modules/file.adoc b/docs/modules/file.adoc similarity index 100% rename from docs/antora/modules/file.adoc rename to docs/modules/file.adoc diff --git a/docs/publish-docs-from-travis b/docs/publish-docs-from-travis deleted file mode 100755 index 2408c9b63..000000000 --- a/docs/publish-docs-from-travis +++ /dev/null @@ -1,15 +0,0 @@ -#!/usr/bin/env bash - -set -e - -$(dirname $(dirname $0))/gradlew groovydoc && \ - cd $(dirname $0) && \ - ./gradlew --console=plain -q combineDocs - -if [[ "${TRAVIS_PULL_REQUEST}" == "false" && "${TRAVIS_REPO_SLUG}" == "asciidoctor/asciidoctor-gradle-plugin" ]] ; then - set -x - ./gradlew --console=plain :antora:publishDocs :gh-pages:publishDocs \ - -Dorg.ajoberstar.grgit.auth.username=$GITHUB_PUBLISH_USER \ - -Dorg.ajoberstar.grgit.auth.password=$GITHUB_PUBLISH_KEY \ - -Dorg.ajoberstar.grgit.auth.force=hardcoded -fi \ No newline at end of file diff --git a/docs/settings.gradle b/docs/settings.gradle deleted file mode 100644 index e8cf4cc4b..000000000 --- a/docs/settings.gradle +++ /dev/null @@ -1,4 +0,0 @@ -rootProject.name = 'asciidoctor-gradle-docs' - -includeBuild('..') -include 'gh-pages' From 32fa82889255b603c4ba69859632903283226011 Mon Sep 17 00:00:00 2001 From: Abel Salgado Romero Date: Sat, 9 Mar 2024 21:38:01 +0100 Subject: [PATCH 08/10] Ignore docs in CI --- .github/workflows/build.yaml | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml index e886629f1..24acffdf5 100644 --- a/.github/workflows/build.yaml +++ b/.github/workflows/build.yaml @@ -1,5 +1,14 @@ name: Build -on: [push, pull_request] +on: + push: + paths-ignore: + - '*.adoc' + - docs/** + pull_request: + paths-ignore: + - '*.adoc' + - docs/** + jobs: check: runs-on: ubuntu-latest From 8f4f923df33e48092efb677ec05f84776a3e24c2 Mon Sep 17 00:00:00 2001 From: Abel Salgado Romero Date: Sat, 9 Mar 2024 21:39:20 +0100 Subject: [PATCH 09/10] Fix antora.yml location --- docs/{modules => }/antora.yml | 0 docs/modules/ROOT/pages/common-task-configuration.adoc | 2 +- 2 files changed, 1 insertion(+), 1 deletion(-) rename docs/{modules => }/antora.yml (100%) diff --git a/docs/modules/antora.yml b/docs/antora.yml similarity index 100% rename from docs/modules/antora.yml rename to docs/antora.yml diff --git a/docs/modules/ROOT/pages/common-task-configuration.adoc b/docs/modules/ROOT/pages/common-task-configuration.adoc index e4580797f..8e5c6808f 100644 --- a/docs/modules/ROOT/pages/common-task-configuration.adoc +++ b/docs/modules/ROOT/pages/common-task-configuration.adoc @@ -271,7 +271,7 @@ asciidoctorj { // <1> asciidoctorjs { // <2> attributesForLang 'en', langName : 'English' - attributesForLang 'ca', langName : 'Catala'F + attributesForLang 'ca', langName : 'Catala' } ---- <1> Configuration when using {asciidoctorj-name} From b2678c7e68c989b428dccf04134f4a867fa11f90 Mon Sep 17 00:00:00 2001 From: Abel Salgado Romero Date: Sun, 10 Mar 2024 22:07:30 +0100 Subject: [PATCH 10/10] Fix project-repo-url --- docs/antora.yml | 2 +- docs/modules/appendices/pages/hacking.adoc | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/antora.yml b/docs/antora.yml index 7811dcac5..9da788455 100644 --- a/docs/antora.yml +++ b/docs/antora.yml @@ -6,7 +6,7 @@ asciidoc: release-version: 4.0.2 project-full-path: asciidoctor/asciidoctor-gradle-plugin project-name: asciidoctor-gradle-plugin - project-repo-url: asciidoctor-gradle-plugin + project-repo-url: https://github.com/asciidoctor/asciidoctor-gradle-plugin plugin-name: Asciidoctor Gradle plugin asciidoc-url: https://asciidoc.org asciidoc-docs: https://docs.asciidoctor.org/asciidoc/latest diff --git a/docs/modules/appendices/pages/hacking.adoc b/docs/modules/appendices/pages/hacking.adoc index ecfc718ef..18d3d9f65 100644 --- a/docs/modules/appendices/pages/hacking.adoc +++ b/docs/modules/appendices/pages/hacking.adoc @@ -7,4 +7,4 @@ Development for 4.x is against the link:{project-repo-url}/tree/{development-bra 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. +PRs for that should be raised against the link:{project-repo-url}/tree/maintenance-3.x[maintenance-3.x] branches.