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 & 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">