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'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
"Project Reports".
-
-**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 ("R" value in the "Type"
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't forget to define reportSets for plugins which provide
aggregator reports, like maven-javadoc-plugin, maven-jxr-plugin or
maven-checkstyle-plugin or you'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 "`mvn
site`".
+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 "`mvn site:run`", 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 <url> 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 <url> element in the POM?
-The Site Plugin does not use the <url> 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
-<url> element. If the project's site is not deployed anywhere,
-then remove the <url> element from the POM.
-
-On the other hand, the <distributionManagement.url> 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
("/").
+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 ("/").
### 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 "Your site" will be a relative one, but
-that the link to "Maven 2" 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
"`mvn site`"?
-What "`mvn site`" will do for you, in a multi-project
-build, is to run "`mvn site`" 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 `©`, and
character references such as `®` 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 "®">
+]>
+```
-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'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'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's new in 1\.1?](/doxia/whatsnew-1.1.html)
- - [Doxia: Enhancements to the APT format](/doxia/references/doxia-apt.html)
- - [Doxia: Issues & 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 '_Staging a Site_'.
-**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 [...]