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


The following commit(s) were added to refs/heads/master by this push:
     new 06aefefa Merge the Maven Site Plugin content guides into the site 
guides
06aefefa is described below

commit 06aefefa066184e850c5892d50c142cfcc75e1d7
Author: Sylwester Lachiewicz <[email protected]>
AuthorDate: Sat Oct 31 20:02:55 2026 +0000

    Merge the Maven Site Plugin content guides into the site guides
---
 content/filtered-resources/.htaccess               |   5 +
 content/markdown/guides/index.md.vm                |   1 +
 .../markdown/guides/mini/guide-multimodule-site.md |  93 ++++++++++++++
 content/markdown/guides/mini/guide-site.md         | 141 ++++++++++++++++++---
 content/markdown/skins/index.md                    |  18 +++
 content/site.xml                                   |   1 +
 6 files changed, 242 insertions(+), 17 deletions(-)

diff --git a/content/filtered-resources/.htaccess 
b/content/filtered-resources/.htaccess
index f9e1188b..79e47f5d 100644
--- a/content/filtered-resources/.htaccess
+++ b/content/filtered-resources/.htaccess
@@ -40,7 +40,12 @@ Redirect Permanent 
/plugins/maven-compiler-plugin/multirelease.html /guides/mini
 Redirect Permanent /plugins/maven-deploy-plugin/examples/deploy-ftp.html 
/guides/mini/guide-deployment-transports.html#FTP
 Redirect Permanent /plugins/maven-deploy-plugin/examples/deploy-http.html 
/guides/mini/guide-deployment-transports.html#HTTP.28S.29
 Redirect Permanent 
/plugins/maven-deploy-plugin/examples/deploy-ssh-external.html 
/guides/mini/guide-deployment-transports.html#SSH_with_external_executables
+Redirect Permanent /plugins/maven-site-plugin/examples/creating-content.html 
/guides/mini/guide-site.html#Creating_Content
+Redirect Permanent /plugins/maven-site-plugin/examples/creatingskins.html 
/skins/#Creating_a_skin
+Redirect Permanent /plugins/maven-site-plugin/examples/filtering-content.html 
/guides/mini/guide-site.html#Filtering_with_Maven_Resources_Plugin
 Redirect Permanent /plugins/maven-site-plugin/examples/mermaid-diagrams.html 
/doxia/mermaid-diagrams.html
+Redirect Permanent /plugins/maven-site-plugin/examples/multimodule.html 
/guides/mini/guide-multimodule-site.html
+Redirect Permanent /plugins/maven-site-plugin/i18n.html 
/plugins/localization.html
 Redirect Permanent /plugins/maven-toolchains-plugin/toolchains/index.html 
/guides/mini/guide-using-toolchains.html
 Redirect Permanent /plugins/maven-toolchains-plugin/toolchains/jdk.html 
/guides/mini/guide-using-toolchains.html#JDK_Toolchain
 Redirect Permanent /plugins/maven-toolchains-plugin/toolchains/custom.html 
/guides/mini/guide-using-toolchains.html#Custom_Toolchains
diff --git a/content/markdown/guides/index.md.vm 
b/content/markdown/guides/index.md.vm
index c492dc51..13547f4c 100644
--- a/content/markdown/guides/index.md.vm
+++ b/content/markdown/guides/index.md.vm
@@ -47,6 +47,7 @@ User Centre
 #[[#### Site]]#
 
 - [Creating a Site](./mini/guide-site.html)
+- [Building Multi-module Sites](./mini/guide-multimodule-site.html)
 - [The APT Format](/doxia/references/apt-format.html)
 - [Snippet Macro](./mini/guide-snippet-macro.html)
 #[[### Getting Started with Maven]]#
