Name	Name	Last commit message	Last commit date
parent directory ..
docs-asciidoctor-extensions-base	docs-asciidoctor-extensions-base
docs-asciidoctor-extensions	docs-asciidoctor-extensions
docs	docs
samples	samples

Gradle Documentation Contributor Guide

Purpose: This guide is for contributors writing or editing documentation for the gradle/gradle repository. It covers structure, authoring conventions, code samples, and testing.

AI Usage: This document is structured for both human contributors and AI assistants (e.g., Copilot, Cursor, Claude). It is intended to be ingested as a system prompt or context file to guide AI-assisted documentation contributions. All rules and conventions stated here should be treated as authoritative and followed strictly when generating or editing .adoc files, code snippets, or any other documentation artifacts in this repository.

Overview

The docs project produces:

All file paths in this guide are relative to the docs project directory unless stated otherwise.

Build Logic

The documentation build is driven by plugins in build-logic/documentation/. The root plugin gradlebuild.documentation is applied in build.gradle.kts and applies the per-document-type sub-plugins below.

Plugins

Plugin	Responsibility
`GradleBuildDocumentationPlugin`	Root plugin. Creates the `gradleDocumentation` extension, configures the Asciidoctor toolchain, and applies the sub-plugins.
`GradleReleaseNotesPlugin`	Converts `notes.md` to HTML.
`GradleUserManualPlugin`	Registers Asciidoctor tasks for the multi-page and single-page user manual. Also generates the default-imports and API-mapping files used by the DSL reference.
`GradleDslReferencePlugin`	Generates the Groovy DSL reference from Docbook sources and extracted code doc comments.
`GradleKotlinDslReferencePlugin`	Runs Dokka to produce the Kotlin DSL reference.
`GradleJavadocsPlugin`	Generates Javadoc for the full Gradle distribution.

The `gradleDocumentation` extension

The extension is the configuration surface used by build.gradle.kts.

Top-level properties:

Property	Purpose
`sourceRoot`	Root directory of all documentation inputs (defaults to `src/docs`).
`stagingRoot`	Working directory for in-flight rendered output (defaults to `build/working`).
`documentationRenderedRoot`	Final location of all rendered documentation (defaults to `build/docs`).
`gradleVersion`	Gradle version embedded in the documentation.
`gradleVersion8`	Latest Gradle 8.x patch version, auto-derived from `released-versions.json`.
`quickFeedback`	When `true` (via `-PquickDocs`), slow tasks (single-page manual, DSL reference) are skipped.

The extension also exposes nested configurations for each documentation type:

Configuration	Configures
`releaseNotes { ... }`	Release-notes source and rendered output locations.
`userManual { ... }`	Staging directories, snippet sources, raw and rendered output paths.
`dslReference { ... }`	Generated metadata file, rendered output location.
`javadocs { ... }`	`javaApi`, `javadocReferenceUrl`, `minJdkVersion`, `groovyApi`, package-list paths, CSS file.
`kotlinDslReference { ... }`	Dokka configuration and rendered output.

Build flow

Source — Each documentation type reads from a subdirectory of src/docs/ (or from generated metadata such as the DSL meta-data file).
Stage — The user manual stages flattened .adoc sources, snippets, images, and CSS into build/working/usermanual/raw/ via the stageUserguideSource task.
Render — Asciidoctor (userguideMultiPage, userguideSinglePageHtml) and Dokka render the staged sources into build/working/<doc-type>/render-*/.
Publish — stageDocs collects every rendered output into build/docs/ (multi-page manual under userguide/, DSL under dsl/, Javadoc under javadoc/, Kotlin DSL under kotlin-dsl/).
Consume — The gradleFullDocsElements configuration exposes build/docs/ as an outgoing artifact for downstream packaging (distribution zips, the docs.gradle.org deploy).

Release Notes

Source file: src/docs/release/notes.md - authored in Markdown

Follow the instructions in notes.md.

