gradle/guides

The Gradle Guides at https://guides.gradle.org.

stars

2,956

commits

Java

primary language

Sep 10, 2026

updated

gradle-bt

gradle-bt-documentation

Browse cluster: Gradle Build System and Plugins →

README

Note	All Gradle documentation content from this repository has been moved to the Gradle User Manual.

This is a collection of very opinionated plugins that support the authoring of documentations for Gradle.

org.gradle.guides: The single guide project plugin.
org.gradle.samples: The samples plugin.
org.gradle.documentation: Used to generate all type of documentation (currently only guides and samples).

How do I use the plugins?

Each of the plugins generates a guide from Asciidoc source.

Guide

The source for the guide is located in content/index.adoc
Run ./gradlew guidesMultiPage to generate the guide into build/working/guides/render-guides/<name-of-guide>/index.html.
Run ./gradlew view<NameOfGuide>Guide to generate the guide and open it in the browser.
Run ./gradlew check to execute all guide check.

Changelog

0.23.3

Fix compatibility with Gradle 9.0 (File Permission API)

0.23.2

Remove deprecated GUtil

0.23.1

Make all private @TaskAction methods public

0.23

Upgrade to the Asciidoctor plugin 4.0.1
Fix compatibility with Gradle 8.0

0.22

Remove unnecessary dependencies

0.21

Use tasks as the sanity check task instead of help

0.19.1

Use docs-asciidoctor-extension 0.11.0

0.19.0

Use exemplar 1.0.0
Force upgrade of asciidoctor-groovy-dsl to version 2.0.2 which can be resolved via Maven Central

0.18.0

Make compatible with Asciidoctor Gradle Plugin 3.x and AsciidoctorJ 2.x
Use exemplar 0.10.0

0.17.0

Allow duplicate entries for zipped samples

0.16.9

Update to support Gradle 7
Fix resources being included several times

0.16.6

Use Worker API for some sample related tasks so more things can run in parallel
Introduce new type of sample binary that does not have an associated zip

0.16.5

Skip asciidoctor-related validation tasks for non-promoted samples.
Include a common directory for samples by convention

0.16.4

Samples can be excluded from the samples index by setting the sample property to false.
Samples can overwrite generated sanity checks with explicit Exemplar tests
Exemplar tests located in the tests-groovy and tests-kotlin subdirectory are only executed for the target dsl variant.

0.16.3

Add samplesInformation to list information about samples and template
Fix kebab-case handling for template names

0.16.2

Avoid creating temporary directories during configuration phase

0.16.1

Normalize the trailing new lines from Gradle output

0.16.0

Refactoring of the internal of all plugins to share most of the implementation
Discontinue the Getting Started, Topical and Tutorial plugins in favor of a category property on each guides
Introduce the org.gradle.guide plugin opinionated to a single guide for the project (replacement for the discontinued plugins)
Introduce the org.gradle.documentation plugin for building all type of documentation
Introduce the Asciidoctor content testing for guides and samples
Remove usage of the org.ysb33r.cloudci and org.ysb33r.gradlerunner plugins
Improve clarity around the public and internal APIs

0.15.28

Add checkSamples to run sample checks
Disable checkstyle on generated tests

0.15.27

Major changes in samples plugin DSL

0.15.26

Honor Gradle wrapper execution flag on *nix system

0.15.25

Honor disabled Exemplar tests from previous test runs
Order sample index according to sample creation order inside build script
Capitalize the sample archive base name
Allow configuration of the sample permalink
Update Asciidoctor Gradle plugin to version 1.5.9.2

0.15.24

Allow Asciidoctor tasks to be cacheable

0.15.23

Avoid filtering any binary files in sample zips

0.15.22

Fix exemplar testing with generated content

0.15.21

Fix corrupted wrapper JAR in sample zips

0.15.20

Fix ClassNotFoundException with org.gradle.samples plugin

0.15.19

Allow sample display name to be customized (sample.displayName)
Pass sample display name to Asciidoctor generator as sample-displayName
Pass sample description to Asciidoctor generator as sample-description

0.15.18

Use Exemplar 0.9.0
Allow README Asciidoctor files to use sample extension
Remove Sample prefix to on the auto-generated sample index page
Remove .gradle and build directory from sample archives
Remove Asciidoctor tags from Gradle script files inside archives

0.15.17

Fix Exemplar tests for multiple samples

0.15.16

Introduce sample description on the model
Expose Asciidoctor task on the sample model
Disable checkstyle check on the Exemplar generated source
Automatically add the license file if available to all sample archives

0.15.15

Allow samples archive content to be customized
Allow samples archive content to be generated
Allow samples to be tested via Exemplar

