You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by sl...@apache.org on 2026/08/06 13:25:20 UTC
(maven-war-plugin) branch master updated (44bdb11 -> 4934505)
This is an automated email from the ASF dual-hosted git repository.
slachiewicz pushed a change to branch master
in repository https://gitbox.apache.org/repos/asf/maven-war-plugin.git
from 44bdb11 Verify the build against Maven 4 as well
new 5bbded1 Rename the site documents ahead of converting them
new 4934505 Port the site documentation from APT to Markdown
The 2 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
Summary of changes:
src/site/apt/examples/file-name-mapping.apt | 60 ----
.../including-excluding-files-from-war.apt.vm | 92 -----
.../apt/examples/rapid-testing-jetty6-plugin.apt | 75 ----
src/site/apt/examples/war-manifest-guide.apt.vm | 102 ------
src/site/apt/index.apt.vm | 98 -----
src/site/apt/overlays.apt.vm | 393 ---------------------
src/site/apt/usage.apt.vm | 229 ------------
.../examples/adding-filtering-webresources.md.vm} | 195 +++++-----
src/site/markdown/examples/file-name-mapping.md | 46 +++
.../including-excluding-files-from-war.md.vm | 72 ++++
.../examples/rapid-testing-jetty6-plugin.md | 62 ++++
.../markdown/examples/war-manifest-guide.md.vm | 87 +++++
src/site/markdown/index.md | 48 +++
src/site/markdown/overlays.md.vm | 342 ++++++++++++++++++
src/site/markdown/usage.md.vm | 206 +++++++++++
15 files changed, 948 insertions(+), 1159 deletions(-)
delete mode 100644 src/site/apt/examples/file-name-mapping.apt
delete mode 100644 src/site/apt/examples/including-excluding-files-from-war.apt.vm
delete mode 100644 src/site/apt/examples/rapid-testing-jetty6-plugin.apt
delete mode 100644 src/site/apt/examples/war-manifest-guide.apt.vm
delete mode 100644 src/site/apt/index.apt.vm
delete mode 100644 src/site/apt/overlays.apt.vm
delete mode 100644 src/site/apt/usage.apt.vm
rename src/site/{apt/examples/adding-filtering-webresources.apt.vm => markdown/examples/adding-filtering-webresources.md.vm} (65%)
create mode 100644 src/site/markdown/examples/file-name-mapping.md
create mode 100644 src/site/markdown/examples/including-excluding-files-from-war.md.vm
create mode 100644 src/site/markdown/examples/rapid-testing-jetty6-plugin.md
create mode 100644 src/site/markdown/examples/war-manifest-guide.md.vm
create mode 100644 src/site/markdown/index.md
create mode 100644 src/site/markdown/overlays.md.vm
create mode 100644 src/site/markdown/usage.md.vm
(maven-war-plugin) 02/02: Port the site documentation from APT to Markdown
Posted by sl...@apache.org.
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-war-plugin.git
commit 4934505c5bc98e4bf149e342efdc72dc009726d5
Author: Sylwester Lachiewicz <sl...@apache.org>
AuthorDate: Thu Aug 6 13:52:59 2026 +0200
Port the site documentation from APT to Markdown
9 page(s) converted with doxia-converter and then cleaned up by hand:
- <<<code>>> becomes backticks, <<bold>> becomes **bold**, {{{url}text}}
becomes [text](url)
- the ASF license header becomes a single block HTML comment
- a page whose only Velocity reference was ${project.name} is now a plain
.md with the title spelled out
- a page that keeps a reference stays a .vm. Velocity reads ## as a line
comment and would silently swallow every ATX heading below level one, so
subsections use setext underlines and anything deeper is wrapped in
#[[ ... ]]#
- references APT rendered literally are escaped, so they do not resolve
Verified by building the site before and after and comparing every
generated page: the visible text and the link targets are unchanged apart
from <b>/<i> becoming <strong>/<em> and quotes in prose picking up the
Markdown module's typographic substitution.
---
.../examples/adding-filtering-webresources.md.vm | 195 ++++++------
src/site/markdown/examples/file-name-mapping.md | 84 +++---
.../including-excluding-files-from-war.md.vm | 70 ++---
.../examples/rapid-testing-jetty6-plugin.md | 67 ++---
.../markdown/examples/war-manifest-guide.md.vm | 71 ++---
src/site/markdown/index.md | 122 +++-----
src/site/markdown/overlays.md.vm | 335 +++++++++------------
src/site/markdown/usage.md.vm | 145 ++++-----
8 files changed, 439 insertions(+), 650 deletions(-)
diff --git a/src/site/markdown/examples/adding-filtering-webresources.md.vm b/src/site/markdown/examples/adding-filtering-webresources.md.vm
index 56f97ba..b2bbda0 100644
--- a/src/site/markdown/examples/adding-filtering-webresources.md.vm
+++ b/src/site/markdown/examples/adding-filtering-webresources.md.vm
@@ -1,44 +1,32 @@
- ------
- Adding and Filtering External Web Resources
- ------
- Pete Marvin King
- Dennis Lundberg
- ------
- 2012-09-28
- ------
-
-~~ 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.
-
-~~ NOTE: For help with the syntax of this file, see:
-~~ http://maven.apache.org/doxia/references/apt-format.html
-
-Adding and Filtering External Web Resources
-
- The default resource directory for all Maven projects is <<<src/main/resources>>> which
- will end up in <<<target/classes>>> and in <<<WEB-INF/classes>>> in the WAR. The directory
- structure will be preserved in the process.
-
- The WAR Plugin is also capable of including resources not found in the default resource
- directory through the <<<webResources>>> parameter.
-
-*Adding web resources
-
-+-------+
+<!--
+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.
+-->
+
+# Adding and Filtering External Web Resources
+
+The default resource directory for all Maven projects is `src/main/resources` which will end up in `target/classes` and in `WEB-INF/classes` in the WAR. The directory structure will be preserved in the process.
+
+The WAR Plugin is also capable of including resources not found in the default resource directory through the `webResources` parameter.
+
+Adding web resources
+--------------------
+
+```xml
<project>
...
<build>
@@ -60,11 +48,11 @@ Adding and Filtering External Web Resources
</build>
...
</project>
-+-------+
+```
- Using our sample project in the {{{../usage.html}usage section}} with an added external resource, like this:
+Using our sample project in the [usage section](../usage.html) with an added external resource, like this:
-----------
+```
.
|-- pom.xml
|-- resource2
@@ -87,11 +75,11 @@ Adding and Filtering External Web Resources
|-- index.jsp
`-- jsp
`-- websource.jsp
-----------
+```
- would end up in the WAR as:
+would end up in the WAR as:
-----------
+```
documentedproject-1.0-SNAPSHOT.war
|-- META-INF
| |-- MANIFEST.MF
@@ -115,28 +103,25 @@ documentedproject-1.0-SNAPSHOT.war
|-- index.jsp
`-- jsp
`-- websource.jsp
-----------
-
- <<<external-resource2.jpg>>> and <<<image2>>> are copied to the root of the WAR, preserving the
- directory structure.
-
-*Configuring web Resources
+```
- <<<webResources>>> is a list of resources. All options of resource are supported.
+`external-resource2.jpg` and `image2` are copied to the root of the WAR, preserving the directory structure.
- A web resource
+Configuring web Resources
+-------------------------
- * can have includes/excludes
+`webResources` is a list of resources. All options of resource are supported.
- * can be filtered
+A web resource
- * is not limited to the default destination - the root of the WAR
+- can have includes/excludes
+- can be filtered
+- is not limited to the default destination - the root of the WAR
+#[[### Includes/Excludes]]#
-**Includes/Excludes
+To include all jpgs in the WAR we can add the following to our POM configuration from above:
- To include all jpgs in the WAR we can add the following to our POM configuration from above:
-
-+----------+
+```unknown
...
<configuration>
<webResources>
@@ -151,11 +136,11 @@ documentedproject-1.0-SNAPSHOT.war
</webResources>
</configuration>
...
-+----------+
+```
- To exclude the <<<image2>>> directory from the WAR add this:
+To exclude the `image2` directory from the WAR add this:
-+----------+
+```unknown
...
<configuration>
<webResources>
@@ -170,14 +155,13 @@ documentedproject-1.0-SNAPSHOT.war
</webResources>
</configuration>
...
-+----------+
+```
- Be careful when mixing includes and excludes, excludes will have a higher priority.
- Includes can not override excludes if a resource matches both.
+Be careful when mixing includes and excludes, excludes will have a higher priority. Includes can not override excludes if a resource matches both.
- Having this configuration will exclude all jpgs from the WAR:
+Having this configuration will exclude all jpgs from the WAR:
-+----------+
+```unknown
...
<configuration>
<webResources>
@@ -196,11 +180,11 @@ documentedproject-1.0-SNAPSHOT.war
</webResources>
</configuration>
...
-+----------+
+```
- Here's another example of how to specify include and exclude patterns:
+Here's another example of how to specify include and exclude patterns:
-+----------+
+```unknown
...
<configuration>
<webResources>
@@ -221,14 +205,13 @@ documentedproject-1.0-SNAPSHOT.war
</webResources>
</configuration>
...
-+----------+
+```
-**Filtering
+#[[### Filtering]]#
- Using our example above, we can also configure filters for our resources.
- We will add a hypothetical <<<configurations>>> directory to our project:
+Using our example above, we can also configure filters for our resources. We will add a hypothetical `configurations` directory to our project:
-----------
+```
.
|-- configurations
| |-- config.cfg
@@ -255,12 +238,11 @@ documentedproject-1.0-SNAPSHOT.war
|-- index.jsp
`-- jsp
`-- websource.jsp
-----------
+```
- To prevent corrupting your binary files when filtering is enabled, you can configure a list of file extensions that
- will not be filtered.
+To prevent corrupting your binary files when filtering is enabled, you can configure a list of file extensions that will not be filtered.
-+----------+
+```unknown
...
<configuration>
<!-- the default value is the filter list under build -->
@@ -289,25 +271,25 @@ documentedproject-1.0-SNAPSHOT.war
</webResources>
</configuration>
...
-+----------+
+```
-*** <<<config.prop>>>
+#[[#### `config.prop`]]#
-+----------+
+```properties
interpolated_property=some_config_value
-+----------+
+```
-*** <<<config.cfg>>>
+#[[#### `config.cfg`]]#
-+----------+
+```xml
<another_ioc_container>
<configuration>${interpolated_property}</configuration>
</another_ioc_container>
-+----------+
+```
- The resulting WAR would be:
+The resulting WAR would be:
-----------
+```
documentedproject-1.0-SNAPSHOT.war
|-- META-INF
| |-- MANIFEST.MF
@@ -332,30 +314,23 @@ documentedproject-1.0-SNAPSHOT.war
|-- index.jsp
`-- jsp
`-- websource.jsp
-----------
+```
- and the content of <<<config.cfg>>> would be:
+and the content of `config.cfg` would be:
-+----------+
+```xml
<another_ioc_container>
<configuration>some_config_value</configuration>
</another_ioc_container>
-+----------+
-
- <<Note:>> In versions 2.2 and earlier of this plugin the platform encoding was
- used when filtering resources. Depending on what that encoding was you could
- end up with scrambled characters after filtering. Starting with version 2.3
- this plugin respects the property <<<project.build.sourceEncoding>>> when
- filtering resources. One notable exception to this is that <<<.xml>>> files
- are filtered using the encoding specified inside the xml-file itself.
+```
+**Note:** In versions 2.2 and earlier of this plugin the platform encoding was used when filtering resources. Depending on what that encoding was you could end up with scrambled characters after filtering. Starting with version 2.3 this plugin respects the property `project.build.sourceEncoding` when filtering resources. One notable exception to this is that `.xml` files are filtered using the encoding specified inside the xml-file itself.
-**Overriding the default destination directory
+#[[### Overriding the default destination directory]]#
- By default web resources are copied to the root of the WAR, as shown in the previous example.
- To override the default destination directory, specify the target path.
+By default web resources are copied to the root of the WAR, as shown in the previous example. To override the default destination directory, specify the target path.
-+----------+
+```unknown
...
<configuration>
<webResources>
@@ -375,11 +350,11 @@ documentedproject-1.0-SNAPSHOT.war
</webResources>
</configuration>
...
-+----------+
+```
- Using the sample project the resulting WAR would look like this:
+Using the sample project the resulting WAR would look like this:
-----------
+```
documentedproject-1.0-SNAPSHOT.war
|-- META-INF
| |-- MANIFEST.MF
@@ -404,4 +379,4 @@ documentedproject-1.0-SNAPSHOT.war
|-- index.jsp
`-- jsp
`-- websource.jsp
-----------
+```
diff --git a/src/site/markdown/examples/file-name-mapping.md b/src/site/markdown/examples/file-name-mapping.md
index 0e96b41..699cdf5 100644
--- a/src/site/markdown/examples/file-name-mapping.md
+++ b/src/site/markdown/examples/file-name-mapping.md
@@ -1,60 +1,46 @@
- ------
- Using File Name Mapping
- ------
- Stephane Nicoll
- Dennis Lundberg
- ------
- 2010-05-24
-
-~~ 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.
-
-~~ NOTE: For help with the syntax of this file, see:
-~~ http://maven.apache.org/doxia/references/apt-format.html
-
-Using File Name Mapping
-
- It might be necessary to customize the file name of libraries and TLDs. By default, those resources are stored
- using the following pattern:
-
-+-----
+<!--
+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.
+-->
+
+# Using File Name Mapping
+
+It might be necessary to customize the file name of libraries and TLDs. By default, those resources are stored using the following pattern:
+
+```unknown
@{artifactId}@-@{version}@.@{extension}@
-+-----
+```
- If the artifact has a classifier the default pattern is of course:
+If the artifact has a classifier the default pattern is of course:
-+-----
+```unknown
@{artifactId}@-@{version}@-@{classifier}@.@{extension}@
-+-----
+```
- The <<<outputFileNameMapping>>> parameter allows you to give a custom pattern. Each token defined in the
- pattern will be replaced with a value from the current artifact. You can use any property of Artifact and
- ArtifactHandler as a token. There is also a special token named <<<dashClassifier?>>> that can be used, since 2.1.
- It will add the string "-yourclassifier" if and only if the artifact has a classifier.
+The `outputFileNameMapping` parameter allows you to give a custom pattern. Each token defined in the pattern will be replaced with a value from the current artifact. You can use any property of Artifact and ArtifactHandler as a token. There is also a special token named `dashClassifier?` that can be used, since 2.1. It will add the string "-yourclassifier" if and only if the artifact has a classifier.
- For instance, to store the libraries and TLDs without version numbers or classifiers, use the following pattern:
+For instance, to store the libraries and TLDs without version numbers or classifiers, use the following pattern:
-+-----
+```unknown
@{artifactId}@.@{extension}@
-+-----
+```
- To store the libraries and TLDs without version numbers but with classifiers
- (if they exist), use the following pattern:
+To store the libraries and TLDs without version numbers but with classifiers (if they exist), use the following pattern:
-+-----
+```unknown
@{artifactId}@@{dashClassifier?}@.@{extension}@
-+-----
+```
diff --git a/src/site/markdown/examples/including-excluding-files-from-war.md.vm b/src/site/markdown/examples/including-excluding-files-from-war.md.vm
index f183fac..55b9f58 100644
--- a/src/site/markdown/examples/including-excluding-files-from-war.md.vm
+++ b/src/site/markdown/examples/including-excluding-files-from-war.md.vm
@@ -1,43 +1,29 @@
- ------
- Including and Excluding Files From the WAR
- ------
- Dennis Lundberg
- ------
- 2011-11-21
- ------
+<!--
+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
-~~ 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.
+http://www.apache.org/licenses/LICENSE-2.0
-~~ NOTE: For help with the syntax of this file, see:
-~~ http://maven.apache.org/doxia/references/apt-format.html
+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.
+-->
-Including and Excluding Files From the WAR
+# Including and Excluding Files From the WAR
+It is possible to include or exclude certain files from the WAR file, by using the `<packagingIncludes>` and `<packagingExcludes>` configuration parameters. They each take a comma-separated list of Ant file set patterns. You can use wildcards such as `**` to indicate multiple directories and `*` to indicate an optional part of a file or directory name.
- It is possible to include or exclude certain files from the WAR file, by using
- the <<<\<packagingIncludes\>>>> and <<<\<packagingExcludes\>>>> configuration
- parameters. They each take a comma-separated list of Ant file set patterns.
- You can use wildcards such as <<<**>>> to indicate multiple directories and
- <<<*>>> to indicate an optional part of a file or directory name.
-
- Here is an example where we exclude all JAR files from <<<WEB-INF/lib>>>:
+Here is an example where we exclude all JAR files from `WEB-INF/lib`:
-+-----------------+
+```xml
<project>
...
<build>
@@ -53,16 +39,11 @@ Including and Excluding Files From the WAR
</build>
...
</project>
-+-----------------+
+```
- Sometimes even such wildcards are not enough. In these cases you can use
- regular expressions with the <<<%regex[]>>> syntax. Here is a real life use
- case in which this is used. In this example we want to exclude any
- commons-logging and log4j JARs, but we do not want to exclude the
- log4j-over-slf4j JAR. So we want to exclude <<<log4j-\<version\>.jar>>> but
- keep the <<<log4j-over-slf4j-\<version\>.jar>>>.
+Sometimes even such wildcards are not enough. In these cases you can use regular expressions with the `%regex[]` syntax. Here is a real life use case in which this is used. In this example we want to exclude any commons-logging and log4j JARs, but we do not want to exclude the log4j-over-slf4j JAR. So we want to exclude `log4j-<version>.jar` but keep the `log4j-over-slf4j-<version>.jar`.
-+-----------------+
+```xml
<project>
...
<build>
@@ -86,7 +67,6 @@ Including and Excluding Files From the WAR
</build>
...
</project>
-+-----------------+
+```
- If you have more real life examples of using regular expressions, we'd like to
- know about them.
+If you have more real life examples of using regular expressions, we'd like to know about them.
diff --git a/src/site/markdown/examples/rapid-testing-jetty6-plugin.md b/src/site/markdown/examples/rapid-testing-jetty6-plugin.md
index a500a93..bd0b839 100644
--- a/src/site/markdown/examples/rapid-testing-jetty6-plugin.md
+++ b/src/site/markdown/examples/rapid-testing-jetty6-plugin.md
@@ -1,44 +1,31 @@
- ------
- Rapid Testing Using the Jetty Plugin
- ------
- Pete Marvin King
- ------
- 2008-08-03
- ------
+<!--
+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
-~~ 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.
+http://www.apache.org/licenses/LICENSE-2.0
-~~ NOTE: For help with the syntax of this file, see:
-~~ http://maven.apache.org/doxia/references/apt-format.html
+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.
+-->
-Rapid Testing Using the Jetty Plugin
+# Rapid Testing Using the Jetty Plugin
- Normally, testing a web application involves compiling Java sources, creating a WAR and
- deploying it to a web container.
+Normally, testing a web application involves compiling Java sources, creating a WAR and deploying it to a web container.
- Using the Jetty Plugin enables you to quickly test your web application by skipping
- the last two steps. By default the Jetty Plugin scans <<<target/classes>>> for
- any changes in your Java sources and <<<src/main/webapp>>> for changes to your web sources.
- The Jetty Plugin will automatically reload the modified classes and web sources.
+Using the Jetty Plugin enables you to quickly test your web application by skipping the last two steps. By default the Jetty Plugin scans `target/classes` for any changes in your Java sources and `src/main/webapp` for changes to your web sources. The Jetty Plugin will automatically reload the modified classes and web sources.
- To use the Jetty Plugin just add the following in your <<<pom.xml>>>:
+To use the Jetty Plugin just add the following in your `pom.xml`:
-+-----------------+
+```xml
<project>
...
<build>
@@ -62,14 +49,14 @@ Rapid Testing Using the Jetty Plugin
</build>
...
</project>
-+-----------------+
+```
- Then start Jetty:
+Then start Jetty:
------------------
+```
mvn jetty:run
------------------
+```
- The command will block with Jetty listening on port 8080.
+The command will block with Jetty listening on port 8080.
- Check the {{{http://docs.codehaus.org/display/JETTY/Maven+Jetty+Plugin}Jetty Plugin documentation}} for more details.
+Check the [Jetty Plugin documentation](http://docs.codehaus.org/display/JETTY/Maven+Jetty+Plugin) for more details.
diff --git a/src/site/markdown/examples/war-manifest-guide.md.vm b/src/site/markdown/examples/war-manifest-guide.md.vm
index a3aadb3..eee6f36 100644
--- a/src/site/markdown/examples/war-manifest-guide.md.vm
+++ b/src/site/markdown/examples/war-manifest-guide.md.vm
@@ -1,45 +1,32 @@
- ------
- WAR Manifest Customization
- ------
- Pete Marvin King
- ------
- 2008-08-03
- ------
+<!--
+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
-~~ 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.
+http://www.apache.org/licenses/LICENSE-2.0
-~~ NOTE: For help with the syntax of this file, see:
-~~ http://maven.apache.org/doxia/references/apt-format.html
+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.
+-->
-WAR Manifest Customization
+# WAR Manifest Customization
- The manifest can be customized by configuring the WAR Plugin's archiver. For full information on the different
- configuration options available check the documentation for
- {{{http://maven.apache.org/shared/maven-archiver/index.html}Maven Archiver}}.
+The manifest can be customized by configuring the WAR Plugin's archiver. For full information on the different configuration options available check the documentation for [Maven Archiver](http://maven.apache.org/shared/maven-archiver/index.html).
+Generating a manifest classpath
+-------------------------------
-*Generating a manifest classpath
+Generating a manifest classpath for a WAR is similar to for a JAR, but there are a couple of slight differences since you normally don't want a JAR in both the manifest classpath and the `WEB-INF/lib` directory. Customize the WAR Plugin's archiver:
- Generating a manifest classpath for a WAR is similar to for a JAR, but there are a couple of slight differences since
- you normally don't want a JAR in both the manifest classpath and the <<<WEB-INF/lib>>> directory. Customize the WAR
- Plugin's archiver:
-
-+--------------------+
+```xml
<project>
...
<build>
@@ -61,14 +48,13 @@ WAR Manifest Customization
</build>
...
</project>
-+--------------------+
+```
- Now, you can control which dependencies are included in <<<WEB-INF/lib>>> and in the manifest classpath by following
- these examples. Maven will follow the transitive dependency tree until it gets to artifacts scoped as "provided".
+Now, you can control which dependencies are included in `WEB-INF/lib` and in the manifest classpath by following these examples. Maven will follow the transitive dependency tree until it gets to artifacts scoped as "provided".
- <<Note:>> No way is shown how to include a dependency in <<<WEB-INF/lib>>> but not in the manifest classpath.
+**Note:** No way is shown how to include a dependency in `WEB-INF/lib` but not in the manifest classpath.
-+--------------------+
+```xml
<project>
...
<dependencies>
@@ -96,7 +82,6 @@ WAR Manifest Customization
</dependencies>
...
</project>
-+--------------------+
+```
- Check the {{{http://maven.apache.org/guides/mini/guide-manifest.html}Guide to Working with Manifests}} for more
- examples.
+Check the [Guide to Working with Manifests](http://maven.apache.org/guides/mini/guide-manifest.html) for more examples.
diff --git a/src/site/markdown/index.md b/src/site/markdown/index.md
index 8ebdac0..558e2e3 100644
--- a/src/site/markdown/index.md
+++ b/src/site/markdown/index.md
@@ -1,98 +1,48 @@
- ------
- Introduction
- ------
- Pete Marvin King
- ------
- 2013-07-22
- ------
+<!--
+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
-~~ 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.
+http://www.apache.org/licenses/LICENSE-2.0
-~~ NOTE: For help with the syntax of this file, see:
-~~ http://maven.apache.org/doxia/references/apt-format.html
+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.
+-->
-${project.name}
+# Apache Maven WAR Plugin
+The WAR Plugin is responsible for collecting all artifact dependencies, classes and resources of the web application and packaging them into a web application archive.
- The WAR Plugin is responsible for collecting all artifact dependencies, classes
- and resources of the web application and packaging them into a web application
- archive.
+## Goals Overview
-* Goals Overview
+- [war:war](./war-mojo.html) is the default goal invoked during the `package` phase for projects with a packaging type of `war`. It builds a WAR file.
+- [war:exploded](./exploded-mojo.html) is generally used to speed up testing during the developement phase by creating an exploded webapp in a specified directory.
+- [war:inplace](./inplace-mojo.html) another variation of `war:explode` where the webapp is instead generated in the web application source directory, which is `src/main/webapp` by default.
+## Usage
- * {{{./war-mojo.html}war:war}} is the default goal invoked during the
- <<<package>>> phase for projects with a packaging type of <<<war>>>.
- It builds a WAR file.
+General instructions on how to use the WAR Plugin can be found on the [usage page](./usage.html). Some more specific use cases are described in the examples given below. To share common resources across multiple web applications, see the documentation about using [overlays](./overlays.html).
- * {{{./exploded-mojo.html}war:exploded}} is generally used to speed up
- testing during the developement phase by creating an exploded webapp
- in a specified directory.
+If you still have questions regarding the plugin's usage, please have a look at the [FAQ](./faq.html) and feel free to contact the [user mailing list](./mailing-lists.html). The posts to the mailing list are archived and could already contain the answer to your question as part of an older thread. Hence, it is also worth browsing/searching the [mail archive](./mailing-lists.html).
- * {{{./inplace-mojo.html}war:inplace}} another variation of <<<war:explode>>>
- where the webapp is instead generated in the web application source directory,
- which is <<<src/main/webapp>>> by default.
+If you think the plugin is missing a feature or has a defect, file a feature request or bug report in the [issue tracker](./issue-management.html). When creating a new issue, please provide a comprehensive description of your concern. Especially for fixing bugs it is crucial that the developers can reproduce your problem. For this reason, entire debug logs, POMs or most preferably little demo projects attached to the issue are very much appreciated. Of course, patches are welcome, too. C [...]
- []
+## Examples
-* Usage
+To provide you with better understanding on some usages of the Maven WAR Plugin, you can look into the following examples:
- General instructions on how to use the WAR Plugin can be found on the
- {{{./usage.html}usage page}}. Some more specific use cases are described in the
- examples given below. To share common resources across multiple web applications,
- see the documentation about using {{{./overlays.html}overlays}}.
+- [Adding and Filtering External Web Resources](./examples/adding-filtering-webresources.html)
+- [WAR Manifest Customization](./examples/war-manifest-guide.html)
+- [Rapid Testing the Jetty Plugin](./examples/rapid-testing-jetty6-plugin.html)
+- [Creating Skinny WARs](https://maven.apache.org/plugins/maven-ear-plugin/examples/skinny-wars.html)
+- [Including and Excluding Files From the WAR](./examples/including-excluding-files-from-war.html)
+- [Using File Name Mapping](./examples/file-name-mapping.html)
+## Related links
- If you still have questions regarding the plugin's usage, please have a look at the
- {{{./faq.html}FAQ}} and feel free to contact the {{{./mailing-lists.html}user mailing list}}.
- The posts to the mailing list are archived and could already contain the answer to your
- question as part of an older thread. Hence, it is also worth browsing/searching
- the {{{./mailing-lists.html}mail archive}}.
-
- If you think the plugin is missing a feature or has a defect, file a
- feature request or bug report in the {{{./issue-management.html}issue tracker}}.
- When creating a new issue, please provide a comprehensive description of your
- concern. Especially for fixing bugs it is crucial that the developers can
- reproduce your problem. For this reason, entire debug logs, POMs or most
- preferably little demo projects attached to the issue are very much appreciated.
- Of course, patches are welcome, too. Contributors can check out the project from
- our {{{./scm.html}source repository}} and will find supplementary
- information in the
- {{{/guides/development/guide-helping.html}guide to helping with Maven}}.
-
-* Examples
-
- To provide you with better understanding on some usages of the Maven WAR Plugin,
- you can look into the following examples:
-
- * {{{./examples/adding-filtering-webresources.html}Adding and Filtering External Web Resources}}
-
- * {{{./examples/war-manifest-guide.html}WAR Manifest Customization}}
-
- * {{{./examples/rapid-testing-jetty6-plugin.html}Rapid Testing the Jetty Plugin}}
-
- * {{{https://maven.apache.org/plugins/maven-ear-plugin/examples/skinny-wars.html}Creating Skinny WARs}}
-
- * {{{./examples/including-excluding-files-from-war.html}Including and Excluding Files From the WAR}}
-
- * {{{./examples/file-name-mapping.html}Using File Name Mapping}}
-
- []
-
-* Related links
-
- * {{{/guides/mini/guide-archive-configuration.html}Exclusion of Maven Descriptors}}
-
- []
+- [Exclusion of Maven Descriptors](/guides/mini/guide-archive-configuration.html)
diff --git a/src/site/markdown/overlays.md.vm b/src/site/markdown/overlays.md.vm
index 741a80e..3743b4d 100644
--- a/src/site/markdown/overlays.md.vm
+++ b/src/site/markdown/overlays.md.vm
@@ -1,44 +1,32 @@
- ------
- Overlays
- ------
- Pete Marvin King
- Stephane Nicoll
- Dennis Lundberg
- ------
- 2010-08-14
-
-~~ 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.
-
-~~ NOTE: For help with the syntax of this file, see:
-~~ http://maven.apache.org/doxia/references/apt-format.html
-
-Overlays
-
- Overlays are used to share common resources across multiple web applications.
- The dependencies of a WAR project are collected in <<<WEB-INF/lib>>>, except for WAR
- artifacts which are overlayed on the WAR project itself.
-
-
-* Overlays at a glance
-
- To demonstrate, given this structure for the project <<<documentedproject>>>:
-
------------------
+<!--
+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.
+-->
+
+# Overlays
+
+Overlays are used to share common resources across multiple web applications. The dependencies of a WAR project are collected in `WEB-INF/lib`, except for WAR artifacts which are overlayed on the WAR project itself.
+
+Overlays at a glance
+--------------------
+
+To demonstrate, given this structure for the project `documentedproject`:
+
+```
|-- pom.xml
`-- src
`-- main
@@ -57,12 +45,11 @@ Overlays
|-- index.jsp
`-- jsp
`-- websource.jsp
------------------
+```
- The project depends on another WAR artifact, <<<documentedprojectdependency-1.0-SNAPSHOT.war>>>,
- which is declared as a dependency in the project's <<<pom.xml>>>:
+The project depends on another WAR artifact, `documentedprojectdependency-1.0-SNAPSHOT.war`, which is declared as a dependency in the project's `pom.xml`:
-+-----------------+
+```xml
<project>
...
<dependencies>
@@ -77,11 +64,11 @@ Overlays
</dependencies>
...
</project>
-+-----------------+
+```
- The structure for the <<<documentedprojectdependency>>> WAR file looks like this:
+The structure for the `documentedprojectdependency` WAR file looks like this:
------------------
+```
documentedprojectdependency-1.0-SNAPSHOT.war
|-- META-INF
| |-- MANIFEST.MF
@@ -100,11 +87,11 @@ documentedprojectdependency-1.0-SNAPSHOT.war
| | `-- sampleimage-dependency.jpg
| `-- web.xml
`-- index-dependency.jsp
------------------
+```
- The resulting WAR would end up like this:
+The resulting WAR would end up like this:
------------------
+```
|-- META-INF
| |-- MANIFEST.MF
| `-- maven
@@ -127,57 +114,36 @@ documentedprojectdependency-1.0-SNAPSHOT.war
|-- index.jsp
`-- jsp
`-- websource.jsp
------------------
-
- The <<<web.xml>>> file above comes from <<<documentedproject>>>.
-
-
-* Overlay types
-
- The WAR Plugin handles both <<war>> and <<zip>> artifacts as overlays. However, for backward compatibility reasons, zip
- overlays are handled only if they are defined explicitly in the plugin's configuration.
-
-
-* Configuring Overlays
-
- In previous versions of the WAR Plugin, no configuration was necessary. This is still the
- case if you are happy with the default settings. However, if you need more control, read on!
-
- The <<<\<{overlay}\>>>> element can have the following child elements:
-
- * <<id>> - the id of the overlay. If none is provided, the WAR Plugin will
- generate one.
-
- * <<groupId>> - the groupId of the overlay artifact you want to configure.
-
- * <<artifactId>> - the artifactId of the overlay artifact you want to
- configure.
+```
- * <<type>> - the type of the overlay artifact you want to
- configure. Default value is: <<<war>>>.
+The `web.xml` file above comes from `documentedproject`.
- * <<classifier>> - the classifier of the overlay artifact you want to
- configure if multiple artifacts matches the groupId/artifactId.
+Overlay types
+-------------
- * <<includes>> - the files to include. By default, all files are included.
+The WAR Plugin handles both **war** and **zip** artifacts as overlays. However, for backward compatibility reasons, zip overlays are handled only if they are defined explicitly in the plugin's configuration.
- * <<excludes>> - the files to exclude. By default, the <<<META-INF/MANIFEST.MF>>> file
- is excluded.
+Configuring Overlays
+--------------------
- * <<targetPath>> - the target relative path in the webapp structure, which is only
- available for overlays of type <<<war>>>. By default, the content of the overlay is added in the root
- structure of the webapp.
+In previous versions of the WAR Plugin, no configuration was necessary. This is still the case if you are happy with the default settings. However, if you need more control, read on\!
- * <<skip>> - set to <<<true>>> to skip this overlay. Default value is: <<<false>>>.
+The `<overlay>` element can have the following child elements:
- * <<filtered>> - whether to apply filtering to this overlay. Default value is <<<false>>>.
+- **id** - the id of the overlay. If none is provided, the WAR Plugin will generate one.
+- **groupId** - the groupId of the overlay artifact you want to configure.
+- **artifactId** - the artifactId of the overlay artifact you want to configure.
+- **type** - the type of the overlay artifact you want to configure. Default value is: `war`.
+- **classifier** - the classifier of the overlay artifact you want to configure if multiple artifacts matches the groupId/artifactId.
+- **includes** - the files to include. By default, all files are included.
+- **excludes** - the files to exclude. By default, the `META-INF/MANIFEST.MF` file is excluded.
+- **targetPath** - the target relative path in the webapp structure, which is only available for overlays of type `war`. By default, the content of the overlay is added in the root structure of the webapp.
+- **skip** - set to `true` to skip this overlay. Default value is: `false`.
+- **filtered** - whether to apply filtering to this overlay. Default value is `false`.
- []
+For instance, to exclude the `sampleimage-dependency.jpg` of our `documentedprojectdependency` `war` overlay above:
- For instance, to exclude the <<<sampleimage-dependency.jpg>>> of our
- <<<documentedprojectdependency>>> <<<war>>> overlay above:
-
-+-----------------+
+```xml
<project>
...
<build>
@@ -202,29 +168,18 @@ documentedprojectdependency-1.0-SNAPSHOT.war
</build>
...
</project>
-+-----------------+
-
-
-* Overlays packaging
+```
- Overlays are applied with a first-win strategy (hence if a file has been copied by
- one overlay, it won't be copied by another). Overlays are applied in the order in which
- they are defined in the <<<\<overlays\>>>> configuration. If no configuration is provided,
- the order in which the dependencies are defined in the POM is used (warning: this is not
- deterministic, especially if you have overlays as transitive dependencies). In case of
- a mixed situation (e.g. configured overlays and non-configured overlays), non-configured
- overlays are applied after configured overlays.
+Overlays packaging
+------------------
- By default, the source of the project (a.k.a the current build) is added first (e.g.
- before any overlay is applied). The current build is defined as a special overlay
- with no <<<groupId>>>, <<<artifactId>>>. If overlays need to be applied first, simply
- configure the current build after those overlays.
+Overlays are applied with a first-win strategy (hence if a file has been copied by one overlay, it won't be copied by another). Overlays are applied in the order in which they are defined in the `<overlays>` configuration. If no configuration is provided, the order in which the dependencies are defined in the POM is used (warning: this is not deterministic, especially if you have overlays as transitive dependencies). In case of a mixed situation (e.g. configured overlays and non-configur [...]
- For instance, if <<<my-webapp>>> from the <<<com.example.projects>>> group is a dependency
- of the project and needs to be applied before the project's own source, do as follows:
+By default, the source of the project (a.k.a the current build) is added first (e.g. before any overlay is applied). The current build is defined as a special overlay with no `groupId`, `artifactId`. If overlays need to be applied first, simply configure the current build after those overlays.
+For instance, if `my-webapp` from the `com.example.projects` group is a dependency of the project and needs to be applied before the project's own source, do as follows:
-+-----------------+
+```xml
<project>
...
<build>
@@ -249,17 +204,13 @@ documentedprojectdependency-1.0-SNAPSHOT.war
</build>
...
</project>
-+-----------------+
+```
- <<Note:>> In the scenario above, any other WAR dependency will be applied after the current build
- since they have not been configured in the <<<\<overlays\>>>> element.
+**Note:** In the scenario above, any other WAR dependency will be applied after the current build since they have not been configured in the `<overlays>` element.
- To perform an even more fine grained overwriting policy, overlays can be packaged multiple times
- with different includes/excludes. For instance if the <<<index.jsp>>> file of the
- overlay <<<my-webapp>>> <<must>> be set in the webapp but other files can be controlled the
- regular way, define two overlay configurations for <<<my-webapp>>>:
+To perform an even more fine grained overwriting policy, overlays can be packaged multiple times with different includes/excludes. For instance if the `index.jsp` file of the overlay `my-webapp` **must** be set in the webapp but other files can be controlled the regular way, define two overlay configurations for `my-webapp`:
-+-----------------+
+```xml
<project>
...
<build>
@@ -296,79 +247,77 @@ documentedprojectdependency-1.0-SNAPSHOT.war
</build>
...
</project>
-+-----------------+
-
-
-* Overlay global settings
-
- The following settings can be specified globally and modify the way all overlays are applied.
-
- * <<dependentWarIncludes>> - sets the default includes to apply to all overlays. Any overlay that
- has no specific <<<includes>>> element will inherit this setting by default.
-
-+-----------------+
-<project>
- ...
- <plugins>
- <plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-war-plugin</artifactId>
- <version>${project.version}</version>
- <configuration>
- <dependentWarIncludes>**/IncludeME,**/images</dependentWarIncludes>
- </configuration>
- </plugin>
- </plugins>
- ...
-</project>
-+-----------------+
-
- * <<dependentWarExcludes>> - sets the default excludes to apply to all overlays. Any overlay that
- has no specific <<<excludes>>> element will inherit this setting by default.
-
-+-----------------+
-<project>
- ...
- <plugins>
- <plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-war-plugin</artifactId>
- <version>${project.version}</version>
- <configuration>
- <dependentWarExcludes>WEB-INF/web.xml,index.*</dependentWarExcludes>
- </configuration>
- </plugin>
- </plugins>
- ...
-</project>
-+-----------------+
-
- * <<workDirectory>> - sets the directory where overlays will be temporarily extracted.
-
-+-----------------+
-<project>
- ...
- <plugins>
- <plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-war-plugin</artifactId>
- <version>${project.version}</version>
- <configuration>
- <!-- default value is target/war/work -->
- <workDirectory>/tmp/extract_here</workDirectory>
- </configuration>
- </plugin>
- </plugins>
- ...
-</project>
-+-----------------+
-
-* Zip dependencies with overlays
-
- To use a <<zip>> dependency as an overlay you have to configure it explicitly in the plugin's configuration. For
- instance to inject the content of a zip overlay in the <<<scripts>>> directory of the webapp, do as follows:
-
-+-----------------+
+```
+
+Overlay global settings
+-----------------------
+
+The following settings can be specified globally and modify the way all overlays are applied.
+
+- **dependentWarIncludes** - sets the default includes to apply to all overlays. Any overlay that has no specific `includes` element will inherit this setting by default.
+
+ ```xml
+ <project>
+ ...
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-war-plugin</artifactId>
+ <version>${project.version}</version>
+ <configuration>
+ <dependentWarIncludes>**/IncludeME,**/images</dependentWarIncludes>
+ </configuration>
+ </plugin>
+ </plugins>
+ ...
+ </project>
+ ```
+
+- **dependentWarExcludes** - sets the default excludes to apply to all overlays. Any overlay that has no specific `excludes` element will inherit this setting by default.
+
+ ```xml
+ <project>
+ ...
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-war-plugin</artifactId>
+ <version>${project.version}</version>
+ <configuration>
+ <dependentWarExcludes>WEB-INF/web.xml,index.*</dependentWarExcludes>
+ </configuration>
+ </plugin>
+ </plugins>
+ ...
+ </project>
+ ```
+
+- **workDirectory** - sets the directory where overlays will be temporarily extracted.
+
+ ```xml
+ <project>
+ ...
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-war-plugin</artifactId>
+ <version>${project.version}</version>
+ <configuration>
+ <!-- default value is target/war/work -->
+ <workDirectory>/tmp/extract_here</workDirectory>
+ </configuration>
+ </plugin>
+ </plugins>
+ ...
+ </project>
+ ```
+
+Zip dependencies with overlays
+------------------------------
+
+To use a **zip** dependency as an overlay you have to configure it explicitly in the plugin's configuration. For instance to inject the content of a zip overlay in the `scripts` directory of the webapp, do as follows:
+
+```xml
<project>
...
<plugins>
@@ -390,4 +339,4 @@ documentedprojectdependency-1.0-SNAPSHOT.war
</plugins>
...
</project>
-+-----------------+
+```
diff --git a/src/site/markdown/usage.md.vm b/src/site/markdown/usage.md.vm
index 3e3b1cc..cf7aeac 100644
--- a/src/site/markdown/usage.md.vm
+++ b/src/site/markdown/usage.md.vm
@@ -1,61 +1,43 @@
- ------
- Usage
- ------
- Pete Marvin King
- ------
- 2010-08-15
- ------
+<!--
+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
-~~ 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.
+http://www.apache.org/licenses/LICENSE-2.0
-~~ NOTE: For help with the syntax of this file, see:
-~~ http://maven.apache.org/doxia/references/apt-format.html
+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.
+-->
-Usage
+# Usage
- There are 4 ways to use the WAR Plugin:
+There are 4 ways to use the WAR Plugin:
- * using the <<<package>>> phase with the project package type as <<<war>>>
+- using the `package` phase with the project package type as `war`
+- invocation of the `war:war` goal
+- invocation of the `war:exploded` goal
+- invocation of the `war:inplace` goal
- * invocation of the <<<war:war>>> goal
+**Note:** When using the `war:` goals it is assumed that the `compile` phase is already done. The WAR Plugin is not responsible for compiling the java sources or copying the resources.
- * invocation of the <<<war:exploded>>> goal
+To handle archiving this version of Maven WAR Plugin uses [Maven Archiver](http://maven.apache.org/shared/maven-archiver/index.html) ${mavenArchiverVersion}.
- * invocation of the <<<war:inplace>>> goal
+To handle filtering this version of Maven WAR Plugin uses [Maven Filtering](http://maven.apache.org/shared/maven-filtering/index.html) ${mavenFilteringVersion}.
- []
+Using the `package` phase with the project package type as war / invocation of the `war:war` goal
+-------------------------------------------------------------------------------------------------
- <<Note:>> When using the <<<war:>>> goals it is assumed that the <<<compile>>> phase is already done.
- The WAR Plugin is not responsible for compiling the java sources or copying the resources.
+This is the normal way of using the WAR Plugin. To illustrate, here's the `pom.xml` for our project:
- To handle archiving this version of Maven WAR Plugin uses
- {{{http://maven.apache.org/shared/maven-archiver/index.html}Maven Archiver}} ${mavenArchiverVersion}.
-
- To handle filtering this version of Maven WAR Plugin uses
- {{{http://maven.apache.org/shared/maven-filtering/index.html}Maven Filtering}} ${mavenFilteringVersion}.
-
-
-*Using the <<<package>>> phase with the project package type as war / invocation of the <<<war:war>>> goal
-
- This is the normal way of using the WAR Plugin.
- To illustrate, here's the <<<pom.xml>>> for our project:
-
-+----------+
+```xml
<project>
...
<groupId>com.example.projects</groupId>
@@ -66,11 +48,11 @@ Usage
<url>http://example.com</url>
...
</project>
-+----------+
+```
- The project's structure looks like this:
+The project's structure looks like this:
-----------
+```
|-- pom.xml
`-- src
`-- main
@@ -88,23 +70,23 @@ Usage
|-- index.jsp
`-- jsp
`-- websource.jsp
-----------
+```
- Invoking
+Invoking
-----------
+```
mvn package
-----------
+```
- or
+or
-----------
+```
mvn compile war:war
-----------
+```
- will generate the WAR file <<<target/documentedproject-1.0-SNAPSHOT.war>>>. Here are the contents of that WAR file:
+will generate the WAR file `target/documentedproject-1.0-SNAPSHOT.war`. Here are the contents of that WAR file:
-----------
+```
documentedproject-1.0-SNAPSHOT.war
|-- META-INF
| |-- MANIFEST.MF
@@ -125,22 +107,20 @@ documentedproject-1.0-SNAPSHOT.war
|-- index.jsp
`-- jsp
`-- websource.jsp
-----------
+```
-*Invocation of <<<war:exploded>>> goal
+Invocation of `war:exploded` goal
+---------------------------------
- To speed up testing during the developement phase, <<<war:explode>>> can be used to generate the WAR in exploded
- form.
- Use the same project as above and invoke:
+To speed up testing during the developement phase, `war:explode` can be used to generate the WAR in exploded form. Use the same project as above and invoke:
-----------
+```
mvn compile war:exploded
-----------
+```
- This will generate an exploded version of the WAR in <<<target/documentedproject-1.0-SNAPSHOT>>>.
- The contents of that directory looks like this:
+This will generate an exploded version of the WAR in `target/documentedproject-1.0-SNAPSHOT`. The contents of that directory looks like this:
-----------
+```
documentedproject-1.0-SNAPSHOT
|-- META-INF
|-- WEB-INF
@@ -155,13 +135,11 @@ mvn compile war:exploded
|-- index.jsp
`-- jsp
`-- websource.jsp
-----------
+```
- The default directory for the exploded WAR is <<<target/\<finalName\>>>>. The <<<finalName>>> is usually in the form
- of <<<\<artifactId\>-\<version\>>>>.
- This default directory can be overridden by specifying the <<<webappDirectory>>> parameter.
+The default directory for the exploded WAR is `target/<finalName>`. The `finalName` is usually in the form of `<artifactId>-<version>`. This default directory can be overridden by specifying the `webappDirectory` parameter.
-+-------+
+```xml
<project>
...
<build>
@@ -178,21 +156,20 @@ mvn compile war:exploded
</build>
...
</project>
-+-------+
+```
-*Invocation of <<<war:inplace>>> goal
+Invocation of `war:inplace` goal
+--------------------------------
- Another variation of <<<war:exploded>>> is <<<war:inplace>>>. With <<<war:inplace>>> the exploded WAR is created
- in the webapp source, which defaults to <<<src/main/webapp>>>.
- Use our sample project above, and invoke:
+Another variation of `war:exploded` is `war:inplace`. With `war:inplace` the exploded WAR is created in the webapp source, which defaults to `src/main/webapp`. Use our sample project above, and invoke:
-----------
+```
mvn compile war:inplace
-----------
+```
- This will result in:
+This will result in:
-----------
+```
|-- pom.xml
|-- src
| `-- main
@@ -226,4 +203,4 @@ mvn compile war:inplace
| `-- SampleAction.class
`-- images
`-- sampleimage.jpg
-----------
+```
(maven-war-plugin) 01/02: Rename the site documents ahead of converting them
Posted by sl...@apache.org.
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-war-plugin.git
commit 5bbded14edef24e82a5ddf3f8733942884ca54b5
Author: Sylwester Lachiewicz <sl...@apache.org>
AuthorDate: Thu Aug 6 13:52:59 2026 +0200
Rename the site documents ahead of converting them
A pure rename, so that git records it and `git log --follow` and `git blame` still
reach the history of each page after the conversion that follows. The content is
still APT at this point and the site does not build between the two commits.
---
.../examples/adding-filtering-webresources.md.vm} | 0
.../file-name-mapping.apt => markdown/examples/file-name-mapping.md} | 0
.../examples/including-excluding-files-from-war.md.vm} | 0
.../examples/rapid-testing-jetty6-plugin.md} | 0
.../examples/war-manifest-guide.md.vm} | 0
src/site/{apt/index.apt.vm => markdown/index.md} | 0
src/site/{apt/overlays.apt.vm => markdown/overlays.md.vm} | 0
src/site/{apt/usage.apt.vm => markdown/usage.md.vm} | 0
8 files changed, 0 insertions(+), 0 deletions(-)
diff --git a/src/site/apt/examples/adding-filtering-webresources.apt.vm b/src/site/markdown/examples/adding-filtering-webresources.md.vm
similarity index 100%
rename from src/site/apt/examples/adding-filtering-webresources.apt.vm
rename to src/site/markdown/examples/adding-filtering-webresources.md.vm
diff --git a/src/site/apt/examples/file-name-mapping.apt b/src/site/markdown/examples/file-name-mapping.md
similarity index 100%
rename from src/site/apt/examples/file-name-mapping.apt
rename to src/site/markdown/examples/file-name-mapping.md
diff --git a/src/site/apt/examples/including-excluding-files-from-war.apt.vm b/src/site/markdown/examples/including-excluding-files-from-war.md.vm
similarity index 100%
rename from src/site/apt/examples/including-excluding-files-from-war.apt.vm
rename to src/site/markdown/examples/including-excluding-files-from-war.md.vm
diff --git a/src/site/apt/examples/rapid-testing-jetty6-plugin.apt b/src/site/markdown/examples/rapid-testing-jetty6-plugin.md
similarity index 100%
rename from src/site/apt/examples/rapid-testing-jetty6-plugin.apt
rename to src/site/markdown/examples/rapid-testing-jetty6-plugin.md
diff --git a/src/site/apt/examples/war-manifest-guide.apt.vm b/src/site/markdown/examples/war-manifest-guide.md.vm
similarity index 100%
rename from src/site/apt/examples/war-manifest-guide.apt.vm
rename to src/site/markdown/examples/war-manifest-guide.md.vm
diff --git a/src/site/apt/index.apt.vm b/src/site/markdown/index.md
similarity index 100%
rename from src/site/apt/index.apt.vm
rename to src/site/markdown/index.md
diff --git a/src/site/apt/overlays.apt.vm b/src/site/markdown/overlays.md.vm
similarity index 100%
rename from src/site/apt/overlays.apt.vm
rename to src/site/markdown/overlays.md.vm
diff --git a/src/site/apt/usage.apt.vm b/src/site/markdown/usage.md.vm
similarity index 100%
rename from src/site/apt/usage.apt.vm
rename to src/site/markdown/usage.md.vm