This is an automated email from the ASF dual-hosted git repository.

slachiewicz pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven-checkstyle-plugin.git


The following commit(s) were added to refs/heads/master by this push:
     new e9bbdd9  Refresh the plugin site and README
e9bbdd9 is described below

commit e9bbdd95b4ac1298b6b34bff57146b58743d5723
Author: Sylwester Lachiewicz <[email protected]>
AuthorDate: Tue Nov 17 23:13:13 2026 +0000

    Refresh the plugin site and README
---
 README.md                                          | 119 +++++++---------
 .../markdown/examples/custom-checker-config.md.vm  |  16 ++-
 .../examples/custom-developed-checkstyle.md.vm     | 155 +++++++++++----------
 .../examples/custom-property-expansion.md.vm       |   8 +-
 .../markdown/examples/inline-checker-config.md.vm  | 107 +++++---------
 .../markdown/examples/multi-module-config.md.vm    |  14 +-
 .../markdown/examples/suppressions-filter.md.vm    |  13 +-
 .../markdown/examples/upgrading-checkstyle.md.vm   |  20 ++-
 src/site/markdown/faq.md                           |  33 +++--
 src/site/markdown/history.md.vm                    |  46 +++---
 src/site/markdown/index.md.vm                      |  85 ++++++-----
 src/site/markdown/usage.md.vm                      | 141 +++++++++++--------
 src/site/site.xml                                  |   2 +-
 13 files changed, 387 insertions(+), 372 deletions(-)

diff --git a/README.md b/README.md
index c9d2872..cac7a95 100644
--- a/README.md
+++ b/README.md
@@ -14,71 +14,54 @@
  See the License for the specific language governing permissions and
  limitations under the License.
 -->