0.15.14

Introduce the Gradle samples plugin.

0.15.13

Fix link to C++ guides.

0.15.12

Use https in LICENSE file.

0.15.11

Add GitHub repository configuration task to setupGuide.

0.15.10

Add conventions for the guide DSL:
- repositoryPath defaults to gradle-guides/${project.name}
- title defaults to title case of the project.name
- description defaults to title

0.15.9

Fix repoPath forwarding to repositoryPath property.
Remove usage of mainAuthor in preparation to removing the property.

0.15.8

Introduced repositoryPath property on the guide DSL to replace repoPath getter/setter.
Deprecate repoPath getter/setter.
Add setup tasks to generate common files:
- .github/CODE_OF_CONDUCT.md generated by GenerateCodeOfConductFile
- .github/dco.yml generated by GenerateDeveloperCertificateOfOriginConfiguration
- .gitignore generated by GenerateGitIgnoreConfiguration
- .editorconfig generated by GenerateEditorConfiguration
- LICENSE generated by GenerateLicenseFile
- README.adoc generated by GenerateReadeMeFile
Add setupGuide lifecycle task to configure everything about a guide by generating the common files above and configure the GitHub repository description and homepage.

0.15.7

Model the minimum Gradle version of a guide by introducing minimumGradleVersion property on the guide DSL.

0.15.6

More reliable viewGuide implementation.
The standard assemble task also generates the guide output.

Plugins development

Releasing the plugins

Edit build.gradle.kts and replace -SNAPSHOT version with the version to release.
Edit this README to update the changes section.
Commit and create tag, e.g. git tag v0.15.9.
Push changes and tag to master, e.g. git push && git push origin v0.15.9
Run the Publish Documentation Plugins build on TeamCity.
Create GitHub release.
Edit build.gradle.kts and replace version with -SNAPSHOT for next version.

Contributors

(top 30 of 81)

695 commits

455 commits

314 commits

207 commits

Similar repos

gradle/gradle-site-plugin

shared topics

gradle/exemplar

Discover and verify code samples and services

shared contributors

gradle/gradle-profiler

A tool for gathering profiling and benchmarking information for Gradle builds

1,531

shared contributors

gradle/playframework

Gradle Play Support

shared contributors

gradle/gradle

Adaptable, fast automation for all

18,825

shared contributors

gradle/develocity-build-config-samples

Code samples that demonstrate how to customize your Develocity build configuration using Gradle,…

shared contributors

asciidoctor/asciidoctor-gradle-plugin

A Gradle plugin that uses Asciidoctor via JRuby to process AsciiDoc source files within the project.

302

shared contributors

gradle/native-samples

Samples of modern build automation for native languages with Gradle

157

shared contributors

Languages

Java

64.1%

Groovy

35.9%

gradle/guides

The Gradle Guides at https://guides.gradle.org.

stars

2,956

commits

Java

primary language

Sep 10, 2026

updated

gradle-bt

gradle-bt-documentation

Browse cluster: Gradle Build System and Plugins →

README

Note	All Gradle documentation content from this repository has been moved to the Gradle User Manual.

This is a collection of very opinionated plugins that support the authoring of documentations for Gradle.

org.gradle.guides: The single guide project plugin.
org.gradle.samples: The samples plugin.
org.gradle.documentation: Used to generate all type of documentation (currently only guides and samples).

How do I use the plugins?

Each of the plugins generates a guide from Asciidoc source.

Guide

The source for the guide is located in content/index.adoc
Run ./gradlew guidesMultiPage to generate the guide into build/working/guides/render-guides/<name-of-guide>/index.html.
Run ./gradlew view<NameOfGuide>Guide to generate the guide and open it in the browser.
Run ./gradlew check to execute all guide check.

Changelog

0.23.3

Fix compatibility with Gradle 9.0 (File Permission API)

0.23.2

Remove deprecated GUtil

0.23.1

Make all private @TaskAction methods public

0.23

Upgrade to the Asciidoctor plugin 4.0.1
Fix compatibility with Gradle 8.0

0.22

Remove unnecessary dependencies

0.21

Use tasks as the sanity check task instead of help

0.19.1

Use docs-asciidoctor-extension 0.11.0

0.19.0

Use exemplar 1.0.0
Force upgrade of asciidoctor-groovy-dsl to version 2.0.2 which can be resolved via Maven Central

0.18.0

Make compatible with Asciidoctor Gradle Plugin 3.x and AsciidoctorJ 2.x
Use exemplar 0.10.0

0.17.0

Allow duplicate entries for zipped samples

0.16.9

Update to support Gradle 7
Fix resources being included several times