diff --git a/content/markdown/guides/mini/guide-multimodule-site.md 
b/content/markdown/guides/mini/guide-multimodule-site.md
new file mode 100644
index 00000000..86024658
--- /dev/null
+++ b/content/markdown/guides/mini/guide-multimodule-site.md
@@ -0,0 +1,93 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Building multi-module sites
+
+When running `mvn site` on a top level project, Maven builds the sites of all 
modules defined in the `modules` section of the POM individually. Each site is 
generated in the `target` directory of its own project. As a result, relative 
links between different modules do NOT work in the build output. They work when 
you deploy or stage the site.
+
+## Staging and deploying
+
+To preview the whole tree of a multi-module site, use the 
[`site:stage`](/plugins/maven-site-plugin/stage-mojo.html) goal. It copies the 
individual sites to their proper place at the staging location.
+
+[`site:deploy`](/plugins/maven-site-plugin/deploy-mojo.html) does the same 
thing as `site:stage`, but uses the URL defined in the 
`<distributionManagement>` element of the POM as the deployment location. This 
is usually a remote URL, but both remote protocols like `scp` and local 
protocols like `file` are supported.
+
+Finally, 
[`site:stage-deploy`](/plugins/maven-site-plugin/stage-deploy-mojo.html) does 
the same thing as `site:deploy` but uses the `stagingDirectory` parameter as 
the deployment location. This deploys the site to a remote staging area 
(`site:stage` is always local).
+
+**Notes:**
+
+- If subprojects inherit the (distribution) site URL from a parent POM, they 
automatically append their _artifactId_ to form their effective deployment 
location. This goes for both the project URL and the URL defined in the 
`<distributionManagement>` element of the POM.
+- If your multi-module tree does not follow the Maven conventions, or if 
module directories are named differently than module artifacts, you have to 
specify the URLs for **each** child project. See also [How does the Site Plugin 
use the `<url>` element in the 
POM?](/plugins/maven-site-plugin/faq.html#Use_of_url).
+- The `pom.xml` of the topmost project in a multi-module build must define the 
`distributionManagement` URL element (called "rootURL" hereafter). The rootURL 
must be the topmost `distributionManagement` URL in the multi-module project, 
implying that any `distributionManagement` URL defined within another project 
in a multi-module build must start with the rootURL and append unique paths (to 
be situated "below" the rootURL).
+- All projects in multi-module builds must define unique 
`distributionManagement` URL elements, below the root `distributionManagement` 
URL in terms of URL path.
+- If the artifactId and module name (the directory name) are not identical for 
any project within a multi-module build, the `distributionManagement` URL 
element must be defined in the `pom.xml` file of that project.
+
+## Inheritance
+
+Site descriptors are inherited along the same lines as project descriptors 
are. If you want the site descriptor of your project to be inherited, you need 
to attach it to the main artifact of the project. Use the 
[`site:attach-descriptor`](/plugins/maven-site-plugin/attach-descriptor-mojo.html)
 goal to attach the site descriptor to the main artifact.
+
+In Maven 3 you must attach the site descriptor yourself, even for projects 
with packaging set to `pom`.
+
+By default, all the parent descriptor settings are inherited with the only 
exception of menus, see below. From the body, the links and breadcrumbs 
accumulate to contain all the links and breadcrumbs of the parent site 
descriptor. If the parent contains a breadcrumb and the inheriting site 
descriptor doesn't, a breadcrumb with the name of the current site descriptor 
is added automatically.
+
+It is possible to inherit menus as well. To do so, use the `inherit` attribute 
in the site descriptor. This can be either `top` or `bottom`, indicating where 
the inherited menu is placed. For example:
+
+```xml
+<site>
+  ...
+  <body>
+    ...
+    <menu name="My Inherited Menu" inherit="top">
+      ...
+    </menu>
+    ...
+  </body>
+  ...
+</site>
+```
+
+## Aggregate Reports
+
+Some reports can be run against the sum of all modules: these are aggregate 
reports. This is the case of maven-javadoc-plugin, maven-jxr-plugin or 
maven-checkstyle-plugin.
+
+To benefit from aggregate reports, configure a report set in the parent POM, 
and turn inheritance off so that the aggregate report does not run in the 
modules. For example, with maven-jxr-plugin:
+
+```xml
+<project>
+  ...
+  <reporting>
+    <plugins>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-jxr-plugin</artifactId>
+        <version>3.6.0</version>
+        <reportSets>
+          <reportSet>
+            <id>aggregate</id>
+            <inherited>false</inherited>
+            <reports>
+              <report>aggregate</report>
+            </reports>
+          </reportSet>
+        </reportSets>
+      </plugin>
+    </plugins>
+  </reporting>
+  ...
+</project>
+```
diff --git a/content/markdown/guides/mini/guide-site.md 
b/content/markdown/guides/mini/guide-site.md
index 402e5807..d5212239 100644
--- a/content/markdown/guides/mini/guide-site.md
+++ b/content/markdown/guides/mini/guide-site.md
@@ -39,6 +39,9 @@ The first step to creating your site is to create some 
content. In Maven, the si
       +- xdoc/
       |  +- other.xml
       |
+      +- xhtml/
+      |  +- xhtml-content.xhtml
+      |
       +- site.xml
 ```
 
@@ -46,16 +49,36 @@ You will notice there is now a 
`${project.basedir}/src/site` directory within wh
 
 Let's take a look at the examples of the various document types:
 
-- `markdown`: the well known 
[Markdown](https://en.wikipedia.org/wiki/Markdown) format, and the one this 
page is written in. It is what new documentation should use,
-- `apt`: the APT format, "Almost Plain Text", a wiki-like format that predates 
Maven's support for Markdown. It is still supported, but the Maven project 
itself has moved its own documentation off it; see the [APT 
Format](/doxia/references/apt-format.html) reference if you are maintaining an 
existing page, and [doxia-converter](/doxia/doxia-tools/doxia-converter/) if 
you would like to convert one,
+- `markdown`: the well known 
[Markdown](https://en.wikipedia.org/wiki/Markdown) format (supported since 
Maven Site Plugin 3.3), and the one this page is written in. It is what new 
documentation should use,
+- `apt`: the APT format, "Almost Plain Text", a wiki-like format that predates 
Maven's support for Markdown. It is still supported, but the Maven project 
itself has moved its own documentation off it; see the [APT 
Format](/doxia/references/apt-format.html) reference if you are maintaining an 
existing page, and [Migrating APT to 
Markdown](/doxia/migrating-apt-to-markdown.html) if you would like to convert 
one,
 - `fml`: the FML format is the [FAQ format](/doxia/references/fml-format.html),
-- `xdoc`: an XML document conforming to a small and simple set of tags, see 
the [full reference](/doxia/references/xdoc-format.html).
+- `xdoc`: an XML document conforming to a small and simple set of tags, see 
the [full reference](/doxia/references/xdoc-format.html),
+- `xhtml`: plain XHTML documents.
+
+Other formats are available, but at this point the first 4 are the best 
tested. Any other format for which a Doxia parser exists (see the list of 
[Doxia Markup Languages](/doxia/references/index.html)) can be used as well, 
but you need to add the corresponding Doxia module to the dependencies of the 
Maven Site Plugin.
 
-Other formats are available, but at this point these 4 are the best tested.
+There are also several possible output formats, but as of Maven Site Plugin, 
only XHTML5 is available.
 
-There are also several possible output formats, but as of Maven Site Plugin, 
only XHTML is available.
+Note that all of the above is optional - just one index file is required in 
one of the input trees. Each of the paths will be merged together to form the 
root directory of the site. After running `mvn site` on the example above you 
will end up with this in your `target` directory:
 
-Note that all of the above is optional - just one index file is required in 
one of the input trees. Each of the paths will be merged together to form the 
root directory of the site.
+```
++- target/
+   +- site/
+      +- css/
+      |
+      +- images/
+      |
+      +- index.html
+      +- content.html
+      +- general.html
+      +- faq.html
+      +- other.html
+      +- xhtml-content.html
+```
+
+This means that `src/site/apt/content.apt` is available in the site as 
`/content.html`, whichever directory it comes from. So, in your [site 
descriptor](/plugins/maven-site-plugin/examples/sitedescriptor.html) you link 
to `index.html` and `other.html`, where the sources of these two files are 
`src/site/markdown/index.md` and `src/site/xdoc/other.xml`.
+
+The `css` and `images` directories contain the stylesheets and images of the 
skin being used.
 
 ## Customizing the Look &amp; Feel
 
@@ -63,9 +86,7 @@ If you want to tune the way your site looks, you can use a 
custom **skin** to pr
 
 You can visit the [Skins index](/skins/) to have a look at some of the skins 
that you can use to change the look of your site.
 
-<!--  TODO: The following link is currently not available. Restore it when it 
becomes available again.-->
-<!--  For an in-depth discussion of site customization, please have a look at 
the-->
-<!--  {{{http://www.sonatype.com/book/site-generation.html} Maven User Guide, 
Chapter 9, "Site Generation"}}.-->
+To build a skin of your own, see [Creating a skin](/skins/#Creating_a_skin).
 
 ## Generating the Site
 
@@ -117,7 +138,7 @@ For example with a project hosted on GitHub and using 
GitHub Pages for its site
 <plugin>
   <groupId>org.apache.maven.plugins</groupId>
   <artifactId>maven-scm-publish-plugin</artifactId>
-  <version>3.1.0</version>
+  <version>3.3.0</version>
   <configuration>
     <pubScmUrl>${project.scm.developerConnection}</pubScmUrl>
     <scmBranch>gh-pages</scmBranch>
@@ -190,10 +211,96 @@ You can add any arbitrary resource to your site by 
including them in a `resource
             +- pic1.jpg
 ```
 
-The file `site.css` will be added to the default XHTML output, so it can be 
used to adjust the default Maven stylesheets if desired.
+The file `site.css` will be added to the default XHTML5 output, so it can be 
used to adjust the default Maven stylesheets if desired.
 
 The file `pic1.jpg` will be available via a relative reference to the `images` 
directory from any page in your site.
 
+## Using Properties in Content
+
+To add simple logic to your content, for example to filter properties, add a 
`.vm` extension to the file name (this is valid for all supported formats). 
[Apache Velocity](https://velocity.apache.org/) is the templating engine.
+
+For example, the Maven website itself has a 
[`content/xdoc/download.xml.vm`](https://github.com/apache/maven-site/blob/master/content/xdoc/download.xml.vm)
 file, which uses the expression `${currentStableVersion}` to filter in a 
property set in the 
[POM](https://github.com/apache/maven-site/blob/master/pom.xml).
+
+Some properties are defined by default: see [Doxia Site Renderer's Velocity 
processing 
reference](/doxia/doxia-sitetools/doxia-site-renderer/#Velocity_processing) for 
more information. For a complete usage overview, see Velocity's [user 
guide](https://velocity.apache.org/engine/2.3/user-guide.html).
+
+Since version 3.5 of the Maven Site Plugin, you can save the processed markup 
by setting 
[`saveProcessedContent`](/plugins/maven-site-plugin/site-mojo.html#saveProcessedContent)
 to `true`.
+
+### Common Issues and Workarounds
+
+- **Dotted properties**: Velocity uses a dot notation to traverse beans, so 
you **cannot** use dotted properties defined in `<properties>` directly. Access 
them through the `$context` tool instead: for example 
`$context.get("my.property")`.
+- **Markdown conflicts with Velocity on the `##` syntax**: `##` starts a 
[single line 
comment](https://velocity.apache.org/engine/2.3/vtl-reference.html#single-line-comments)
 in Velocity, so Markdown headings written with it are suppressed from the 
generated content. Use the [unparsed content 
syntax](https://velocity.apache.org/engine/2.3/vtl-reference.html#unparsed-content),
 `#[[## Heading]]#`, or the [escape 
tool](https://velocity.apache.org/tools/3.1/apidocs/org/apache/velocity/tools/ 
[...]
+
+### Filtering with Maven Resources Plugin
+
+Velocity has drawbacks for plain property interpolation:
+
+- not everyone is familiar with the Velocity syntax,
+- the web-based preview (for example on GitHub) does not work,
+- Velocity and Markdown both use `##`, for different purposes, and
+- the overhead is large for simple replacements.
+
+For simple property interpolation, regular [Maven 
filtering](./guide-filtering-resources.html) is often more suitable. Create a 
dedicated source directory that 
[`maven-resources-plugin:copy-resources`](/plugins/maven-resources-plugin/copy-resources-mojo.html)
 processes before the site is created. In the following example, the directory 
`src/site` is copied with filtering to `target/site-src`:
+
+```xml
+<project>
+  ...
+  <build>
+    <plugins>
+      <plugin>
+        <!-- prepare site content by filtering ${project.*} values -->
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-resources-plugin</artifactId>
+        <executions>
+          <execution>
+            <id>filter-site</id>
+            <phase>pre-site</phase>
+            <goals>
+              <goal>copy-resources</goal>
+            </goals>
+            <configuration>
+              
<outputDirectory>${project.build.directory}/site-src</outputDirectory>
+              <resources>
+                <resource>
+                  <directory>src/site</directory>
+                  <filtering>true</filtering>
+                </resource>
+              </resources>
+            </configuration>
+          </execution>
+        </executions>
+      </plugin>
+      ...
+    </plugins>
+  </build>
+</project>
+```
+
+Then generate the site from the filtered sources by adjusting the 
[`siteDirectory`](/plugins/maven-site-plugin/site-mojo.html#siteDirectory) of 
the Maven Site Plugin. Also adjust the 
[`alternativeSiteSourceDirectories`](/plugins/maven-site-plugin/site-mojo.html#alternativeSiteSourceDirectories),
 which the edit buttons use:
+
+```xml
+<project>
+  ...
+  <build>
+    <plugins>
+      ...
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-site-plugin</artifactId>
+        <configuration>
+          <siteDirectory>${project.build.directory}/site-src</siteDirectory>
+          
<alternativeSiteSourceDirectories>${basedir}/src/site</alternativeSiteSourceDirectories>
+        </configuration>
+      </plugin>
+      ...
+    </plugins>
+  </build>
+</project>
+```
+
+## Multi-module Sites
+
+Running `mvn site` on a multi-module project builds the site of every module 
individually, and relative links between module sites work only after you stage 
or deploy. See [Building multi-module sites](./guide-multimodule-site.html) for 
staging, deployment, site descriptor inheritance and aggregate reports.
+
 ## 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 plugins, just like 
those used to build the project.
@@ -220,7 +327,7 @@ To add these reports to your site, you must add the Project 
Info Reports plugin
       <plugin>
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-project-info-reports-plugin</artifactId>
-        <version>2.8</version><!-- define version here if not already defined 
in build/plugins or build/pluginManagement -->
+        <version>3.9.0</version><!-- define version here if not already 
defined in build/plugins or build/pluginManagement -->
       </plugin>
     </plugins>
   </reporting>
@@ -238,7 +345,7 @@ Many other plugins provide reporting goals: look for "R" 
(Reporting) value in th
 
 ## Internationalization
 
-Internationalization in Maven is very simple, as long as the reports you are 
using have that particular locale defined. For an overview of supported 
languages and instructions on how to add further languages, please see the 
related article 
[Internationalization](../../plugins/maven-site-plugin/i18n.html) from the 
Maven Site Plugin.
+Internationalization in Maven is very simple, as long as the reports you are 
using have that particular locale defined. For an overview of supported 
languages and instructions on how to add further languages, see 
[Internationalization](/plugins/localization.html).
 
 To enable multiple locales, add a configuration similar to the following to 
your POM:
 
@@ -250,9 +357,9 @@ To enable multiple locales, add a configuration similar to 
the following to your
       <plugin>
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-site-plugin</artifactId>
-        <version>3.4</version>
+        <version>3.22.0</version>
         <configuration>
-          <locales>en,fr</locales>
+          <locales>default,fr</locales>
         </configuration>
       </plugin>
     </plugins>
@@ -261,7 +368,7 @@ To enable multiple locales, add a configuration similar to 
the following to your
 </project>
 ```
 
-This will generate both an English and a French version of the site. If `en` 
is your current locale, then it will be generated at the root of the site, with 
a copy of the French translation of the site in the `fr/` subdirectory.
+This generates both a default (`Locale#ROOT`) and a French version of the 
site. The default version is at the root of the site, with a copy of the French 
translation in the `fr/` subdirectory.
 
 To add your own content for that translation instead of using the default, 
place a subdirectory with that locale name in your site directory and create a 
new site descriptor with the locale in the file name. For example:
 
@@ -279,4 +386,4 @@ To add your own content for that translation instead of 
using the default, place
       +- site_fr.xml      (French site descriptor)
 ```
 
-With one site descriptor per language, the translated site(s) can evolve 
independently.
+With one site descriptor per language, the translated sites can evolve 
independently.
diff --git a/content/markdown/skins/index.md b/content/markdown/skins/index.md
index 2d0d506b..954b9a59 100644
--- a/content/markdown/skins/index.md
+++ b/content/markdown/skins/index.md
@@ -67,3 +67,21 @@ For example, to use the Maven Fluido Skin, you would include 
this in your `site.
 </site>
 ```
 
+## Creating a skin
+
+If you want to tune the way your site looks, you can use a custom skin to 
provide your own CSS stylesheets. If that is still not enough, you can tweak 
the output templates that Maven uses to generate the site documentation.
+
+A skin contains the following elements:
+
+- Resources to copy into each project (such as images used by the CSS)
+- A couple of CSS files, containing the visual styling
+- A Velocity template in `/META-INF/maven/site.vm` for an alternate HTML 
rendering of the site
+- Since Maven Site Plugin 3.5, an optional [skin 
descriptor](/doxia/doxia-sitetools/doxia-skin-model/index.html) in 
`/META-INF/maven/skin.xml` containing metadata about the skin
+
+The [`maven-archetype-site-skin` 
archetype](/archetypes/maven-archetype-site-skin/) creates a complete new skin 
project, including its dedicated `/META-INF/maven/site.vm`.
+
+A skin is built like any other JAR, with a `packaging` of `jar`. No additional 
plugins are needed. Put resources in the normal `src/main/resources` directory. 
Once the JAR is built and deployed, projects can use it.
+
+To construct your own CSS, copy the file 
[`maven-theme.css`](https://github.com/apache/maven-fluido-skin/tree/master/src/main/resources/css/maven-theme.css)
 from Maven Fluido Skin and modify it to suit your needs.
+
+The format of the Velocity template is out of scope for this page. For more 
information about how to write Velocity templates see the [Velocity User 
Guide](https://velocity.apache.org/engine/2.3/user-guide.html) and the 
[Velocity Template Language Reference 
Guide](https://velocity.apache.org/engine/2.3/vtl-reference.html). Velocity 2.3 
is used since Maven Site Plugin 4.0.0-M2; version 1.7 was used previously.
diff --git a/content/site.xml b/content/site.xml
index 3f49078e..d04f3327 100644
--- a/content/site.xml
+++ b/content/site.xml
@@ -96,6 +96,7 @@ under the License.
 
           <item name="Creating a site" href="/guides/mini/guide-site.html" 
collapse="true">
             <item name="Markup Formats" href="/doxia/references/index.html"/>
+            <item name="Multi-module Sites" 
href="/guides/mini/guide-multimodule-site.html"/>
             <item name="Snippet Macro" 
href="/guides/mini/guide-snippet-macro.html"/>
           </item>
           <item name="Archetypes" 
href="/guides/introduction/introduction-to-archetypes.html" collapse="true">

Reply via email to