Release notes are one of the main ways Gradle conveys information about improvements to users. We expect that users will upgrade Gradle more readily if they can understand the benefits of said upgrade.

"New features and usability improvements" content

We want the "New features and usability improvements" to be more than just a change log. It is a copyedited description of the main benefits of a given release, and it does not aim for completeness.

What should be in the "New features" section

For a change to make it to the "New features and usability improvements" section, it should be a feature or improvement in either:

The Gradle distribution
Another component maintained by the Gradle team tied directly to the given Gradle release

Major features or efforts should be introduced through release notes:

When they are ready for early adopters
When they are stable

And it should fall into one of the following categories:

A new feature, incubating or not, that we expect users to try, give feedback, and/or adopt
A bug fix with an important impact on users, such as:
- A highly voted issue
- An issue with a high potential impact

Note: Users are anyone matching one of our proto personas.

How a release note entry should be presented

Each entry should have the following characteristics:

Sets the context — what are we even talking about (don't assume too much about what the user already knows)
Expresses the problem or use case in the given context
Explains how the new release addresses that problem or use case
Has backing documentation in the user manual, DSL doc, javadoc, or the upgrade guide. The "New features and usability improvements" section highlights the feature but should never be the only documentation.
Links to that documentation
Contains example(s):
- Code snippet
- After/before output
- After/before behavior
Optional: Video/screencast for major changes. If possible, include them in the release changelog for better promotion of new features. The same video can be included in the integrated release video later.

What should not be in the "New features" section

The following changes are not intended to be in the "New features and usability improvements":

Internal features. They are mainly defined by things users should either never use or not yet use.
Behavior changes that might break users. These go to the upgrade guide or a potential new section.
Promoted features, aside from major efforts. These go to their dedicated section. We assume they were release noted before being promoted.
Very early experimental features intended for invite-only audiences (possibly hidden behind an internal flag).

Generating Release Notes

./gradlew :docs:releaseNotes

Markdown References

Markdown Cheat Sheet

User Manual

Source: src/docs/userguide/ — authored in Asciidoctor

Build Commands

Goal	Command
Full preview (recommended)	`./gradlew stageDocs`
Full preview with continuous rebuild	`./gradlew stageDocs -t`
Full preview with fast iteration	`./gradlew stageDocs -PquickDocs`
Live reload at `http://localhost:8000`	`./gradlew serveDocs`
User manual only (links may break)	`./gradlew :docs:userguide`
Multi-page HTML manual only	`./gradlew :docs:userguideMultiPage`
Single-page HTML manual only	`./gradlew :docs:userguideSinglePageHtml`
Javadoc only	`./gradlew :docs:javadocAll`
Run all snippet and sample tests	`./gradlew :docs:docsTest`

The -PquickDocs flag skips slow tasks (DSL reference, single-page manual). Rebuild time in quick mode is approximately 30–40 seconds. The t and -PquickDocs flags can be used by the serveDocs task as well.

Output locations:

Multi-page HTML: build/working/usermanual/render-multi/ (one .html per .adoc)
Single-page HTML: build/working/usermanual/render-single-html/userguide_single.html
All staged docs: build/docs/

AsciiDoc References

Cross-References and Linking

Good cross-references help readers navigate, but too many become disruptive.

Follow these guidelines:

Be selective. Every link adds cognitive load and risks pulling readers away from the page. Only include links that are genuinely useful.
Provide context on the page. When a term, concept, or brief set of steps can be explained in a few sentences, do so rather than linking out.
Avoid duplicate links. Link to the same destination only once per page, unless sections are far apart or serve different entry points (e.g., a procedure and a troubleshooting section).
Link to the most relevant destination. Target the most specific relevant page or heading. Don't provide multiple links that serve the same purpose.

For third-party content, avoid links unless absolutely necessary. If a brief explanation covers what readers need, provide it on the page. Reserve third-party links for cases where the full external resource is genuinely required.

Linking to DSL and API References

Whenever you reference a Gradle API class, method, or annotation in prose, link it to the relevant reference documentation. Three path attributes are available:

Attribute	Points to
`{javadocPath}`	Javadoc (use for Java API classes and annotations)
`{groovyDslPath}`	Groovy DSL reference
`{kotlinDslPath}`	Kotlin DSL reference

link:{javadocPath}/org/gradle/process/CommandLineArgumentProvider.html[`CommandLineArgumentProvider`]
link:{javadocPath}/org/gradle/api/tasks/CacheableTask.html[`@CacheableTask`]
link:{groovyDslPath}/org.gradle.api.tasks.javadoc.Groovydoc.html[`Groovydoc`]
link:{groovyDslPath}/org.gradle.api.Project.html#org.gradle.api.Project:afterEvaluate(org.gradle.api.Action)[`Project.afterEvaluate()`]
link:{kotlinDslPath}/gradle/org.gradle.api.tasks/-task-container/index.html[`register()`]
link:{kotlinDslPath}/gradle/org.gradle.api/-project/get-project-dir.html[`Project.projectDir`]

Always wrap link text in backticks for any code identifier — classes, methods, properties, and annotations alike.

Images

Images live in docs/src/userguide/img/. Formats include GIF, GRAPHML, SVG, PNG, and JPEG. Smaller size files are preferred.

To embed an image in an .adoc file:

image::performance/performance-1.png[]

The path is relative to the src/docs/img/ directory.

Do not submit images as part of a PR to gradle/gradle. All images must be created and approved by the Gradle documentation team.

Anchors

Every heading should have an anchor declared on the line immediately above it. This enables direct linking from other pages. Anchor IDs should use snake_case.

Heading level	Anchor required?
`=` (page title)	Required
`==` (section)	Required
`===` (subsection)	As needed
`====` (sub-subsection)	As needed

[[incremental_build]]
= Incremental Build

[[sec:task_inputs_outputs]]
== Task Inputs and Outputs

To link to an anchor from another page:

<<incremental_build.adoc#incremental_build,incremental build>>
<<incremental_build.adoc#sec:task_inputs_outputs,defined outputs>>

To link to an anchor on the same page, omit the filename:

<<sec:task_inputs_outputs,defined outputs>>
<<#sec:task_inputs_outputs,defined outputs>>

Renaming or Deleting a Chapter

When an .adoc file is renamed or deleted, you must add a redirect entry to the /redirect folder so that existing links to the old page continue to work.

Adding a New Page

Create <page-name>.adoc in an appropriate subdirectory of src/docs/userguide/.
Add the license header at the top of every new .adoc file. See the Gradle Contributing Guide for the exact license text to use.
```
[[toolchains]]
= Toolchains for JVM Projects
```

Add the file to src/docs/userguide/userguide_single.adoc.

<<toolchains.adoc#toolchains,Toolchains for JVM Projects>>

Add a relative link to the chapter in src/main/resources/header.html.

<li><a href="../userguide/toolchains.html">Toolchains for JVM projects</a></li>

Checking for Broken Links

Always run the following after making changes to ensure no internal links are broken:

./gradlew :docs:checkDeadInternalLinks

Code Snippets and Testing Docs

The docs:docsTest task tests code snippets located in src/snippets/. Snippets are included inline in the user manual and are the standard way to add tested code examples.

To fully understand how to write and test code snippets in the Gradle documentation, see @platforms/documentation/docs/src/docs/rules/snippets.md

`org.gradle.samples` plugin

The main build file for documentation, platforms/documentation/docs/build.gradle.kts, applies the org.gradle.samples plugin.

The source code of this plugin is here. This plugin adds a Samples extension named samples.

This samples extension is configured in platforms/documentation/docs/build.gradle.kts. All snippets are auto-discovered and assembled into samples.publishedSamples, as follows:

┌────────────────────────────────────┐
│ documentation/docs/build.gradle.kts│
│                                    │
│  samples {                         │    ┌─────────────────────────────────┐
│    ...                             │    │ code snippets in src/snippets   ├───┐
│    publishedSamples {  ────────────┼───►│                                 │   │
│      ...                           │    └─────────────────────────────────┘   │
└────────────────────────────────────┘                                          │
                                                                                │
                                        ┌───────────────────────────────────┐   │
                                        │ org.gradle.samples plugin         │   │
                                        │ ┌─────────────────────────────┐   │   │
┌─────────────┐   Install samples to    │ │ Samples.publishedSamples    │   │   │
│  Exemplar   │   local directory and   │ │                             │   │   │
│             │   test with exemplar    │ │                             │   │   │
│             │◄────────────────────────┤ │                             ◄───┼───┘
│             │                         │ │                             │   │
└─────────────┘                         │ │                             │   │
                                        │ └─────────────────────────────┘   │
                                        │                                   │
                                        └───────────────────────────────────┘

The elements in samples.publishedSamples container are installed into a local directory (by default docs/build/working/samples/install) as Exemplar samples.

Style Guides

All documentation contributions must follow these style guides:

User Manual (.adoc files): Follow the Microsoft Writing Style Guide.
Javadoc: Follow the Gradle Javadoc Style Guide.

Write one sentence per line in .adoc and .md files; this makes diffs cleaner and PRs easier to review.

Always leave a blank line after any heading (=, ==, ===, ====) before the body text begins. This is required by AsciiDoc for the heading to be parsed correctly, and it keeps the source readable.

=== Explanation

The root project defines the overall structure of a composite build.

Not:

=== Explanation
The root project defines the overall structure of a composite build.

Groovy DSL Reference

Source: src/docs/dsl/ — authored in Docbook syntax. Much content is extracted from code doc comments

Build

./gradlew :docs:dslHtml

Output: build/working/dsl/

Useful Custom Tags

<apilink> — Links to the DSL reference or Javadoc for a class or method.

Link to a class:

You can use the <apilink class='org.gradle.api.Project' /> interface to do stuff.

Link to a method:

<apilink class='org.gradle.api.Project' method="apply(java.util.Map)" />

For the full list of standard Docbook tags, see the Docbook reference.

Javadoc

Source: gradle/* — javadoc can be found in many java files in the Gradle codebase

./gradlew :docs:javadocAll

Output: build/javadoc/

Build All Docs

./gradlew :docs:docs

Navigation Menu

README.md

Gradle Documentation Contributor Guide

Overview

Build Logic

Plugins

The `gradleDocumentation` extension

Build flow

Release Notes

"New features and usability improvements" content

What should be in the "New features" section

How a release note entry should be presented

What should not be in the "New features" section

Generating Release Notes

Markdown References

User Manual

Build Commands

AsciiDoc References

Cross-References and Linking

Linking to DSL and API References

Images

Anchors

Renaming or Deleting a Chapter

Adding a New Page

Checking for Broken Links

Code Snippets and Testing Docs

`org.gradle.samples` plugin

Style Guides

Groovy DSL Reference

Build

Useful Custom Tags

Javadoc

Build All Docs

FilesExpand file tree

documentation

Directory actions

More options

Directory actions

More options

Latest commit

History

documentation

Folders and files

parent directory

README.md

Gradle Documentation Contributor Guide

Overview

Build Logic

Plugins

The gradleDocumentation extension

Build flow

Release Notes

"New features and usability improvements" content

What should be in the "New features" section

How a release note entry should be presented

What should not be in the "New features" section

Generating Release Notes

Markdown References

User Manual

Build Commands

AsciiDoc References

Cross-References and Linking

Linking to DSL and API References

Images

Anchors

Renaming or Deleting a Chapter

Adding a New Page

Checking for Broken Links

Code Snippets and Testing Docs

org.gradle.samples plugin

Style Guides

Groovy DSL Reference

Build

Useful Custom Tags

Javadoc

Build All Docs

The `gradleDocumentation` extension

`org.gradle.samples` plugin