0.16.6

Use Worker API for some sample related tasks so more things can run in parallel
Introduce new type of sample binary that does not have an associated zip

0.16.5

Skip asciidoctor-related validation tasks for non-promoted samples.
Include a common directory for samples by convention

0.16.4

Samples can be excluded from the samples index by setting the sample property to false.
Samples can overwrite generated sanity checks with explicit Exemplar tests
Exemplar tests located in the tests-groovy and tests-kotlin subdirectory are only executed for the target dsl variant.

0.16.3

Add samplesInformation to list information about samples and template
Fix kebab-case handling for template names

0.16.2

Avoid creating temporary directories during configuration phase

0.16.1

Normalize the trailing new lines from Gradle output

0.16.0

Refactoring of the internal of all plugins to share most of the implementation
Discontinue the Getting Started, Topical and Tutorial plugins in favor of a category property on each guides
Introduce the org.gradle.guide plugin opinionated to a single guide for the project (replacement for the discontinued plugins)
Introduce the org.gradle.documentation plugin for building all type of documentation
Introduce the Asciidoctor content testing for guides and samples
Remove usage of the org.ysb33r.cloudci and org.ysb33r.gradlerunner plugins
Improve clarity around the public and internal APIs

0.15.28

Add checkSamples to run sample checks
Disable checkstyle on generated tests

0.15.27

Major changes in samples plugin DSL

0.15.26

Honor Gradle wrapper execution flag on *nix system

0.15.25

Honor disabled Exemplar tests from previous test runs
Order sample index according to sample creation order inside build script
Capitalize the sample archive base name
Allow configuration of the sample permalink
Update Asciidoctor Gradle plugin to version 1.5.9.2

0.15.24

Allow Asciidoctor tasks to be cacheable

0.15.23

Avoid filtering any binary files in sample zips

0.15.22

Fix exemplar testing with generated content

0.15.21

Fix corrupted wrapper JAR in sample zips

0.15.20

Fix ClassNotFoundException with org.gradle.samples plugin

0.15.19

Allow sample display name to be customized (sample.displayName)
Pass sample display name to Asciidoctor generator as sample-displayName
Pass sample description to Asciidoctor generator as sample-description

0.15.18

Use Exemplar 0.9.0
Allow README Asciidoctor files to use sample extension
Remove Sample prefix to on the auto-generated sample index page
Remove .gradle and build directory from sample archives
Remove Asciidoctor tags from Gradle script files inside archives

0.15.17

Fix Exemplar tests for multiple samples

0.15.16

Introduce sample description on the model
Expose Asciidoctor task on the sample model
Disable checkstyle check on the Exemplar generated source
Automatically add the license file if available to all sample archives

0.15.15

Allow samples archive content to be customized
Allow samples archive content to be generated
Allow samples to be tested via Exemplar

0.15.14

Introduce the Gradle samples plugin.

0.15.13

Fix link to C++ guides.

0.15.12

Use https in LICENSE file.

0.15.11

Add GitHub repository configuration task to setupGuide.

0.15.10

Add conventions for the guide DSL:
- repositoryPath defaults to gradle-guides/${project.name}
- title defaults to title case of the project.name
- description defaults to title

0.15.9

Fix repoPath forwarding to repositoryPath property.
Remove usage of mainAuthor in preparation to removing the property.

0.15.8

Introduced repositoryPath property on the guide DSL to replace repoPath getter/setter.
Deprecate repoPath getter/setter.
Add setup tasks to generate common files:
- .github/CODE_OF_CONDUCT.md generated by GenerateCodeOfConductFile
- .github/dco.yml generated by GenerateDeveloperCertificateOfOriginConfiguration
- .gitignore generated by GenerateGitIgnoreConfiguration
- .editorconfig generated by GenerateEditorConfiguration
- LICENSE generated by GenerateLicenseFile
- README.adoc generated by GenerateReadeMeFile
Add setupGuide lifecycle task to configure everything about a guide by generating the common files above and configure the GitHub repository description and homepage.

0.15.7

Model the minimum Gradle version of a guide by introducing minimumGradleVersion property on the guide DSL.

0.15.6

More reliable viewGuide implementation.
The standard assemble task also generates the guide output.

Plugins development

Releasing the plugins

Edit build.gradle.kts and replace -SNAPSHOT version with the version to release.
Edit this README to update the changes section.
Commit and create tag, e.g. git tag v0.15.9.
Push changes and tag to master, e.g. git push && git push origin v0.15.9
Run the Publish Documentation Plugins build on TeamCity.
Create GitHub release.
Edit build.gradle.kts and replace version with -SNAPSHOT for next version.