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-site-plugin.git


The following commit(s) were added to refs/heads/master by this push:
     new a1ebdfb4 Refresh the site documentation for 3.23.0
a1ebdfb4 is described below

commit a1ebdfb422ac9cc327e42123a4965948ef368371
Author: Sylwester Lachiewicz <[email protected]>
AuthorDate: Wed Nov 18 01:32:34 2026 +0000

    Refresh the site documentation for 3.23.0
---
 .../markdown/examples/adding-deploy-protocol.md.vm |  33 +++---
 src/site/markdown/examples/configuring-reports.md  |  56 +++-------
 src/site/markdown/examples/moduleexcludes.md.vm    |  17 +--
 src/site/markdown/examples/siterun.md.vm           |  45 +++++++-
 src/site/markdown/faq.md                           | 121 ++++++---------------
 src/site/markdown/history.md                       |   2 +-
 src/site/markdown/migrate.md                       |  55 +++-------
 src/site/markdown/usage.md                         |  14 ++-
 8 files changed, 145 insertions(+), 198 deletions(-)

diff --git a/src/site/markdown/examples/adding-deploy-protocol.md.vm 
b/src/site/markdown/examples/adding-deploy-protocol.md.vm
index cf8eb568..c2b6a1f6 100644
--- a/src/site/markdown/examples/adding-deploy-protocol.md.vm
+++ b/src/site/markdown/examples/adding-deploy-protocol.md.vm
@@ -26,21 +26,28 @@ under the License.
 
 # Adding a Protocol to Deploy the Site
 
-Out of the box, Maven and Site Plugin only supports `file:`, `http(s):` and 
`dav+http(s):` (for WebDAV) as transport protocols.
+[`site:deploy`](../deploy-mojo.html) and 
[`site:stage-deploy`](../stage-deploy-mojo.html) copy the site with a 
[Wagon](/wagon/) provider chosen by the protocol of the site URL in 
`<distributionManagement>`. Out of the box, only `file:` URLs work: the plugin 
brings the file provider, and the HTTP provider that ships with Maven cannot 
copy a directory.
 
-If you try to deploy a site with an unsupported protocol, you&apos;ll get an 
error:
+A URL with any other protocol fails. For example, with an `scp:` URL:
 
 ```
-[ERROR] 
-Unsupported protocol: '...' for site deployment to 
distributionManagement.site.url=...
-Currently supported protocols are: ...
-    Protocols may be added through wagon providers.
-    For more information, see 
http://maven.apache.org/plugins/maven-site-plugin/examples/adding-deploy-protocol.html
+[ERROR] Failed to execute goal 
org.apache.maven.plugins:maven-site-plugin:${project.version}:deploy 
(default-cli) on project scratch-parent: Cannot find wagon which supports the 
requested protocol: scp -> [Help 1]
 ```
 
-As explained in the error message, to deploy a site with a non-built-in 
protocol, you need to add the corresponding [wagon provider](/wagon/).
+and with an `http:` URL:
 
-You can add it either as a [global 
extension](/guides/mini/guide-using-extensions.html), or declare it as a 
dependency of the site plugin:
+```
+[ERROR] Failed to execute goal 
org.apache.maven.plugins:maven-site-plugin:${project.version}:deploy 
(default-cli) on project scratch-parent: Wagon protocol 'http' doesn't support 
directory copying -> [Help 1]
+```
+
+To deploy with another protocol, add the [Wagon provider](/wagon/) for it:
+
+| Site URL | Wagon provider |
+|----------|----------------|
+| `scp://`, `sftp://` | 
[`org.apache.maven.wagon:wagon-ssh`](/wagon/wagon-providers/wagon-ssh/) |
+| `dav:http://`, `dav:https://` (WebDAV) | 
[`org.apache.maven.wagon:wagon-webdav-jackrabbit`](/wagon/wagon-providers/wagon-webdav-jackrabbit/)
 |
+
+You can add it either as a [build 
extension](/guides/mini/guide-using-extensions.html), or declare it as a 
dependency of the Site Plugin:
 
 ```xml
 <project>
@@ -53,7 +60,7 @@ You can add it either as a [global 
extension](/guides/mini/guide-using-extension
           <artifactId>maven-site-plugin</artifactId>
           <version>${project.version}</version>
           <dependencies>
-            <dependency><!-- add support for sftp/scp -->
+            <dependency><!-- add support for scp and sftp -->
               <groupId>org.apache.maven.wagon</groupId>
               <artifactId>wagon-ssh</artifactId>
               <version>${wagonVersion}</version>
@@ -67,6 +74,6 @@ You can add it either as a [global 
extension](/guides/mini/guide-using-extension
 </project>
 ```
 