-Contributing to [Apache Maven Checkstyle 
Plugin](https://maven.apache.org/plugins/maven-checkstyle-plugin/)
-======================
-
-[![Apache License, Version 2.0, January 
2004](https://img.shields.io/github/license/apache/maven.svg?label=License)][license]
-[![Maven 
Central](https://img.shields.io/maven-central/v/org.apache.maven.plugins/maven-checkstyle-plugin.svg?label=Maven%20Central)](https://search.maven.org/artifact/org.apache.maven.plugins/maven-checkstyle-plugin)
-[![Reproducible 
Builds](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/jvm-repo-rebuild/reproducible-central/master/content/org/apache/maven/plugins/maven-checkstyle-plugin//badge.json)](https://github.com/jvm-repo-rebuild/reproducible-central/blob/master/content/org/apache/maven/plugins/maven-checkstyle-plugin/README.md)
-[![Jenkins 
Status](https://img.shields.io/jenkins/s/https/ci-maven.apache.org/job/Maven/job/maven-box/job/maven-checkstyle-plugin/job/master.svg?)][build]
-[![Jenkins 
tests](https://img.shields.io/jenkins/t/https/ci-maven.apache.org/job/Maven/job/maven-box/job/maven-checkstyle-plugin/job/master.svg?)][test-results]
-
-
-You have found a bug, or you have an idea for a cool new feature? Contributing
-code is a great way to give something back to the open source community. Before
-you dig right into the code, there are a few guidelines that we need
-contributors to follow so that we can have a chance of keeping on top of
-things.
-
-Getting Started
----------------
-
-+ Make sure you have a [GitHub account](https://github.com/signup/free).
-+ If you're planning to implement a new feature, it makes sense to discuss 
your changes 
-  on the [dev list][ml-list] first. 
-  This way you can make sure you're not wasting your time on something that 
isn't 
-  considered to be in Apache Maven's scope.
-+ Submit a ticket for your issue, assuming one does not already exist.
-  + Clearly describe the issue, including steps to reproduce when it is a bug.
-  + Make sure you fill in the earliest version that you know has the issue.
-+ Fork the repository on GitHub.
-
-Making and Submitting Changes
---------------
-
-We accept Pull Requests via GitHub. The [developer mailing list][ml-list] is 
the
-main channel of communication for contributors.  
-There are some guidelines which will make applying PRs easier for us:
-+ Create a topic branch from where you want to base your work (this is usually 
the master branch).
-  Push your changes to a topic branch in your fork of the repository.
-+ Make commits of logical units.
-+ Respect the original code style: by using the same [codestyle][code-style],
-  patches should only highlight the actual difference, not being disturbed by 
any formatting issues:
-  + Only use spaces for indentation.
-  + Create minimal diffs - disable on save actions like reformat source code 
or organize imports. 
-    If you feel the source code should be reformatted, create a separate PR 
for this change.
-  + Check for unnecessary whitespace with `git diff --check` before committing.
-+ Make sure you have added the necessary tests (JUnit/IT) for your changes.
-+ Run all the tests with `mvn -Prun-its verify` to assure nothing else was 
accidentally broken.
-+ Submit a pull request to the repository in the Apache organization.
-
-If you plan to contribute on a regular basis, please consider filing a 
[contributor license agreement][cla].
-
-Additional Resources
---------------------
-
-+ [Contributing 
patches](https://maven.apache.org/guides/development/guide-maven-development.html#Creating_and_submitting_a_patch)
-+ [Contributor License Agreement][cla]
-+ [General GitHub documentation](https://help.github.com/)
-+ [GitHub pull request 
documentation](https://help.github.com/send-pull-requests/)
-+ [Apache Maven X Account](https://x.com/ASFMavenProject)
-+ [Apache Maven Bluesky Account](https://bsky.app/profile/maven.apache.org)
-+ [Apache Maven Mastodon 
Account](https://mastodon.social/deck/@[email protected])
-
-[license]: https://www.apache.org/licenses/LICENSE-2.0
-[ml-list]: https://maven.apache.org/mailing-lists.html
-[code-style]: https://maven.apache.org/developers/conventions/code.html
-[cla]: https://www.apache.org/licenses/#clas
-[maven-wiki]: https://cwiki.apache.org/confluence/display/MAVEN/Index
-[test-results]: 
https://ci-maven.apache.org/job/Maven/job/maven-box/job/maven-checkstyle-plugin/job/master/lastCompletedBuild/testReport/
-[build]: 
https://ci-maven.apache.org/job/Maven/job/maven-box/job/maven-checkstyle-plugin/job/master/
+
+# Apache Maven Checkstyle Plugin
+
+[![Apache License, Version 2.0, January 
2004](https://img.shields.io/github/license/apache/maven.svg?label=License)](https://www.apache.org/licenses/LICENSE-2.0)
+[![Maven 
Central](https://img.shields.io/maven-central/v/org.apache.maven.plugins/maven-checkstyle-plugin.svg?label=Maven%20Central)](https://central.sonatype.com/artifact/org.apache.maven.plugins/maven-checkstyle-plugin)
+[![Reproducible 
Builds](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/jvm-repo-rebuild/reproducible-central/master/content/org/apache/maven/plugins/maven-checkstyle-plugin/badge.json)](https://github.com/jvm-repo-rebuild/reproducible-central/blob/master/content/org/apache/maven/plugins/maven-checkstyle-plugin/README.md)
+[![Verify](https://github.com/apache/maven-checkstyle-plugin/actions/workflows/maven-verify.yml/badge.svg)](https://github.com/apache/maven-checkstyle-plugin/actions/workflows/maven-verify.yml)
+
+Runs [Checkstyle](https://checkstyle.org/) on a Maven project. The `check` goal
+logs violations and fails the build; the `checkstyle` and 
`checkstyle-aggregate`
+goals write an HTML report, on their own or as part of the project site.
+
+```shell
+mvn checkstyle:check
+mvn checkstyle:checkstyle
+```
+
+The plugin requires Maven 3.9.0 and Java 8, and runs Checkstyle 9.3 by default.
+Projects can [use a newer 
Checkstyle](https://maven.apache.org/plugins/maven-checkstyle-plugin/examples/upgrading-checkstyle.html)
+by adding it as a plugin dependency.
+
+- Documentation: <https://maven.apache.org/plugins/maven-checkstyle-plugin/>
+- Issues: <https://github.com/apache/maven-checkstyle-plugin/issues>
+- Security reports: see [SECURITY.md](SECURITY.md); never a public issue
+- Agents and automated tools: see [AGENTS.md](AGENTS.md)
+
+## Build
+
+```shell
+mvn verify
+```
+
+Run the integration tests in `src/it` with the `run-its` profile:
+
+```shell
+mvn -Prun-its verify
+```
+
+Build the plugin site, including the goal pages, with:
+
+```shell
+mvn install -DskipTests
+mvn site -Preporting
+```
+
+## Contributing
+
+Open a pull request against `master`. Discuss larger changes on the
+[developer mailing list](https://maven.apache.org/mailing-lists.html) first. 
See the
+[guide to helping with 
Maven](https://maven.apache.org/guides/development/guide-helping.html)
+for the general process.
diff --git a/src/site/markdown/examples/custom-checker-config.md.vm 
b/src/site/markdown/examples/custom-checker-config.md.vm
index 5e00f38..d1e499b 100644
--- a/src/site/markdown/examples/custom-checker-config.md.vm
+++ b/src/site/markdown/examples/custom-checker-config.md.vm
@@ -23,6 +23,8 @@ specific language governing permissions and limitations
 under the License.
 -->
 
+<a id="Using_a_Custom_Checkstyle_Checker_Configuration"></a>
+
 # Custom Checkstyle Checker Configuration
 
 You can define a custom [Checker configuration xml 
file](https://checkstyle.org/config.html#Checker).
@@ -49,11 +51,13 @@ Use the `configLocation` parameter to reference a custom 
Checkstyle Checker conf
 </project>
 ```
 
-This example makes the plugin check for a file named `checkstyle.xml`.
-It can find the file in the compile scope of the dependencies or in the build 
extensions classpath.
+With this example, the plugin looks for `checkstyle.xml` in these places:
+
+- as a file, relative to the project directory or to the directory of a parent 
project;
+- as a URL;
+- as a resource on the plugin classpath, for example in a JAR that you add as 
a plugin dependency, as the [multimodule example](./multi-module-config.html) 
shows.
 
-The Checkstyle Plugin ships with two predefined configuration definitions.
-It selects the Sun Microsystems definition by default.
+Two predefined configurations ship with Checkstyle, and the plugin uses the 
Sun one by default:
 
-- **sun_checks.xml** - Sun Microsystems Definition (default).
-- **google_checks.xml** - Google Definition.
+- `sun_checks.xml`: [Sun code 
conventions](https://checkstyle.org/sun_style.html) (default).
+- `google_checks.xml`: [Google Java 
Style](https://checkstyle.org/google_style.html).
diff --git a/src/site/markdown/examples/custom-developed-checkstyle.md.vm 
b/src/site/markdown/examples/custom-developed-checkstyle.md.vm
index b5002aa..9744982 100644
--- a/src/site/markdown/examples/custom-developed-checkstyle.md.vm
+++ b/src/site/markdown/examples/custom-developed-checkstyle.md.vm
@@ -23,17 +23,18 @@ specific language governing permissions and limitations
 under the License.
 -->
 
+<a id="Using_Custom_Developed_Checkstyle_Checks"></a>
+
 # Custom Developed Checkstyle Checks
 
-This example shows how to create a Maven project for your custom checks.
-The project generates a jar file.
-You then use the jar file in your other projects.
-You add the jar file as a dependency to the Checkstyle Plugin.
+This example shows how to create a Maven project for your own Checkstyle 
checks.
+The project builds a JAR file, which you add as a dependency of the Checkstyle 
Plugin in your other projects.
+
+A [package names file](https://checkstyle.org/config.html#Packages) named 
`checkstyle_packages.xml` in the JAR lets your Checkstyle configuration refer 
to the checks by their short names.
 
-The plugin also lets you define the [package names XML 
document](https://checkstyle.org/config.html#Packages).
-This document lets Checkstyle reference your custom check modules.
+This example uses the [example 
check](https://checkstyle.org/writing-checks.html#Visitor_in_action) from the 
Checkstyle website.
 
-This example uses the [example 
check](https://checkstyle.org/writingchecks.html#Visitor_in_action) from the 
Checkstyle website.
+<a id="Structuring_your_project"></a>
 
 Project Structure
 -----------------
@@ -45,12 +46,13 @@ mycompany-checkstyle-checks
 |-- pom.xml
 `-- src
     `-- main
-        `-- java
-            `-- com
-                `-- mycompany
-                    `-- checks
-                        |-- packagenames.xml
-                        `-- MethodLimitCheck.java
+        |-- java
+        |   `-- com
+        |       `-- mycompany
+        |           `-- checks
+        |               `-- MethodLimitCheck.java
+        `-- resources
+            `-- checkstyle_packages.xml
 ```
 
 The sections below describe the three files.
@@ -58,6 +60,7 @@ The sections below describe the three files.
 #[[### `pom.xml`]]#
 
 This POM adds a dependency on Checkstyle.
+Use the Checkstyle version that the plugin runs; the `provided` scope keeps it 
out of your JAR's dependencies.
 
 ```xml
 <project>
@@ -68,20 +71,22 @@ This POM adds a dependency on Checkstyle.
   <version>1.0</version>
   <dependencies>
     <dependency>
-      <groupId>checkstyle</groupId>
+      <groupId>com.puppycrawl.tools</groupId>
       <artifactId>checkstyle</artifactId>
-        <version>${project.version}</version>
+      <version>${checkstyleVersion}</version>
+      <scope>provided</scope>
     </dependency>
   </dependencies>
 </project>
 ```
 
-#[[### `packagenames.xml`]]#
+<a id="packagenames.xml"></a>
 
-This file lets you specify the names of the packages that you want to use.
-This example adds `com.mycompany.checks` to the standard set of Checkstyle 
packages.
-You can then use your custom checks in the Checkstyle configuration file.
-You do not need to specify their package name.
+#[[### `checkstyle_packages.xml`]]#
+
+Checkstyle reads every `checkstyle_packages.xml` file at the root of the 
classpath.
+This one adds `com.mycompany.checks` to the packages that Checkstyle searches 
for modules.
+You can then use your checks in the Checkstyle configuration without their 
package name.
 
 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
@@ -92,80 +97,76 @@ You do not need to specify their package name.
 
 <checkstyle-packages>
   <package name="com.mycompany.checks"/>
-  <package name="com.puppycrawl.tools.checkstyle">
-    <package name="checks">
-      <package name="blocks"/>
-      <package name="coding"/>
-      <package name="design"/>
-      <package name="duplicates"/>
-      <package name="header"/>
-      <package name="imports"/>
-      <package name="indentation"/>
-      <package name="j2ee"/>
-      <package name="javadoc"/>
-      <package name="metrics"/>
-      <package name="modifier"/>
-      <package name="naming"/>
-      <package name="sizes"/>
-      <package name="whitespace"/>
-    </package>
-    <package name="filters"/>
-  </package>
 </checkstyle-packages>
 ```
 
 #[[### `MethodLimitCheck.java`]]#
 
 Here is the example check from the Checkstyle site.
-It checks that your source files do not have more than 30 methods.
+It checks that a class or interface does not have more than 30 methods.
+The `max` property can change the limit.
 
 ```java
 package com.mycompany.checks;
-import com.puppycrawl.tools.checkstyle.api.*;
 
-public class MethodLimitCheck extends Check
-{
+import com.puppycrawl.tools.checkstyle.api.AbstractCheck;
+import com.puppycrawl.tools.checkstyle.api.DetailAST;
+import com.puppycrawl.tools.checkstyle.api.TokenTypes;
+
+public class MethodLimitCheck extends AbstractCheck {
+
     private int max = 30;
 
-    public int[] getDefaultTokens()
-    {
-        return new int[]{TokenTypes.CLASS_DEF, TokenTypes.INTERFACE_DEF};
+    public void setMax(int max) {
+        this.max = max;
     }
 
-    public void visitToken(DetailAST ast)
-    {
+    @Override
+    public int[] getDefaultTokens() {
+        return new int[] {TokenTypes.CLASS_DEF, TokenTypes.INTERFACE_DEF};
+    }
+
+    @Override
+    public int[] getAcceptableTokens() {
+        return getDefaultTokens();
+    }
+
+    @Override
+    public int[] getRequiredTokens() {
+        return new int[0];
+    }
+
+    @Override
+    public void visitToken(DetailAST ast) {
         // find the OBJBLOCK node below the CLASS_DEF/INTERFACE_DEF
         DetailAST objBlock = ast.findFirstToken(TokenTypes.OBJBLOCK);
-        // count the number of direct children of the OBJBLOCK
-        // that are METHOD_DEFS
+        // count the number of direct children of the OBJBLOCK that are 
METHOD_DEFs
         int methodDefs = objBlock.getChildCount(TokenTypes.METHOD_DEF);
-        // report error if limit is reached
+        // report a violation if the limit is exceeded
         if (methodDefs > max) {
-            log(ast.getLineNo(),
-                "too many methods, only " + max + " are allowed");
+            log(ast, "too many methods, only " + max + " are allowed");
         }
-   }
+    }
 }
 ```
 
+<a id="Building_a_JAR_for_your_custom_checks_project"></a>
+
 Build the JAR for Your Custom Checks Project
 --------------------------------------------
 
-To use your custom checks in other projects, package and install them.
-Run this command:
+To use your custom checks in other projects, package and install them:
 
 ```shell
 mvn install
 ```
 
-This command produces a JAR file with these contents.
-It also installs the file into your local repository.
+This command builds a JAR file with these contents and installs it into your 
local repository.
 
 #[[### `mycompany-checkstyle-checks-1.0.jar`]]#
 
 ```text
 mycompany-checkstyle-checks-1.0.jar
-|-- pom.xml
 |-- META-INF
 |   |-- MANIFEST.MF
 |   `-- maven
@@ -173,13 +174,15 @@ mycompany-checkstyle-checks-1.0.jar
 |           `-- mycompany-checkstyle-checks
 |               |-- pom.xml
 |               `-- pom.properties
+|-- checkstyle_packages.xml
 `-- com
     `-- mycompany
         `-- checks
-            |-- packagenames.xml
             `-- MethodLimitCheck.class
 ```
 
+<a id="Using_your_checks_in_another_project"></a>
+
 Use Your Checks in Another Project
 ----------------------------------
 
@@ -187,22 +190,22 @@ You are now ready to use your custom checks in another 
project.
 
 #[[### Create a Checkstyle configuration]]#
 
-Create the file `checkstyle.xml` in the root of the project that wants to use 
your custom checks.
-In this file, tell Checkstyle which checks you want to use.
-
-**Note:** You do not have to specify the fully qualified class name of your 
check here.
-The `packagenames.xml` file makes this possible.
+Create the file `checkstyle.xml` in the root of the project that uses your 
custom checks.
+In this file, tell Checkstyle which checks to run.
+Thanks to `checkstyle_packages.xml`, `MethodLimit` is enough; you do not need 
the fully qualified class name.
 
 ```xml
-<?xml version="1.0" ?>
+<?xml version="1.0"?>
 
 <!DOCTYPE module PUBLIC
-  "-//Checkstyle//DTD Checkstyle Configuration 1.2//EN"
-  "https://checkstyle.org/dtds/configuration_1_2.dtd";>
+  "-//Checkstyle//DTD Checkstyle Configuration 1.3//EN"
+  "https://checkstyle.org/dtds/configuration_1_3.dtd";>
 
 <module name="Checker">
   <module name="TreeWalker">
-    <module name="MethodLimit"/>
+    <module name="MethodLimit">
+      <property name="max" value="20"/>
+    </module>
   </module>
 </module>
 ```
@@ -212,10 +215,9 @@ The `packagenames.xml` file makes this possible.
 Finally, tell the other project to use your custom Checkstyle checks.
 Add this configuration to the `pom.xml` of that project.
 
-**Note:** You must specify a plugin dependency on 
`mycompany-checkstyle-checks` in the `<build>` element of your `pom.xml`.
-This dependency will not work in the `<reporting>` element.
-The `<reporting>` element does not support plugin dependencies.
-Do the rest of the configuration in the normal way in the `<reporting>` 
element.
+**Note:** Declare the plugin dependency on `mycompany-checkstyle-checks` in 
the `<build>` section of your `pom.xml`.
+The `<reporting>` section does not support plugin dependencies, but the report 
uses the ones declared in `<build>`.
+Do the rest of the configuration in the normal way in the `<reporting>` 
section.
 
 ```xml
 <project>
@@ -251,3 +253,10 @@ Do the rest of the configuration in the normal way in the 
`<reporting>` element.
   ...
 </project>
 ```
+
+Run `mvn site` for the report, or `mvn checkstyle:check 
-Dcheckstyle.config.location=checkstyle.xml` to check from the command line.
+With `max` set to `2`, a class with three methods logs:
+
+```text
+[ERROR] src/main/java/com/example/Big.java:[3,1] (extension) MethodLimit: too 
many methods, only 2 are allowed
+```
diff --git a/src/site/markdown/examples/custom-property-expansion.md.vm 
b/src/site/markdown/examples/custom-property-expansion.md.vm
index 4c35d21..21fb99f 100644
--- a/src/site/markdown/examples/custom-property-expansion.md.vm
+++ b/src/site/markdown/examples/custom-property-expansion.md.vm
@@ -23,6 +23,8 @@ specific language governing permissions and limitations
 under the License.
 -->
 
+<a id="Using_Custom_Checkstyle_Property_Expansion_Definitions"></a>
+
 # Custom Checkstyle Property Expansion Definitions
 
 You can define custom [property expansion 
definitions](https://checkstyle.org/config.html#Properties) for the Checker.
@@ -45,7 +47,7 @@ It also lets the Checker users specify their own projectname.
   <module name="TreeWalker">
     <module name="PackageName">
       <property name="format"
-         value="com\.example\.$\{projectname\}(\.[a-z][a-zA-Z0-9]+)*$"/>
+         
value="com\.example\.${esc.dollar}{projectname}(\.[a-z][a-zA-Z0-9]+)*$"/>
     </module>
   </module>
 </module>
@@ -78,7 +80,7 @@ Checkstyle uses it when it encounters the variable in the 
Checker configuration
 ```
 
 You can also provide the property expansion information from a location with 
the `propertiesLocation` parameter as shown below.
-The parameter can point to a URL, a file, or a build classpath resource.
+The parameter can point to a file relative to the project directory, a URL, or 
a resource on the plugin classpath.
 
 ```xml
 <project>
@@ -91,7 +93,7 @@ The parameter can point to a URL, a file, or a build 
classpath resource.
         <version>${project.version}</version>
         <configuration>
           <configLocation>checkstyle.xml</configLocation>
-          
<propertiesLocation>${basedir}/checkstyle.properties</propertiesLocation>
+          <propertiesLocation>checkstyle.properties</propertiesLocation>
         </configuration>
       </plugin>
     </plugins>
diff --git a/src/site/markdown/examples/inline-checker-config.md.vm 
b/src/site/markdown/examples/inline-checker-config.md.vm
index eef312b..3da40ce 100644
--- a/src/site/markdown/examples/inline-checker-config.md.vm
+++ b/src/site/markdown/examples/inline-checker-config.md.vm
@@ -23,15 +23,14 @@ specific language governing permissions and limitations
 under the License.
 -->
 
-# Inline Checkstyle Checker Configuration
+<a id="Using_an_Inline_Checkstyle_Checker_Configuration"></a>
 
-From version 2.12, you can define an inline [Checker 
configuration](https://checkstyle.org/config.html#Checker) directly in the 
`configuration` section of the plugin inside your `pom.xml`.
+# Inline Checkstyle Checker Configuration
 
-This is useful when you want to run the Checkstyle checks with every compile.
-You do not need to create a separate project for your Checkstyle rules.
-You do not need a separate parent POM structure.
+You can define a [Checker 
configuration](https://checkstyle.org/config.html#Checker) directly in the 
`<configuration>` section of the plugin in your `pom.xml`.
+You then need no separate ruleset file, no separate project for your 
Checkstyle rules, and no parent POM structure.
 
-Use the `checkstyleRules` parameter to define a custom Checkstyle checker 
configuration inside your `pom.xml`.
+Use the `checkstyleRules` parameter to define the checker configuration inside 
your `pom.xml`:
 
 ```xml
 <project>
@@ -56,15 +55,15 @@ Use the `checkstyleRules` parameter to define a custom 
Checkstyle checker config
           <checkstyleRules>
             <module name="Checker">
 
-              <!-- Checks for Size Violations.                    -->
-              <!-- See http://checkstyle.sf.net/config_sizes.html -->
+              <!-- Checks for size violations.                    -->
+              <!-- See https://checkstyle.org/checks/sizes/       -->
               <module name="FileLength">
                 <property name="max" value="3500" />
                 <property name="fileExtensions" value="java"/>
               </module>
 
-              <!-- Checks for whitespace                               -->
-              <!-- See http://checkstyle.sf.net/config_whitespace.html -->
+              <!-- Checks for whitespace.                         -->
+              <!-- See https://checkstyle.org/checks/whitespace/  -->
               <module name="FileTabCharacter"/>
 
               <module name="TreeWalker">
@@ -83,77 +82,33 @@ Use the `checkstyleRules` parameter to define a custom 
Checkstyle checker config
 </project>
 ```
 
-# Different Header
-
-The plugin writes the inline configuration to a file.
-It then passes the file to checkstyle.
-The configuration file must contain a specific 
[header](https://checkstyle.org/config.html#Configuration_XML_Structure).
+<a id="Using_a_different_header"></a>
 
-The plugin includes one by default.
-The default header is compatible with the included checkstyle version.
+${esc.h}${esc.h} Different Header
 
-When you use a different checkstyle version than the one that is included, you 
must specify a different header:
+The plugin writes the inline configuration to `target/checkstyle-checker.xml` 
and passes that file to Checkstyle.
+The file starts with a [document type 
declaration](https://checkstyle.org/config.html#Configuration_XML_Structure), 
which the plugin adds for you.
+The default declaration references the Checkstyle configuration DTD 1.3:
 
 ```xml
-<project>
-  ...
-  <build>
-    <plugins>
-      <plugin>
-        <groupId>org.apache.maven.plugins</groupId>
-        <artifactId>maven-checkstyle-plugin</artifactId>
-        <version>${project.version}</version>
-        <executions>
-          <execution>
-            <id>verify-style</id>
-            <phase>process-classes</phase>
-            <goals>
-              <goal>check</goal>
-            </goals>
-          </execution>
-        </executions>
-        <configuration>
-          <logViolationsToConsole>true</logViolationsToConsole>
-          <checkstyleRules>
-            <module name="Checker">
-
-              <!-- Checks for Size Violations.                    -->
-              <!-- See http://checkstyle.sf.net/config_sizes.html -->
-              <module name="FileLength">
-                <property name="max" value="3500" />
-                <property name="fileExtensions" value="java"/>
-              </module>
+<?xml version="1.0"?>
+<!DOCTYPE module PUBLIC "-//Checkstyle//DTD Checkstyle Configuration 1.3//EN"
+        "https://checkstyle.org/dtds/configuration_1_3.dtd";>
+```
 
-              <!-- Checks for whitespace                               -->
-              <!-- See http://checkstyle.sf.net/config_whitespace.html -->
-              <module name="FileTabCharacter"/>
+DTD 1.3 is the current version, and the default works when you [upgrade 
Checkstyle at runtime](./upgrading-checkstyle.html).
+Set the `checkstyleRulesHeader` parameter only if you need a different 
declaration:
 
-              <module name="TreeWalker">
-                <module name="StaticVariableName"/>
-                <module name="TypeName">
-                  <property name="format" value="^_?[A-Z][a-zA-Z0-9]*$"/>
-                </module>
-              </module>
-            </module>
-          </checkstyleRules>
-          <checkstyleRulesHeader>
-<![CDATA[
-<!DOCTYPE module PUBLIC
-  "-//Checkstyle//DTD Checkstyle Configuration 1.3//EN"
-  "https://checkstyle.org/dtds/configuration_1_3.dtd";>
+```xml
+<configuration>
+  <checkstyleRules>
+    ...
+  </checkstyleRules>
+  <checkstyleRulesHeader>
+<![CDATA[<?xml version="1.0"?>
+<!DOCTYPE module PUBLIC "-//Checkstyle//DTD Checkstyle Configuration 1.3//EN"
+        "https://checkstyle.org/dtds/configuration_1_3.dtd";>
 ]]>
-          </checkstyleRulesHeader>
-        </configuration>
-        <dependencies>
-          <dependency>
-            <groupId>com.puppycrawl.tools</groupId>
-            <artifactId>checkstyle</artifactId>
-            <version>8.15</version>
-          </dependency>
-        </dependencies>
-      </plugin>
-    </plugins>
-  </build>
-  ...
-</project>
+  </checkstyleRulesHeader>
+</configuration>
 ```
diff --git a/src/site/markdown/examples/multi-module-config.md.vm 
b/src/site/markdown/examples/multi-module-config.md.vm
index 3407633..f97b08d 100644
--- a/src/site/markdown/examples/multi-module-config.md.vm
+++ b/src/site/markdown/examples/multi-module-config.md.vm
@@ -25,10 +25,8 @@ under the License.
 
 # Multimodule Configuration
 
-From version 2.12 of this Plugin, you can 
[inline](./inline-checker-config.html) the configuration directly in the parent 
POM.
-
-You can configure the Checkstyle Plugin for large multimodule projects.
-It requires some setup.
+To share one Checkstyle configuration across the modules of a large project, 
put it in a JAR and add that JAR as a plugin dependency.
+For a small set of rules, you can instead 
[inline](./inline-checker-config.html) the configuration in the parent POM.
 
 This example uses a sample project called _whizbang_.
 The project has the structure below:
@@ -63,7 +61,7 @@ whizbang
 |   |       `-- resources
 |   |           `-- whizbang
 |   |               |-- checkstyle.xml
-|   |               `-- LICENSE.TXT
+|   |               `-- LICENSE.txt
 |   `-- pom.xml
 |-- core
 |-- gui
@@ -141,14 +139,14 @@ Do the rest of the configuration in the normal way in the 
`<reporting>` element.
 </project>
 ```
 
-Make sure that you do not include the Maven Checkstyle Plugin in your 
submodules.
-A submodule definition overrides the top level parent POM definition.
+Keep the Checkstyle Plugin configuration in the parent POM only.
+If a submodule declares the plugin as well, its settings override the parent's 
for that submodule.
 
 The plugin resolves the values of `configLocation` and `headerLocation` from 
the classpath.
 The _build-tools_ JAR is in the classpath.
 You declared the JAR as a dependency to the plugin.
 
-Then run a build of the site:
+Then build the site:
 
 ```shell
 mvn site
diff --git a/src/site/markdown/examples/suppressions-filter.md.vm 
b/src/site/markdown/examples/suppressions-filter.md.vm
index 0a9c0a0..de3e05b 100644
--- a/src/site/markdown/examples/suppressions-filter.md.vm
+++ b/src/site/markdown/examples/suppressions-filter.md.vm
@@ -23,11 +23,13 @@ specific language governing permissions and limitations
 under the License.
 -->
 
+<a id="Using_a_Suppressions_Filter"></a>
+
 # Suppressions Filter
 
 Checkstyle lets you define a list of files and their line ranges.
 Checkstyle does not report violations in these ranges.
-This list is called a [suppressions 
filter](https://checkstyle.org/config.html#Filters).
+This list is called a [suppressions 
filter](https://checkstyle.org/filters/suppressionfilter.html).
 
 Example: `checkstyle-suppressions.xml`
 
@@ -35,8 +37,8 @@ Example: `checkstyle-suppressions.xml`
 <?xml version="1.0"?>
 
 <!DOCTYPE suppressions PUBLIC
-     "-//Checkstyle//DTD SuppressionFilter Configuration 1.0//EN"
-     "https://checkstyle.org/dtds/suppressions_1_0.dtd";>
+     "-//Checkstyle//DTD SuppressionFilter Configuration 1.2//EN"
+     "https://checkstyle.org/dtds/suppressions_1_2.dtd";>
 
 <suppressions>
   <suppress checks="JavadocStyleCheck"
@@ -62,7 +64,6 @@ Example: `pom.xml` - This configuration specifies the 
suppressions filter for Ch
         <configuration>
           <configLocation>checkstyle.xml</configLocation>
           
<suppressionsLocation>checkstyle-suppressions.xml</suppressionsLocation>
-          
<suppressionsFileExpression>checkstyle.suppressions.file</suppressionsFileExpression>
         </configuration>
       </plugin>
     </plugins>
@@ -70,3 +71,7 @@ Example: `pom.xml` - This configuration specifies the 
suppressions filter for Ch
   ...
 </project>
 ```
+
+The plugin applies the suppressions file itself, so `checkstyle.xml` needs no 
`SuppressionFilter` module.
+The plugin also passes the path of the file to Checkstyle in the 
`checkstyle.suppressions.file` property.
+If your Checkstyle configuration refers to the file under another property 
name, set that name with the `suppressionsFileExpression` parameter.
diff --git a/src/site/markdown/examples/upgrading-checkstyle.md.vm 
b/src/site/markdown/examples/upgrading-checkstyle.md.vm
index 58f99c4..17ac1f8 100644
--- a/src/site/markdown/examples/upgrading-checkstyle.md.vm
+++ b/src/site/markdown/examples/upgrading-checkstyle.md.vm
@@ -23,14 +23,16 @@ specific language governing permissions and limitations
 under the License.
 -->
 
+<a id="Upgrading_Checkstyle_at_Runtime"></a>
+
 # Upgrade Checkstyle at Runtime
 
 The Maven Checkstyle Plugin has a default Checkstyle version.
 For `maven-checkstyle-plugin ${project.version}`, the plugin uses Checkstyle 
${checkstyleVersion} by default.
 
-Checkstyle keeps good compatibility between versions.
-You can override the version used at runtime.
-This lets you use the [latest Checkstyle bug 
fixes](https://checkstyle.org/releasenotes.html):
+You can override the version used at runtime with a plugin dependency.
+This lets you use the [latest Checkstyle checks and bug 
fixes](https://checkstyle.org/release-notes.html).
+Declare it in `<pluginManagement>` so that it applies both to the `check` goal 
and to the reports:
 
 ```xml
 <project>
@@ -56,3 +58,15 @@ This lets you use the [latest Checkstyle bug 
fixes](https://checkstyle.org/relea
   ...
 </project>
 ```
+
+Newer Checkstyle versions need a newer Java version than the plugin itself.
+Run Maven with a JDK that the chosen Checkstyle version supports:
+
+| Checkstyle | Minimum Java |
+|:---|:---|
+| 10.x | 11 |
+| 11.x and 12.x | 17 |
+| 13.x and later | 21 |
+
+The predefined `sun_checks.xml` and `google_checks.xml` rulesets come from the 
Checkstyle JAR.
+When you upgrade Checkstyle, they change with it and can report new violations.
diff --git a/src/site/markdown/faq.md b/src/site/markdown/faq.md
index ac60f6c..dea24b2 100644
--- a/src/site/markdown/faq.md
+++ b/src/site/markdown/faq.md
@@ -25,7 +25,7 @@ under the License.
 
 # Frequently Asked Questions
 
-1. [Where is `config/maven_checks.xml` predefined 
ruleset?](#Where_is_maven_checks.xml_predefined_ruleset)
+1. [Where is the `config/maven_checks.xml` predefined 
ruleset?](#Where_is_maven_checks.xml_predefined_ruleset)
 1. [How are the Checkstyle properties 
set?](#How_are_the_Checkstyle_properties_set)
 1. [How do I set a custom ruleset?](#How_do_I_set_a_custom_ruleset)
 1. [How do I include the test directory in 
Checkstyle?](#How_do_I_include_the_test_directory_in_Checkstyle)
@@ -35,39 +35,38 @@ under the License.
 
 ### Where is the `config/maven_checks.xml` predefined ruleset?
 
-From maven-checkstyle-plugin version 2.14, `config/maven_checks.xml`
-is no longer part of the plugin.
-The file moved to [Apache Maven Shared 
Resources](/shared/maven-shared-resources/).
+Version 2.14 removed `config/maven_checks.xml` from the plugin.
+The ruleset is now in [Apache Maven Shared 
Resources](/shared/maven-shared-resources/).
+The plugin ships `sun_checks.xml` and `google_checks.xml`; the [Predefined 
Rulesets](./config/index.html) page lists the rulesets of each plugin version.
 
 <a id="How_are_the_Checkstyle_properties_set"></a>
 
 ### How are the Checkstyle properties set?
 
-You can set the Checkstyle properties with the `propertiesLocation` parameter 
in the
-plugin configuration of your POM.
-The plugin resolves the properties file from the value of the parameter.
+Set them with the `propertyExpansion` parameter, or put them in a properties 
file and point the `propertiesLocation` parameter to it.
+See [Custom Checkstyle Property Expansion 
Definitions](./examples/custom-property-expansion.html).
 
 <a id="How_do_I_set_a_custom_ruleset"></a>
 
 ### How do I set a custom ruleset?
 
-You can set a custom ruleset with the `configLocation` plugin parameter.
-If you do not specify a value, the plugin uses the `sun_checks.xml` ruleset.
-This ruleset is bundled with the plugin.
+Set the `configLocation` parameter to a file, a URL, or a resource on the 
plugin classpath.
+If you do not set it, the plugin uses the `sun_checks.xml` ruleset that ships 
with Checkstyle.
+See [Custom Checkstyle Checker 
Configuration](./examples/custom-checker-config.html).
 
 <a id="How_do_I_include_the_test_directory_in_Checkstyle"></a>
 
 ### How do I include the test directory in Checkstyle?
 
-You can include the test directory in the Checkstyle report.
-The `includeTestSourceDirectory` plugin parameter must be `true`.
+Set the `includeTestSourceDirectory` parameter to `true`.
+It is `false` by default, for both the `check` goal and the reports.
 
+<a 
id="What_is_the_difference_between_checkstyle:checkstyle_and_checkstyle:check"></a>
 <a 
id="What_is_the_difference_between_checkstyle.3Acheckstyle_and_checkstyle.3Acheck"></a>
 
 ### What is the difference between checkstyle:checkstyle and checkstyle:check?
 
-The checkstyle:checkstyle goal is a **reporting** goal.
-It adds a report of Checkstyle violations to the output of the 
maven-site-plugin.
-The checkstyle:check goal is an ordinary goal.
-It reports violations to the console.
-It fails the build when there are violations.
+`checkstyle:checkstyle` is a reporting goal.
+It writes an HTML report of Checkstyle violations, as part of the site or on 
its own.
+It does not fail the build unless you set `failsOnError` to `true`.
+`checkstyle:check` logs violations to the console and fails the build when 
there are violations.
diff --git a/src/site/markdown/history.md.vm b/src/site/markdown/history.md.vm
index b351856..26aa571 100644
--- a/src/site/markdown/history.md.vm
+++ b/src/site/markdown/history.md.vm
@@ -22,43 +22,49 @@
 Maven Checkstyle Plugin Releases History
 ----------------------------------------
 
-#macro ( release $version )
-<a 
href="https://checkstyle.org/releasenotes.html#Release_$version";>$version</a>
+#macro ( release $version $page )
+<a href="https://checkstyle.org/${page}.html#Release_$version";>$version</a>
 #end
-#macro ( releaseOld $version )
-<a 
href="https://checkstyle.org/releasenotes_old.html#Release_$version";>$version</a>
+#if( $checkstyleVersion.startsWith( "9." ) || $checkstyleVersion.startsWith( 
"10." ) )
+#set( $currentNotes = "release-notes-old-8-35-10-26" )
+#else
+#set( $currentNotes = "release-notes" )
 #end
 
 <table>
 <tr><th>release date</th><th>maven-checkstyle-plugin version</th><th>minimum 
Java version</th>
     <th>default <a href="https://checkstyle.org/";>Checkstyle</a> 
version</th></tr>
-<tr><td>$dateFormat.format( $currentDate 
)</td><td>${project.version}</td><td>${javaVersion}</td><td>#release( 
${checkstyleVersion} )</td></tr>
-<tr><td>2023-05-19</td><td>3.3.0 </td><td rowspan="7"> 8</td><td 
rowspan="4">#release( "9.3" )</td></tr>
+<tr><td>$dateFormat.format( $currentDate 
)</td><td>${project.version}</td><td>${javaVersion}</td><td>#release( 
${checkstyleVersion} $currentNotes )</td></tr>
+<tr><td>2024-10-22</td><td>3.6.0 </td><td rowspan="11"> 8</td><td 
rowspan="8">#release( "9.3" "release-notes-old-8-35-10-26" )</td></tr>
+<tr><td>2024-08-19</td><td>3.5.0 </td></tr>
+<tr><td>2024-06-02</td><td>3.4.0 </td></tr>
+<tr><td>2023-10-21</td><td>3.3.1 </td></tr>
+<tr><td>2023-05-19</td><td>3.3.0 </td></tr>
 <tr><td>2023-04-18</td><td>3.2.2 </td></tr>
 <tr><td>2023-01-06</td><td>3.2.1 </td></tr>
 <tr><td>2022-08-20</td><td>3.2.0 </td></tr>
-<tr><td>2021-01-23</td><td>3.1.2 </td>                       <td 
rowspan="2">#release( "8.29" )</td></tr>
+<tr><td>2021-01-23</td><td>3.1.2 </td>                       <td 
rowspan="2">#release( "8.29" "release-notes-old-8-0-8-34" )</td></tr>
 <tr><td>2020-02-08</td><td>3.1.1 </td></tr>
-<tr><td>2019-05-20</td><td>3.1.0 </td>                       <td>#release( 
"8.19" )</td></tr>
-<tr><td>2018-01-04</td><td>3.0.0 </td><td rowspan="3"> 7</td><td>#release( 
"8.18" )</td></tr>
-<tr><td>2015-10-15</td><td>2.17  </td>                       <td>#release( 
"6.11.2" )</td></tr>
-<tr><td>2015-07-13</td><td>2.16  </td>                       <td>#release( 
"6.2" )</td></tr>
-<tr><td>2015-03-20</td><td>2.15  </td><td>             6</td><td>#release( 
"6.1.1" )</td></tr>
-<tr><td>2015-02-05</td><td>2.14  </td><td rowspan="13">5</td><td>#release( 
"5.8" )  </td></tr>
-<tr><td>2014-09-18</td><td>2.13  </td>                       <td 
rowspan="3">#releaseOld( "5.7" )  </td></tr>
+<tr><td>2019-05-20</td><td>3.1.0 </td>                       <td>#release( 
"8.19" "release-notes-old-8-0-8-34" )</td></tr>
+<tr><td>2018-01-04</td><td>3.0.0 </td><td rowspan="3"> 7</td><td>#release( 
"8.18" "release-notes-old-8-0-8-34" )</td></tr>
+<tr><td>2015-10-15</td><td>2.17  </td>                       <td>#release( 
"6.11.2" "release-notes-old-6-0-7-8" )</td></tr>
+<tr><td>2015-07-13</td><td>2.16  </td>                       <td>#release( 
"6.2" "release-notes-old-6-0-7-8" )</td></tr>
+<tr><td>2015-03-20</td><td>2.15  </td><td>             6</td><td>#release( 
"6.1.1" "release-notes-old-6-0-7-8" )</td></tr>
+<tr><td>2015-02-05</td><td>2.14  </td><td rowspan="13">5</td><td>#release( 
"5.8" "release-notes-old-1-0-5-9" )  </td></tr>
+<tr><td>2014-09-18</td><td>2.13  </td>                       <td 
rowspan="3">#release( "5.7" "release-notes-old-1-0-5-9" )  </td></tr>
 <tr><td>2014-04-19</td><td>2.12.1</td></tr>
 <tr><td>2014-03-12</td><td>2.12  </td></tr>
-<tr><td>2013-11-15</td><td>2.11  </td>                       <td 
rowspan="2">#releaseOld( "5.6" )  </td></tr>
+<tr><td>2013-11-15</td><td>2.11  </td>                       <td 
rowspan="2">#release( "5.6" "release-notes-old-1-0-5-9" )  </td></tr>
 <tr><td>2013-02-22</td><td>2.10  </td></tr>
-<tr><td>2012-02-25</td><td>2.9.1 </td>                       <td 
rowspan="2">#releaseOld( "5.5" )  </td></tr>
+<tr><td>2012-02-25</td><td>2.9.1 </td>                       <td 
rowspan="2">#release( "5.5" "release-notes-old-1-0-5-9" )  </td></tr>
 <tr><td>2012-02-12</td><td>2.9   </td></tr>
-<tr><td>2011-11-01</td><td>2.8   </td>                       <td 
rowspan="2">#releaseOld( "5.4" )  </td></tr>
+<tr><td>2011-11-01</td><td>2.8   </td>                       <td 
rowspan="2">#release( "5.4" "release-notes-old-1-0-5-9" )  </td></tr>
 <tr><td>2011-08-11</td><td>2.7   </td></tr>
-<tr><td>2010-09-25</td><td>2.6   </td>                       <td 
rowspan="3">#releaseOld( "5.0" )  </td></tr>
+<tr><td>2010-09-25</td><td>2.6   </td>                       <td 
rowspan="3">#release( "5.0" "release-notes-old-1-0-5-9" )  </td></tr>
 <tr><td>2010-02-12</td><td>2.5   </td></tr>
 <tr><td>2009-11-18</td><td>2.4   </td></tr>
-<tr><td>2009-07-14</td><td>2.3   </td><td rowspan="4">1.4</td><td 
rowspan="2">#releaseOld( "4.4" )  </td></tr>
+<tr><td>2009-07-14</td><td>2.3   </td><td rowspan="4">1.4</td><td 
rowspan="2">#release( "4.4" "release-notes-old-1-0-5-9" )  </td></tr>
 <tr><td>2008-06-04</td><td>2.2   </td></tr>
-<tr><td>2006-05-14</td><td>2.1   </td>                        <td 
rowspan="2">#releaseOld( "4.1" )  </td></tr>
+<tr><td>2006-05-14</td><td>2.1   </td>                        <td 
rowspan="2">#release( "4.1" "release-notes-old-1-0-5-9" )  </td></tr>
 <tr><td>2006-01-28</td><td>2.0   </td></tr>
 </table>
diff --git a/src/site/markdown/index.md.vm b/src/site/markdown/index.md.vm
index b93c967..5ae67a2 100644
--- a/src/site/markdown/index.md.vm
+++ b/src/site/markdown/index.md.vm
@@ -26,56 +26,73 @@ under the License.
 
 # ${project.name}
 
-The Checkstyle Plugin generates a report on the code style used by the 
developers.
-For more information about Checkstyle, see 
[https://checkstyle.org/](https://checkstyle.org/).
+The Checkstyle Plugin runs [Checkstyle](https://checkstyle.org/) on your 
project's sources and resources.
+It can fail the build on violations, or add a Checkstyle report to the project 
site.
 
 This version of the plugin uses Checkstyle ${checkstyleVersion} by default.
-It requires Java ${javaVersion}.
-You can [upgrade the version used at 
runtime](./examples/upgrading-checkstyle.html).
+It requires Maven 3.9.0 or later and Java ${javaVersion} or later.
+You can [use a newer Checkstyle version](./examples/upgrading-checkstyle.html) 
at runtime.
 
-The plugin can be configured in the project's POM.
-This version of the plugin provides two predefined rulesets: 
[`sun_checks.xml`](https://checkstyle.org/sun_style.html) and 
[`google_checks.xml`](https://checkstyle.org/google_style.html).
-You can also use a custom ruleset in the plugin configuration.
+Quick Start
+-----------
+
+Check the code against the default `sun_checks.xml` ruleset and fail on 
violations:
+
+```shell
+mvn checkstyle:check
+```
+
+Check against the Google ruleset instead.
+The `google_checks.xml` ruleset reports at `warning` severity, so also lower 
the severity that counts as a violation:
+
+```shell
+mvn checkstyle:check -Dcheckstyle.config.location=google_checks.xml 
-Dcheckstyle.violationSeverity=warning
+```
+
+Write an HTML report to `target/reports/checkstyle.html` without failing the 
build:
+
+```shell
+mvn checkstyle:checkstyle
+```
+
+To run the check in every build, bind the `check` goal in your POM, as shown 
on the [usage page](./usage.html).
+
+The plugin ships two predefined rulesets from Checkstyle: 
[`sun_checks.xml`](https://checkstyle.org/sun_style.html) (the default) and 
[`google_checks.xml`](https://checkstyle.org/google_style.html).
+You can also [use your own ruleset](./examples/custom-checker-config.html) or 
[write it inline in the POM](./examples/inline-checker-config.html).
+Rulesets from older plugin versions are listed on the [Predefined 
Rulesets](./config/index.html) page.
 
 Goals Overview
 --------------
 
 The Checkstyle Plugin has three goals:
 
+- [checkstyle:check](./check-mojo.html) performs Checkstyle analysis and logs 
violations to the console.
+  It fails the build on violations by default, and binds to the `verify` phase.
+  It can also re-use the result of an earlier `checkstyle:checkstyle` run.
 - [checkstyle:checkstyle](./checkstyle-mojo.html) is a reporting goal that 
performs Checkstyle analysis and generates a report on violations.
-- [checkstyle:checkstyle-aggregate](./checkstyle-aggregate-mojo.html) is a 
reporting goal that performs Checkstyle analysis and generates an aggregate 
HTML report on violations in a multi-module reactor build.
-- [checkstyle:check](./check-mojo.html) is a goal that performs Checkstyle 
analysis and outputs violations or a count of violations to the console.
-  It can also fail the build.
-  You can configure it to re-use an earlier analysis.
-
-Major Version Upgrade to version 3.0.0
---------------------------------------
+- [checkstyle:checkstyle-aggregate](./checkstyle-aggregate-mojo.html) is a 
reporting goal that generates one report for all modules of a multi-module 
build.
+  Run it from the root project.
 
-These two parameters were removed from the plugin configuration:
-
-- `sourceDirectory`: use `sourceDirectories` instead.
-- `testSourceDirectory`: use `testSourceDirectories` instead.
+[checkstyle:help](./help-mojo.html) lists the goals and their parameters.
 
 Usage
 -----
 
 General instructions on how to use the Checkstyle Plugin are on the [usage 
page](./usage.html).
-The examples below describe more specific use cases.
-
-If you still have questions about the plugin's usage, look at the 
[FAQ](./faq.html).
-You can also contact the [user mailing list](./mailing-lists.html).
-The posts to the mailing list are archived.
-An older thread can contain the answer to your question.
-You can also search the [mail archive](./mailing-lists.html).
-
-If you think that the plugin lacks a feature or has a defect, report it in the 
[issue tracker](https://issues.apache.org/jira/projects/MCHECKSTYLE/).
-When you create a new issue, include a comprehensive description of your 
concern.
-For bug fixes, the developers must be able to reproduce your problem.
-Attach entire debug logs, POMs, or little demo projects to the issue.
-Patches are welcome.
-
-Contributors can check out the project from the [source 
repository](./scm.html).
-They can also find supplementary information in the [guide to helping with 
Maven](https://maven.apache.org/guides/development/guide-helping.html).
+The [examples](#Examples) below describe more specific use cases.
+If you still have questions, look at the [FAQ](./faq.html) or ask on the [user 
mailing list](./mailing-lists.html).
+
+Report a defect or request a feature in the [issue 
tracker](./issue-management.html).
+For a bug, include the steps or a small project that reproduces it.
+The source code is in the [source repository](./scm.html).
+
+<a id="Major_Version_Upgrade_to_version_3.0.0"></a>
+
+Upgrading From 2.x
+------------------
+
+Version 3.0.0 removed the `sourceDirectory` and `testSourceDirectory` 
parameters.
+Use `sourceDirectories` and `testSourceDirectories` instead.
 
 Examples
 --------
diff --git a/src/site/markdown/usage.md.vm b/src/site/markdown/usage.md.vm
index 7af9f9c..4607781 100644
--- a/src/site/markdown/usage.md.vm
+++ b/src/site/markdown/usage.md.vm
@@ -31,90 +31,113 @@ The examples below describe the basic usage of the 
Checkstyle Plugin.
 Generate Checkstyle Report As Part of the Project Reports
 ---------------------------------------------------------
 
-Generate the Checkstyle report as part of the Project Reports.
-Add the Checkstyle Plugin to the `<reporting>` section of your `pom.xml`.
+Add the Checkstyle Plugin to the `<reporting>` section of your `pom.xml`:
 
 ```xml
 <project>
   ...
-   <reporting>
-      <plugins>
-        <plugin>
-          <groupId>org.apache.maven.plugins</groupId>
-          <artifactId>maven-checkstyle-plugin</artifactId>
-          <version>${project.version}</version>
-          <reportSets>
-            <reportSet>
-              <reports>
-                <report>checkstyle</report>
-              </reports>
-            </reportSet>
-          </reportSets>
-        </plugin>
-      </plugins>
-    </reporting>
+  <reporting>
+    <plugins>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-checkstyle-plugin</artifactId>
+        <version>${project.version}</version>
+      </plugin>
+    </plugins>
+  </reporting>
   ...
 </project>
 ```
 
-Run the site phase to generate the report.
+Run the `site` phase to generate the report in `target/site/checkstyle.html`:
 
 ```shell
 mvn site
 ```
 
+In a multi-module build, you can add one report for all modules with the 
`checkstyle-aggregate` report.
+List the reports you want in a `<reportSet>`:
+
+```xml
+<project>
+  ...
+  <reporting>
+    <plugins>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-checkstyle-plugin</artifactId>
+        <version>${project.version}</version>
+        <reportSets>
+          <reportSet>
+            <reports>
+              <report>checkstyle</report>
+              <report>checkstyle-aggregate</report>
+            </reports>
+          </reportSet>
+        </reportSets>
+      </plugin>
+    </plugins>
+  </reporting>
+  ...
+</project>
+```
+
 Generate Checkstyle Report As Standalone
 ----------------------------------------
 
-You can also generate the Checkstyle report with the `checkstyle:checkstyle` 
goal from the command line.
-You do not need to specify the Checkstyle Plugin in your `pom.xml` unless you 
need a specific configuration.
+You can also generate the Checkstyle report from the command line.
+You do not need to declare the plugin in your `pom.xml` unless you need a 
specific configuration.
 
 ```shell
 mvn checkstyle:checkstyle
 ```
 
-Check for Violations as Part of the Build
------------------------------------------
+The report is written to `target/reports/checkstyle.html`.
+For a multi-module build, run `mvn checkstyle:checkstyle-aggregate` from the 
root project; it writes `target/reports/checkstyle-aggregate.html`.
 
-If you want the console report or a build failure, add an execution of 
`checkstyle::check` to the `<build>` element.
-Configure any options that you need.
+<a id="Checking_for_Violations_as_Part_of_the_Build"></a>
 
-Options that you set in the `<reporting>` element do not affect executions in 
the `<build>` element.
+Check for Violations as Part of the Build
+-----------------------------------------
 
-The phase that `checkstyle::check` is bound to is important.
-If you bind it to the validate phase, it checks the code before compilation.
-It is guaranteed to run.
-If the code is invalid, the errors that checkstyle reports can differ from the 
errors from the javac compiler.
+To log violations to the console and fail the build, add an execution of the 
`check` goal to the `<build>` section.
+Options that you set in the `<reporting>` section do not affect executions in 
the `<build>` section.
 
-Another common option binds the goal to the verify phase.
-The verify phase runs much later than the validate phase.
-A later phase lets the javac compiler flag invalid code before checkstyle runs.
+```xml
+<project>
+  ...
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-checkstyle-plugin</artifactId>
+        <version>${project.version}</version>
+        <configuration>
+          <configLocation>checkstyle.xml</configLocation>
+        </configuration>
+        <executions>
+          <execution>
+            <id>validate</id>
+            <phase>validate</phase>
+            <goals>
+              <goal>check</goal>
+            </goals>
+          </execution>
+        </executions>
+      </plugin>
+    </plugins>
+  </build>
+  ...
+</project>
+```
 
-If developers run `mvn test` before they push changes, checkstyle does not run.
-The verify phase occurs after the test phase.
+The phase that you bind `check` to matters:
 
-For example:
+- Bound to `validate`, as above, it runs before compilation, so it also runs 
on `mvn compile` and `mvn test`.
+  For code that does not compile, Checkstyle can report different errors than 
the `javac` compiler.
+- Without a `<phase>`, it binds to `verify`.
+  The compiler then flags invalid code first, but `mvn test` does not run the 
check.
 
-```xml
- <plugin>
-   <groupId>org.apache.maven.plugins</groupId>
-   <artifactId>maven-checkstyle-plugin</artifactId>
-   <version>${project.version}</version>
-   <configuration>
-     <configLocation>checkstyle.xml</configLocation>
-     <inputEncoding>UTF-8</inputEncoding>
-     <consoleOutput>true</consoleOutput>
-     <failsOnError>true</failsOnError>
-     <linkXRef>false</linkXRef>
-   </configuration>
-   <executions>
-     <execution>
-       <id>validate</id>
-       <phase>validate</phase>
-       <goals>
-         <goal>check</goal>
-       </goals>
-     </execution>
-   </executions>
- </plugin>
-```
+By default, only violations of severity `error` are logged and fail the build.
+Set `violationSeverity` to `warning` to include warnings, or `failOnViolation` 
to `false` to log violations without failing.
+To skip the check for one build, pass `-Dcheckstyle.skip`.
diff --git a/src/site/site.xml b/src/site/site.xml
index e66a943..85c510f 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -27,7 +27,7 @@ under the License.
       <item name="Usage" href="usage.html"/>
       <item name="FAQ" href="faq.html"/>
       <!-- According to https://issues.apache.org/jira/browse/MNGSITE-152 -->
-      <item name="License" href="http://www.apache.org/licenses/"/>
+      <item name="License" href="https://www.apache.org/licenses/"/>
       <item name="Download" href="download.html"/>
       <item name="Releases History" href="history.html"/>
     </menu>

Reply via email to