-Although deployment to SCM (Source Control Management) systems (e.g. SVN, Git, 
Mercury) is supported also by [Wagon SCM 
provider](/wagon/wagon-providers/wagon-scm/) 
-that wagon provider is currently committing each file separately which is not 
desirable in the context of site deployment.
-Therefore, it is recommended to use the [Maven SCM Publish 
Plugin](https://maven.apache.org/plugins/maven-scm-publish-plugin/) for SCM 
deployment instead which pushes all files in a single commit.
+Credentials for the server go into a `<server>` element of your `settings.xml` 
whose `<id>` matches the `<id>` of the site in `<distributionManagement>`; see 
the [Guide to Deployment and Security 
Settings](/guides/mini/guide-deployment-security-settings.html).
+
+To publish the site to a source control system, such as GitHub Pages or the 
Apache svnpubsub/gitpubsub service, use the [Maven SCM Publish 
Plugin](/plugins/maven-scm-publish-plugin/) instead of a Wagon provider: it 
commits all files in one commit, where the [Wagon SCM 
provider](/wagon/wagon-providers/wagon-scm/) commits each file separately. See 
[Deploying the 
Site](https://maven.apache.org/guides/mini/guide-site.html${esc.hash}GitHub_Pages.2C_Apache_svnpubsub.2Fgitpubsub_Deployment)
 in  [...]
diff --git a/src/site/markdown/examples/configuring-reports.md 
b/src/site/markdown/examples/configuring-reports.md
index 29fbbe43..4b9a0373 100644
--- a/src/site/markdown/examples/configuring-reports.md
+++ b/src/site/markdown/examples/configuring-reports.md
@@ -27,49 +27,15 @@ under the License.
 
 # Configuring Reports
 
-Maven has several reports that you can add to your web site to display the 
current state of the project. These reports take the form of plugin goals, just 
like those used to build the project.
+Reports are plugin goals listed in the `<reporting>` section of the POM; the 
Site Plugin runs them and adds their output to the site. How to add them, which 
standard reports the [Maven Project Info Reports 
Plugin](/plugins/maven-project-info-reports-plugin/) provides, and how `<menu 
ref="reports"/>` shows them in the site menu is described in [Configuring 
Reports](https://maven.apache.org/guides/mini/guide-site.html#Configuring_Reports)
 in the site guide. To find more report plugins, loo [...]
 
-[Maven Project Info Reports 
Plugin](/plugins/maven-project-info-reports-plugin/) provides many standard 
reports by extracting information from the POM, for example:
-
-- Continous Integration
-- Dependencies
-- Issue Tracking
-- License
-- Mailing Lists
-- Project Team
-- Source Repository
-
-To find out more please see to the [Project Info Reports 
Plugin](/plugins/maven-project-info-reports-plugin/).
-
-To add these reports to your site, you must add the plugin to the 
`<reporting>` element in the POM. The following example shows how to configure 
the standard Project Info Reports that display information from the POM in a 
friendly format:
-
-```xml
-<project>
-  ...
-  <reporting>
-    <plugins>
-      <plugin>
-        <groupId>org.apache.maven.plugins</groupId>
-        <artifactId>maven-project-info-reports-plugin</artifactId>
-        <version>2.6</version>
-      </plugin>
-    </plugins>
-  </reporting>
-  ...
-</project>
-```
-
-If you have included the appropriate `<menu ref="reports"/>` tag in your [site 
descriptor](https://maven.apache.org/guides/mini/guide-site-descriptor.html), 
then when you regenerate the site those items will appear in a menu called 
&quot;Project Reports&quot;.
-
-**Note:** Many report plugins provide a parameter called `outputDirectory` or 
similar to specify the destination for their report outputs. This parameter is 
only relevant if the report plugin is run standalone, i.e. by invocation 
directly from the command line. In contrast, when reports are generated as part 
of the site, the configuration of the Maven Site Plugin will determine the 
effective output directory to ensure that all reports end up in a common 
location.
-
-Check out reporting plugins (&quot;R&quot; value in the &quot;Type&quot; 
column) in the [plugins page](/plugins/), for a list of available reporting 
plugins from Apache Maven Team.
+This page covers how to choose which reports of a plugin run.
 
 # Selecting Reports from a Plugin: Configuring Report Sets
 
-By default, when you add a plugin in reporting section, _every_ reporting goal 
available in the plugin is rendered once.
+By default, when you add a plugin to the reporting section, _every_ report 
goal of the plugin is rendered once.
 
-If you want to choose only some reports from a plugin, or if you want to run a 
report multiple times with a different configuration, you need to configure 
report sets:
+If you want to choose only some reports from a plugin, or if you want to run a 
report several times with a different configuration, you need to configure 
report sets:
 
 ```xml
 <project>
@@ -79,11 +45,12 @@ If you want to choose only some reports from a plugin, or 
if you want to run a r
       <plugin>
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-project-info-reports-plugin</artifactId>
-        <version>2.6</version>
+        <version>3.9.0</version>
         <reportSets>
           <reportSet>
             <reports><!-- select reports -->
               <report>index</report>
+              <report>summary</report>
             </reports>
           </reportSet>
         </reportSets>
@@ -91,7 +58,7 @@ If you want to choose only some reports from a plugin, or if 
you want to run a r
       <plugin>
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-javadoc-plugin</artifactId>
-        <version>2.9</version>
+        <version>3.12.0</version>
         <reportSets>
           <reportSet><!-- by default, id = "default" -->
             <reports><!-- select non-aggregate reports -->
@@ -114,11 +81,16 @@ If you want to choose only some reports from a plugin, or 
if you want to run a r
 </project>
 ```
 
-_Notice_: don&apos;t forget to define reportSets for plugins which provide 
aggregator reports, like maven-javadoc-plugin, maven-jxr-plugin or 
maven-checkstyle-plugin or you&apos;ll have these aggregate reports run by 
default in addition to non-aggregate reports.
+With the first plugin above, the build log lists the selected reports:
+
+```
+[INFO] Configured 2 reports for maven-project-info-reports-plugin:3.9.0: 
index, summary
+```
+
+Define report sets for plugins that provide aggregate reports, such as the 
Maven Javadoc, JXR or Checkstyle plugins; otherwise the aggregate reports run 
in the root of the reactor in addition to the non-aggregate ones.
 
 ## How Report Sets Are Selected
 
 All the report sets of a plugin are collected, a report set with 
`<inherited>false</inherited>` stays in the POM that declares it, and each 
report then decides whether it can run in the module, so a `pom` module often 
shows only the aggregate report. See [How Report Sets Are 
Selected](/guides/mini/guide-site.html#How_Report_Sets_Are_Selected) in the 
site guide for the rule and an example.
 
 See the [reportSet documentation in POM 
reference](/ref/current/maven-model/maven.html#class_reportSet) for complete 
description of available configurations.
-
diff --git a/src/site/markdown/examples/moduleexcludes.md.vm 
b/src/site/markdown/examples/moduleexcludes.md.vm
index fabae56b..5df232f1 100644
--- a/src/site/markdown/examples/moduleexcludes.md.vm
+++ b/src/site/markdown/examples/moduleexcludes.md.vm
@@ -26,23 +26,22 @@ under the License.
 
 # Excluding Document Formats
 
-To exclude specific document formats from the generated site, you can use the 
`moduleExcludes` parameter.
+To leave some source documents out of the generated site, use the 
[`moduleExcludes`](../site-mojo.html${esc.hash}moduleExcludes) parameter. Each 
entry is named after a source format, such as `markdown`, `apt`, `xdoc` or 
`fml`, and holds a comma-separated list of file names or patterns, relative to 
the directory of that format.
 
-For example, you have the following site content in your POM
+For example, your project has the following site content:
 
 ```
 Module1
 |-- src
-|   |-- main
 |   `-- site
-|       |-- apt
-|       |   `-- sample-apt.apt
+|       |-- markdown
+|       |   `-- index.md
 |       `-- fml
 |           `-- sample-fml.fml
 `-- pom.xml
 ```
 
-and you want to exclude all the documents in the fml format from the generated 
site, you need to set the following in your POM and then execute &quot;`mvn 
site`&quot;.
+To exclude all the documents in the FML format from the generated site, set 
the following in your POM and run `mvn site`:
 
 ```xml
 <project>
@@ -65,7 +64,11 @@ and you want to exclude all the documents in the fml format 
from the generated s
 </project>
 ```
 
-You will see that no `sample-fml.html` will be present in the generated site.
+The generated site then contains no `sample-fml.html`, and the build log 
counts only the remaining documents:
+
+```
+[INFO] Rendering 1 Doxia document: 1 markdown
+```
 
 See the documentation of the 
[moduleExcludes](../site-mojo.html#moduleExcludes) Mojo parameter for more 
details.
 
diff --git a/src/site/markdown/examples/siterun.md.vm 
b/src/site/markdown/examples/siterun.md.vm
index 07704ab9..5e7e984c 100644
--- a/src/site/markdown/examples/siterun.md.vm
+++ b/src/site/markdown/examples/siterun.md.vm
@@ -26,9 +26,43 @@ under the License.
 
 # Configuring Site Run
 
-For the [`site:run`](../run-mojo.html) goal, you can configure which port to 
use to start up the site as well as the directory where the pages for the site 
will be rendered.
+The [`site:run`](../run-mojo.html) goal serves the site from a local HTTP 
server and renders each page when it is requested, so you can edit a document 
and reload the page in the browser to see the change. It uses the HTTP server 
that the JDK provides; no servlet container is needed.
 
-For example, you can have the following configuration in your POM:
+${esc.h}${esc.h} Start the server
+
+From the directory of a single project, run:
+
+```shell
+mvn site:run
+```
+
+The server listens on `http://localhost:8080/` until you stop Maven with 
`Ctrl+C`. The log shows the address, then the source of each page as it is 
rendered:
+
+```
+[INFO] --- site:${project.version}:run (default-cli) @ scratch-parent ---
+[INFO] Relativizing site links with respect to localized project URL: 
https://example.org/scratch/
+[INFO] Configuring report plugin maven-project-info-reports-plugin:3.9.0
+[INFO] Configured 2 reports for maven-project-info-reports-plugin:3.9.0: 
index, summary
+[INFO] Skipped "About" report (maven-project-info-reports-plugin:3.9.0:index), 
file "index.html" already exists.
+[INFO] Started site:run HTTP server on http://localhost:8080/
+[INFO] index.html -> src/site/markdown/index.md (default locale)
+[INFO] summary.html -> maven-project-info-reports-plugin:3.9.0:summary 
(default locale)
+[INFO] Generating "Summary" report              --- 
maven-project-info-reports-plugin:3.9.0:summary
+```
+
+`site:run` serves one project. To preview the links between the modules of a 
multi-module site, stage it with [`site:stage`](../stage-mojo.html) instead, as 
described in [Building multi-module 
sites](https://maven.apache.org/guides/mini/guide-multimodule-site.html).
+
+${esc.h}${esc.h} Change the host, the port or the working directory
+
+The [`host`](../run-mojo.html${esc.hash}host) and 
[`port`](../run-mojo.html${esc.hash}port) parameters choose where the server 
listens. Both can be set on the command line:
+
+```shell
+mvn site:run -Dport=9000
+```
+
+If the port is already taken, the goal fails with `Error creating HTTP server 
on localhost:<port>: Address already in use`. Use `-Dport=0` to let the system 
pick a free port; the log then shows which one it chose.
+
+Static resources, such as the skin and the files in `src/site/resources`, are 
copied to 
[`tempWebappDirectory`](../run-mojo.html${esc.hash}tempWebappDirectory), 
`target/site-webapp` by default. To set the parameters in the POM:
 
 ```xml
 <project>
@@ -41,7 +75,7 @@ For example, you can have the following configuration in your 
POM:
         <version>${project.version}</version>
         <configuration>
           <port>9000</port>
-          
<tempWebappDirectory>${basedir}/target/site/tempdir</tempWebappDirectory>
+          
<tempWebappDirectory>${esc.d}{project.build.directory}/site-tempdir</tempWebappDirectory>
         </configuration>
       </plugin>
     </plugins>
@@ -50,5 +84,8 @@ For example, you can have the following configuration in your 
POM:
 </project>
 ```
 
-When you execute &quot;`mvn site:run`&quot;, you will see in the command line 
that the HTTP server is started at port 9000\. To access the site, type 
`http://localhost:9000` in your browser. You will also see that the served site 
files are generated in the `${basedir}/target/site/tempdir` directory as 
specified by the `tempWebappDirectory` parameter.
+With this configuration, `mvn site:run` serves the site on 
`http://localhost:9000/` and copies the static resources to 
`target/site-tempdir`.
+
+${esc.h}${esc.h} Render the site to disk while you edit
 
+[`site:auto-refresh`](../auto-refresh-mojo.html) is the alternative when you 
want files instead of a server: it renders the site once into `target/site`, 
then renders a document again whenever its source changes, until you press 
Enter. In batch mode (`-B`) it renders the site once and stops.
diff --git a/src/site/markdown/faq.md b/src/site/markdown/faq.md
index 5329f86a..ffd1229e 100644
--- a/src/site/markdown/faq.md
+++ b/src/site/markdown/faq.md
@@ -29,7 +29,7 @@ under the License.
 
 1. [What is the difference between `mvn site` and `mvn 
site:site`?](#What_is_the_difference_between_mvn_site_and_mvn_site.3Asite)
 2. [How do I integrate static (X)HTML pages into my Maven 
site?](#How_do_I_integrate_static_.28X.29HTML_pages_into_my_Maven_site)
-3. [How to include a custom Doxia module, like 
Twiki?](#How_to_include_a_custom_Doxia_module.2C_like_Twiki)
+3. [How to include a custom Doxia module, like 
AsciiDoc?](#How_to_include_a_custom_Doxia_module.2C_like_Twiki)
 4. [How can I validate my xdoc/fml source files?](#Can_I_validate_xml)
 5. [How does the Site Plugin use the &lt;url&gt; element in the 
POM?](#Use_of_url)
 
@@ -45,38 +45,24 @@ under the License.
 
 ### What is the difference between `mvn site` and `mvn site:site`?
 
-<dl>
-<dt><code>mvn site</code></dt>
-<dd>Calls the <i>site</i> <b>phase</b> of the site <b>lifecycle</b>.
-Full site lifecycle consists of the following life cycle phases: 
<code>pre-site</code>, <code>site</code>, <code>post-site</code> and 
<code>site-deploy</code>.
-See <a 
href="/guides/introduction/introduction-to-the-lifecycle.html#Lifecycle_Reference">Lifecycle
 Reference</a>.
-Then it calls plugin goals associated to <code>pre-site</code> and 
<code>site</code> phases.</dd>
-<dt><code>mvn site:site</code></dt>
-<dd>Calls the <i>site</i> <b>goal</b> of the site <b>plugin</b>.
-See <a href="site-mojo.html">site:site</a>.</dd>
-</dl>
+`mvn site` runs the `site` **phase** of the site lifecycle, which consists of 
the `pre-site`, `site`, `post-site` and `site-deploy` phases (see the 
[Lifecycle 
Reference](/guides/introduction/introduction-to-the-lifecycle.html#Lifecycle_Reference)).
 Maven runs every plugin goal bound to `pre-site` and `site`, for example a 
resource filtering step bound to `pre-site`.
+
+`mvn site:site` runs only the [`site`](site-mojo.html) **goal** of the Site 
Plugin; goals bound to `pre-site` do not run.
 
 <a id="How_do_I_integrate_static_.28X.29HTML_pages_into_my_Maven_site"></a>
 
 ### How do I integrate static (X)HTML pages into my Maven site?
 
-You can integrate your static pages by following these steps:
+Put the pages in `src/site/resources`; they are copied to the site unchanged. 
Then link to them from a menu item in your `src/site/site.xml`. See [Adding 
Extra 
Resources](https://maven.apache.org/guides/mini/guide-site.html#Adding_Extra_Resources)
 in the site guide.
 
-- Put your static pages in the resources directory, 
`${basedir}/src/site/resources`
-- Create your `site.xml` and put it in `${basedir}/src/site`
-- Link to the static pages by modifying the menu section, create items and map 
them to the filenames of the static pages
+To have a page decorated by the skin like the other pages, write it as an 
XHTML document in `src/site/xhtml` instead.
 
 <!-- mention docbook explicitly so google can find this -->
 <a id="How_to_include_a_custom_Doxia_module.2C_like_Twiki"></a>
 
-### How to include a custom Doxia module, like Twiki?
+### How to include a custom Doxia module, like AsciiDoc?
 
-The site plugin handles out-of-box xhtml5, markdown, apt, xdoc and fml formats.
-If you want to use a custom format like AsciiDoc
-(or any other document format
-for which a doxia parser exists, see the list of
-[Doxia Markup Languages](/doxia/references/index.html)),
-you need to specify the corresponding Doxia module dependency, e.g. for 
AsciiDoc:
+Out of the box, the Site Plugin reads Markdown, APT, XDoc, FML and XHTML5 
documents. For any other format for which a Doxia parser exists (see the list 
of [Doxia Markup Languages](/doxia/references/index.html)), add the Doxia 
module as a dependency of the Site Plugin, as described in [Creating 
Content](https://maven.apache.org/guides/mini/guide-site.html#Creating_Content) 
in the site guide. For example, for AsciiDoc:
 
 ```xml
 <project>
@@ -91,7 +77,7 @@ you need to specify the corresponding Doxia module 
dependency, e.g. for AsciiDoc
           <dependency>
             <groupId>org.asciidoctor</groupId>
             <artifactId>asciidoctor-parser-doxia-module</artifactId>
-            <version><!-- version compatible with the Doxia version used by 
m-site-p --></version>
+            <version><!-- a version built for Doxia 2 --></version>
           </dependency>
         </dependencies>
       </plugin>
@@ -101,48 +87,27 @@ you need to specify the corresponding Doxia module 
dependency, e.g. for AsciiDoc
 </project>
 ```
 
-**Note** that the doxia version has to be adjusted to the
-site-plugin version you are using, see the [Migration Guide](migrate.html).
-In particular, for site plugin versions `>=2.1`
-you need to use doxia `>=1.1`.
+The module has to be built for the Doxia version that the Site Plugin uses: 
Doxia 2 since Site Plugin 3.20.0, see the [history](history.html).
 
 <a id="Can_I_validate_xml"></a>
 
 ### How can I validate my xdoc/fml source files?
 
-Since version 2.1.1 of the Site Plugin, there is a `validate`
-configuration parameter that switches on xml validation (default is off).
-Note that in the current implementation of the parser used by Doxia,
-validation requires an independent parsing run, so that every source
-file is actually parsed twice when validation is switched on.
-
-If validation is switched on, **all** xml source
-files need a correct schema and/or DTD definition.
-See the Doxia documentation on
-[validating xdocs](/doxia/references/xdoc-format.html#Validation),
-and the schema definitions for
-[xdoc](/doxia/doxia/doxia-modules/doxia-module-xdoc/using-xdoc-xsd.html)
-and
-[fml](/doxia/doxia/doxia-modules/doxia-module-fml/using-fml-xsd.html).
+Set the [`validate`](site-mojo.html#validate) parameter of `site:site`, for 
example with `mvn site -Dvalidate=true`. The log then shows:
+
+```
+[INFO] Validation is switched on, xml input documents will be validated!
+```
+
+Each XML document is parsed twice, once to validate it and once to render it, 
and any validation error fails the build. **All** XML source files then need a 
correct schema or DTD declaration. See the Doxia documentation on [validating 
xdocs](/doxia/references/xdoc-format.html#Validation), and the schema 
definitions for 
[xdoc](/doxia/doxia/doxia-modules/doxia-module-xdoc/using-xdoc-xsd.html) and 
[fml](/doxia/doxia/doxia-modules/doxia-module-fml/using-fml-xsd.html).
 
 <a id="Use_of_url"></a>
 
 ### How does the Site Plugin use the &lt;url&gt; element in the POM?
 
-The Site Plugin does not use the &lt;url&gt; element in the POM.
-The project URL is just a piece of information to let your users know
-where the project lives. Some other plugins (e.g. the 
project-info-report-plugin)
-may be used to present this information. If your project has a URL
-where the generated site is deployed, then put that URL into the
-&lt;url&gt; element. If the project's site is not deployed anywhere,
-then remove the &lt;url&gt; element from the POM.
-
-On the other hand, the &lt;distributionManagement.url&gt; is used in a 
multi-module
-build to construct relative links between the generated sub-module sites.
-In a multi module build it is important for the parent and child
-modules to have **different** URLs. If they have the
-same URL, then links within the combined site will not work.
-Note that a proper URL **should** also be terminated by a slash 
(&quot;/&quot;).
+The project `<url>` is where your users find the project. The Site Plugin uses 
it to make the absolute links of the site descriptor relative, see [the next 
question](#Why_do_my_absolute_links_get_translated_into_relative_links). If the 
project's site is not deployed anywhere, remove the `<url>` element from the 
POM; the log then warns that site links will not be relativized.
+
+The site URL in `<distributionManagement>`, `<site><url>`, is where 
[`site:deploy`](deploy-mojo.html) copies the site, and in a multi-module build 
[`site:stage`](stage-mojo.html) uses it to place each module and to build the 
links between modules. In a multi-module build, parent and child modules need 
**different** site URLs; if they share one, the links within the combined site 
do not work. End each URL with a slash (`/`). How child modules inherit these 
URLs is described in [Inheritanc [...]
 
 ## Specific issues
 
@@ -150,54 +115,38 @@ Note that a proper URL **should** also be terminated by a 
slash (&quot;/&quot;).
 
 ### Why do my absolute links get translated into relative links?
 
-This happens because the Site Plugin tries to make all URLs relative,
-when possible. If you have something like this defined in your
-`pom.xml`:
+The Site Plugin makes every link of the site descriptor relative to the 
project `<url>` when it can. With this in the `pom.xml` of a child module:
 
 ```xml
-<url>http://www.your.site.com/</url>
+<url>https://example.org/scratch/scratch-child/</url>
 ```
 
-and create links in your `site.xml` (just an example) like
-this:
+and this link in `site.xml`:
 
 ```xml
 <links>
-  <item name="Your Site" href="http://www.your.site.com/"/>
-  <item name="Maven 2" href="http://maven.apache.org/maven2/"/>
+  <item name="Example" href="https://example.org/"/>
 </links>
 ```
 
-You will see that the link to &quot;Your site&quot; will be a relative one, but
-that the link to &quot;Maven 2&quot; will be an absolute link.
+the generated page links to `../../`, because both URLs are on the same host. 
A link to another host stays absolute.
 
-There is an
-[issue for this in JIRA](https://issues.apache.org/jira/browse/MSITE-159),
-where you can read more about this.
+To keep all links as written, set the 
[`relativizeSiteLinks`](site-mojo.html#relativizeSiteLinks) parameter to 
`false`, for example with `mvn site -DrelativizeSiteLinks=false`. See 
[MSITE-159](https://issues.apache.org/jira/browse/MSITE-159) for the background.
 
 ### Why don't the links between parent and child modules work when I run 
&quot;`mvn site`&quot;?
 
-What &quot;`mvn site`&quot; will do for you, in a multi-project
-build, is to run &quot;`mvn site`&quot; for the parent and all its
-modules **individually**. The links between parent and child will
-**not** work here. They **will** however work when you deploy
-the site.
-
-If you want to test this, prior to deployment, you can run the
-[`site:stage`](./stage-mojo.html) goal as
-described in the [usage documentation](./usage.html)
-instead.
+In a multi-module build, `mvn site` generates the site of each module 
**individually**, in its own `target/site` directory, so the links between 
parent and child do not work there. They work once the site is deployed. To 
check them before deploying, run [`site:stage`](stage-mojo.html), as described 
in the [usage page](usage.html#Staging_a_Site) and in [Building multi-module 
sites](https://maven.apache.org/guides/mini/guide-multimodule-site.html).
 
 <a id="Can_I_use_entities"></a>
 
 ### Can I use entities in xdoc/fml source files?
 
-Yes. Entity resolution has been added in Doxia version 1.1, available
-in Site Plugin 2.1 and later.
+Partly. The predefined XML entities, the HTML entities such as `&copy;`, and 
character references such as `&#174;` work. An entity declared in the 
document's DOCTYPE works only if its value is itself a character reference or 
an HTML entity:
+
+```xml
+<!DOCTYPE document [
+  <!ENTITY reg2 "&#174;">
+]>
+```
 
-There is a catch however. In the current implementation (as of 
maven-site-plugin-2.1.1),
-entities are only resolved by an independent
-[validation](#Can_I_validate_xml) run.
-Therefore, if you want to use entities, you **have** to switch on
-validation for your xml source files.
-See [MSITE-483](https://issues.apache.org/jira/browse/MSITE-483).
+An entity whose value is plain text, such as `<!ENTITY product "My Product">`, 
renders as an empty string, with or without [validation](#Can_I_validate_xml). 
To reuse text across pages, use [Velocity 
properties](https://maven.apache.org/guides/mini/guide-site.html#Using_Properties_in_Content)
 or [filtering with the Maven Resources 
Plugin](https://maven.apache.org/guides/mini/guide-site.html#Filtering_with_Maven_Resources_Plugin)
 instead.
diff --git a/src/site/markdown/history.md b/src/site/markdown/history.md
index 0a430959..3a21ad07 100644
--- a/src/site/markdown/history.md
+++ b/src/site/markdown/history.md
@@ -36,7 +36,7 @@ Knowing which version of maven-site-plugin uses which version 
of Doxia or Doxia
 
 | release date | maven-site-plugin | [Doxia][d]  | [Doxia Sitetools][dst] | 
[Maven Reporting Executor][mre] | minimum Java | minimum Maven | Comment        
                                |
 
|--------------|-------------------|-------------|------------------------|---------------------------------|--------------|---------------|------------------------------------------------|
-| 2026-05      | 3.22.0            | 2.1.0       | =                      | 
2.0.1                           |              |               | Doxia 2.1.0, 
with support for Mermaid diagrams |
+| 2026-05      | 3.22.0            | 2.1.0       | =                      | 
2.0.1                           | 8            | 3.6.3         | Doxia 2.1.0, 
with support for Mermaid diagrams |
 | 2024-10      | 3.21.0            | 2.0.0       | =                      | 
2.0.0                           | 8            | 3.6.3         | Doxia 2.0.0    
                                |
 | 2024-08      | 3.20.0            | *2.0.0-M12* | *2.0.0-M19*            | 
*2.0.0-M14*                     |              |               |                
                                |
 | *2024-07*    | *4.0.0-M16*       | *2.0.0-M12* | *2.0.0-M19*            | 
*2.0.0-M14*                     |              |               |                
                                |
diff --git a/src/site/markdown/migrate.md b/src/site/markdown/migrate.md
index 4704e148..016e12bc 100644
--- a/src/site/markdown/migrate.md
+++ b/src/site/markdown/migrate.md
@@ -27,7 +27,13 @@ under the License.
 
 # Migrate
 
-The Site Plugin has had a couple of upgrades that requires the user to make 
adjustments to their environment, documents or configuration. Below is a list 
of key changes and what updates you as a user need to be aware of: you can have 
a look at [history](./history.html) for precise details of internal components 
updates.
+The Site Plugin has had a couple of upgrades that require you to adjust your 
environment, documents or configuration. Below is a list of key changes and 
what you need to be aware of: see the [history](./history.html) for the 
versions of the internal components.
+
+## From 3\.22\.x to 3\.23\.0
+
+- The plugin requires Maven 3\.9\.0 or later; 3\.22\.0 ran on Maven 3\.6\.3. 
Java 8 is still enough.
+- [`site:run`](./run-mojo.html) serves the site with the HTTP server built 
into the JDK instead of Jetty 9, which is no longer maintained. The `host`, 
`port` and `tempWebappDirectory` parameters are unchanged; Jetty is no longer 
on the plugin class path, so remove any Jetty dependency or configuration you 
added for `site:run`. See [Configuring Site Run](./examples/siterun.html).
+- Properties passed on the command line with `-D` are available when the site 
descriptor is interpolated: with `<item name="Built with ${my.flag}" .../>` in 
`site.xml`, `mvn site -Dmy.flag=CI` renders `Built with CI`. Run `mvn clean 
site` after changing them, since unchanged documents are not rendered again.
 
 ## From 3\.12\.x to 3\.20\.0
 
@@ -42,27 +48,11 @@ Version 3\.20\.0 moves the plugin onto the [Doxia 2\.0\.0 
stack](/doxia/) and Ma
 
 ## From 3\.4 to 3\.5\.1
 
-- Since [Velocity](http://velocity.apache.org) has been upgraded from version 
1\.5 to version 1\.7, which changes escaping rules, you may need to update 
escape sequences in your `.vm` documents and/or skins. If you can&apos;t update 
content and/or skin immediately, you can manually downgrade Velocity version by 
configuring a dependency to Maven Site Plugin:
-
-    ```xml
-        <plugin>
-          <groupId>org.apache.maven.plugins</groupId>
-          <artifactId>maven-site-plugin</artifactId>
-          <dependencies>
-            <dependency>
-              <groupId>org.apache.velocity</groupId>
-              <artifactId>velocity</artifactId>
-              <version>1.5</version>
-            </dependency>
-          </dependencies>
-        </plugin>
-    ```
-
 - Site Decoration Model 1\.7\.0 has changed type for `head` and `footer` from 
`DOM` to `String`: if your `site.xml` (or one parent) contains XML content, 
you&apos;ll need to escape it, usually by adding `<![CDATA[` and `]]>` around 
the content:
 
     ```xml
     <project xmlns="http://maven.apache.org/DECORATION/1.7.0"; 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
-        xsi:schemaLocation="http://maven.apache.org/DECORATION/1.7.0 
http://maven.apache.org/xsd/decoration-1.7.0.xsd";>
+        xsi:schemaLocation="http://maven.apache.org/DECORATION/1.7.0 
https://maven.apache.org/xsd/decoration-1.7.0.xsd";>
         <body>
             <head>
                 <![CDATA[<anyHeadElement/>]]>
@@ -75,27 +65,14 @@ Version 3\.20\.0 moves the plugin onto the [Doxia 2\.0\.0 
stack](/doxia/) and Ma
     </project>
     ```
 
-- Interpolation of `${project.*}` and `${*}` expressions in `site.xml` have 
changed to be consistent with equivalent feature in Maven `pom.xml`: 
interpolation is now done _after_ inheritance. For `site.xml`, this may lead to 
failures on urls (often on `${project.url}` expression), that are expected to 
be rebased during inheritance: a new _early interpolation_ feature has been 
added in Maven Site Plugin 3\.5\.1 throught `${this.*}` expressions (see [ 
Doxia Integration Tools reference docu [...]
-
-## From 2\.x to 3\.x
-
-- Version 3 of the plugin requires at least **Maven 2\.2\.0** to run.
-- If you use **Maven 3** please read the [Maven 3](./maven-3.html) guide about 
relevant issues.
-
-## From 2\.2\.x to 2\.3\.x
-
-- The `site:stage` and `site:stage-deploy` goals have been decoupled from site 
generation. Executing these goals without generating the site first will lead 
to a build failure.
-
-## From 2\.1\.x to 2\.2\.x
+- Interpolation of `${project.*}` and `${*}` expressions in `site.xml` is done 
_after_ inheritance, consistent with the equivalent feature in Maven `pom.xml`. 
For `site.xml`, this may lead to failures on URLs (often on `${project.url}` 
expression) that are expected to be rebased during inheritance. Use `${this.*}` 
expressions, such as `${this.url}` or `${this.customProperty}`, for _early 
interpolation_ before inheritance (see the [Doxia Integration Tools reference 
documentation](/doxia/d [...]
+- Velocity was upgraded from 1\.5 to 1\.7, which changed the escaping rules in 
`.vm` documents and skins. Current versions use Velocity 2, see the [Velocity 
2\.0 upgrade notes](https://velocity.apache.org/engine/2.0/upgrading.html).
 
-- The plugin now requires at least **Maven 2\.2\.0** to run, you cannot use it 
with older Maven versions.
-- The plugin now requires at least **Java 5** to run, you cannot use it with 
older Java versions.
+<a id="From_2.x_to_3.x"></a>
+<a id="From_2.2.x_to_2.3.x"></a>
+<a id="From_2.1.x_to_2.2.x"></a>
+<a id="From_2.0.x_to_2.1.x"></a>
 
-## From 2\.0\.x to 2\.1\.x
+## From 2\.x
 
-- The plugin now requires at least **Maven 2\.1** to run, you cannot use it 
with older Maven versions.
-- The plugin has been upgraded to use **Doxia 1\.1**, which has seen a lot of 
major changes itself. If you experience unexpected behavior, please read these 
resources:
-    - [Doxia: what&apos;s new in 1\.1?](/doxia/whatsnew-1.1.html)
-    - [Doxia: Enhancements to the APT format](/doxia/references/doxia-apt.html)
-    - [Doxia: Issues &amp; Gotchas](/doxia/issues/index.html)
-    - [Doxia: Frequently Asked Questions](/doxia/faq.html)
+Site Plugin 2\.x ran on Maven 2 and Doxia 1\.1. Upgrade directly to the 
current version: follow the notes above from 3\.4 on, and run `site:site` 
before `site:stage` or `site:stage-deploy`, which do not generate the site 
themselves.
diff --git a/src/site/markdown/usage.md b/src/site/markdown/usage.md
index b5930b75..d23411e4 100644
--- a/src/site/markdown/usage.md
+++ b/src/site/markdown/usage.md
@@ -44,7 +44,7 @@ By default, the resulting site will be in the `target/site/` 
directory.
 
 **Note:** If you have a multi module project, then the links between the 
parent and child modules will _not_ work when you use `mvn site` or `mvn 
site:site`. If you want to use those links, you should use `mvn site:stage` 
instead. You can read more about that goal further down on this page in the 
section called &apos;_Staging a Site_&apos;.
 
-**Note:** For performance reasons, Maven compares the timestamps of generated 
files and corresponding source documents, and only regenerates documents that 
have changed since the last build. However, this only applies to documentation 
source documents (apt, xdoc,...). If you change anything in your `site.xml`, 
any relevant sections in your pom, or any relevant properties or resource 
files, you should generate the site from scratch to make sure all references 
and links are correct.
+**Note:** For performance reasons, the Site Plugin compares the timestamps of 
generated files and corresponding source documents, and only regenerates 
documents that have changed since the last build. However, this only applies to 
documentation source documents (Markdown, APT, XDoc and so on). If you change 
anything in your `site.xml`, any relevant sections in your POM, any relevant 
properties or resource files, or the `-D` properties you pass on the command 
line, run `mvn clean site` to [...]
 
 ## Deploying a Site
 
@@ -55,8 +55,8 @@ To be able to deploy the site, you must first specify where 
the site will be dep
   ...
   <distributionManagement>
     <site>
-      <id>www.yourcompany.com</id>
-      <url>scp://www.yourcompany.com/www/docs/project/</url>
+      <id>www.mycompany.com</id>
+      <url>scp://www.mycompany.com/www/docs/project/</url>
     </site>
   </distributionManagement>
   ...
@@ -65,7 +65,7 @@ To be able to deploy the site, you must first specify where 
the site will be dep
 
 The `<id>` element identifies the repository, so that you can attach 
credentials to it in your `settings.xml` file using the [`<servers>` 
element](/ref/current/maven-settings/settings.html#Servers) as you would for 
any other repository.
 
-The `<url>` gives the location to deploy to. In the example above we copy to 
the host `www.mycompany.com` using the path `/www/docs/project/` over the `scp` 
protocol. You can read more about which protocols are supported on [this 
page](./examples/adding-deploy-protocol.html). If subprojects inherit the site 
URL from a parent POM, they will automatically append their `<artifactId>` to 
form their effective deployment location.
+The `<url>` gives the location to deploy to. In the example above we copy to 
the host `www.mycompany.com` using the path `/www/docs/project/` over the `scp` 
protocol. Only `file:` URLs work out of the box; `scp` and other protocols need 
a Wagon provider, see [Adding a Protocol to Deploy the 
Site](./examples/adding-deploy-protocol.html). How child modules inherit the 
site URL is described in [Inheritance of the Site Distribution 
Management](https://maven.apache.org/guides/mini/guide-multi [...]
 
 Now you can execute the [`site:deploy`](./deploy-mojo.html) goal from your 
project directory.
 
@@ -130,11 +130,13 @@ The Site Plugin can also be used to start up the site in 
a local HTTP server. To
 mvn site:run
 ```
 
-The server will, by default, be started on `http://localhost:8080/`.
+The server will, by default, be started on `http://localhost:8080/`, and 
renders each page when it is requested, so an edited document shows up on the 
next reload. It uses the HTTP server provided by the JDK. The `port` and `host` 
parameters change the address, for example `mvn site:run -Dport=9000`; see 
[Configuring Site Run](./examples/siterun.html).
 
 **Note:** Running a site only works for single-module sites. To preview a 
multi-module site one should use `site:stage`.
 
+To write the pages to `target/site` instead, run 
[`site:auto-refresh`](./auto-refresh-mojo.html): it renders the site once, then 
renders a document again whenever its source changes, until you press Enter. In 
batch mode (`-B`) it renders the site once and stops.
+
 ## Rebuilding a Published (Released) Site
 
-In general, site documentation is published as part of a release. This means 
that changes to the documentation depend on a new release before being visible 
_or_ you must accept that the documentation refers to a snapshot version 
instead of the latest release version. To solve that problem, you first need to 
configure your project for reproducibility by setting the 
`project.build.outputTimestamp` model property. Then branch off from the SCM 
tag you want to modify, perform the changes, com [...]
+In general, site documentation is published as part of a release. This means 
that changes to the documentation depend on a new release before being visible 
_or_ you must accept that the documentation refers to a snapshot version 
instead of the latest release version. To solve that problem, you first need to 
configure your project for reproducibility by setting the 
`project.build.outputTimestamp` model property. Then branch off from the SCM 
tag you want to modify, perform the changes, com [...]
 

Reply via email to