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:24:35 UTC
(maven-shade-plugin) 02/02: Port the site documentation from APT to Markdown
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-shade-plugin.git
commit 659953d0df503e4d3f9389e206f32442d43af010
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.
---
src/site/markdown/examples/attached-artifact.md.vm | 52 ++--
src/site/markdown/examples/class-relocation.md.vm | 66 ++--
src/site/markdown/examples/executable-jar.md.vm | 56 ++--
src/site/markdown/examples/includes-excludes.md.vm | 80 ++---
.../markdown/examples/resource-transformers.md.vm | 345 +++++++++------------
.../markdown/examples/use-shader-other-impl.md.vm | 58 ++--
src/site/markdown/index.md | 95 ++----
src/site/markdown/usage.md.vm | 96 +++---
8 files changed, 346 insertions(+), 502 deletions(-)
diff --git a/src/site/markdown/examples/attached-artifact.md.vm b/src/site/markdown/examples/attached-artifact.md.vm
index 5838c15..7b6bef0 100644
--- a/src/site/markdown/examples/attached-artifact.md.vm
+++ b/src/site/markdown/examples/attached-artifact.md.vm
@@ -1,35 +1,27 @@
- ------
- Attaching the Shaded Artifact
- ------
- Mauro Talevi
- ------
- 2008-07-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
-Attaching the Shaded Artifact
+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.
+-->
- By default, the plugin will replace the project's main artifact with the shaded artifact. If both the original and
- the shaded artifact should be installed/deployed to the repository, one can configure the plugin to attach the
- shaded artifact as a secondary artifact:
+# Attaching the Shaded Artifact
-+-----
+By default, the plugin will replace the project's main artifact with the shaded artifact. If both the original and the shaded artifact should be installed/deployed to the repository, one can configure the plugin to attach the shaded artifact as a secondary artifact:
+
+```xml
<project>
...
<build>
@@ -55,6 +47,6 @@ Attaching the Shaded Artifact
</build>
...
</project>
-+-----
+```
- The shaded artifact is distinguished from the main artifact by means of the additional classifier.
+The shaded artifact is distinguished from the main artifact by means of the additional classifier.
diff --git a/src/site/markdown/examples/class-relocation.md.vm b/src/site/markdown/examples/class-relocation.md.vm
index 0dd6213..0f06d66 100644
--- a/src/site/markdown/examples/class-relocation.md.vm
+++ b/src/site/markdown/examples/class-relocation.md.vm
@@ -1,36 +1,27 @@
- ------
- Relocating Classes
- ------
- Mauro Talevi
- ------
- 2008-07-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
-Relocating Classes
+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.
+-->
- If the uber JAR is reused as a dependency of some other project, directly including classes from the artifact's
- dependencies in the uber JAR can cause class loading conflicts due to duplicate classes on the class path. To
- address this issue, one can relocate the classes which get included in the shaded artifact in order to create a
- private copy of their bytecode:
+# Relocating Classes
-+-----
+If the uber JAR is reused as a dependency of some other project, directly including classes from the artifact's dependencies in the uber JAR can cause class loading conflicts due to duplicate classes on the class path. To address this issue, one can relocate the classes which get included in the shaded artifact in order to create a private copy of their bytecode:
+
+```xml
<project>
...
<build>
@@ -64,17 +55,13 @@ Relocating Classes
</build>
...
</project>
-+-----
-
- This instructs the plugin to move classes from the package <<<org.codehaus.plexus.util>>> and its subpackages
- into the package <<<org.shaded.plexus.util>>> by moving the corresponding JAR file entries and rewriting the
- affected bytecode. The class <<<Xpp3Dom>>> and some others will remain in their original package.
-
+```
- It's also possible to narrow the pattern with the <<<include>>> and/or <<<exclude>>> tag:
+This instructs the plugin to move classes from the package `org.codehaus.plexus.util` and its subpackages into the package `org.shaded.plexus.util` by moving the corresponding JAR file entries and rewriting the affected bytecode. The class `Xpp3Dom` and some others will remain in their original package.
+It's also possible to narrow the pattern with the `include` and/or `exclude` tag:
-+-----
+```xml
<project>
...
<relocation>
@@ -89,7 +76,6 @@ Relocating Classes
</relocation>
...
</project>
-+-----
+```
-When using relocations with the <<<rawString>>> element set to <<<true>>>, both <<<includes>>> and <<<excludes>>> are disregarded but the pattern is treated as {{{https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html}regular expression pattern}}.
-Also the <<<pattern>>> and <<<shadedPattern>>> are always referring to a filesystem path (and must use forward slash (<<</>>>) as separator). Both are not normalized in this case.
+# When using relocations with the `rawString` element set to `true`, both `includes` and `excludes` are disregarded but the pattern is treated as [regular expression pattern](https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html). Also the `pattern` and `shadedPattern` are always referring to a filesystem path (and must use forward slash (`/`) as separator). Both are not normalized in this case.
diff --git a/src/site/markdown/examples/executable-jar.md.vm b/src/site/markdown/examples/executable-jar.md.vm
index fb4689a..4b6242f 100644
--- a/src/site/markdown/examples/executable-jar.md.vm
+++ b/src/site/markdown/examples/executable-jar.md.vm
@@ -1,33 +1,27 @@
- ------
- Executable JAR
- ------
- Mauro Talevi
- ------
- 2008-07-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
-Executable JAR
+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.
+-->
- To create an executable uber JAR, one simply needs to set the main class that serves as the application entry point:
+# Executable JAR
-+-----
+To create an executable uber JAR, one simply needs to set the main class that serves as the application entry point:
+
+```xml
<project>
...
<build>
@@ -56,13 +50,11 @@ Executable JAR
</build>
...
</project>
-+-----
+```
- This snippet configures a special resource transformer which sets the <<<Main-Class>>> entry in the <<<MANIFEST.MF>>>
- of the shaded JAR. Other entries can be added to the <<<MANIFEST.MF>>> as well via key-value pairs in the
- <<<\<manifestEntries\>>>> section:
+This snippet configures a special resource transformer which sets the `Main-Class` entry in the `MANIFEST.MF` of the shaded JAR. Other entries can be added to the `MANIFEST.MF` as well via key-value pairs in the `<manifestEntries>` section:
-+-----
+```xml
<project>
...
<build>
@@ -94,4 +86,4 @@ Executable JAR
</build>
...
</project>
-+-----
+```
diff --git a/src/site/markdown/examples/includes-excludes.md.vm b/src/site/markdown/examples/includes-excludes.md.vm
index 40b2e60..0375f66 100644
--- a/src/site/markdown/examples/includes-excludes.md.vm
+++ b/src/site/markdown/examples/includes-excludes.md.vm
@@ -1,33 +1,27 @@
- ------
- Selecting Contents for Uber JAR
- ------
- Mauro Talevi
- ------
- 2008-07-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
-Selecting Contents for Uber JAR
+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.
+-->
- The POM snippet below shows how to control which project dependencies should be included/excluded in the uber JAR:
+# Selecting Contents for Uber JAR
-+-----
+The POM snippet below shows how to control which project dependencies should be included/excluded in the uber JAR:
+
+```xml
<project>
...
<build>
@@ -61,16 +55,13 @@ Selecting Contents for Uber JAR
</build>
...
</project>
-+-----
-
- Of course, <<<\<includes\>>>> can be used as well to specify a white list of artifacts. Artifacts are denoted by a
- composite identifier of the form <groupId>:<artifactId>[[:<type>]:<classifier>]. Since plugin version 1.3, the
- wildcard characters '*' and '?' can be used to do glob-like pattern matching.
+```
+Of course, `<includes>` can be used as well to specify a white list of artifacts. Artifacts are denoted by a composite identifier of the form _groupId_:_artifactId_\[\[:_type_\]:_classifier_\]. Since plugin version 1.3, the wildcard characters '*' and '?' can be used to do glob-like pattern matching.
- For fine-grained control of which classes from the selected dependencies are included, artifact filters can be used:
+For fine-grained control of which classes from the selected dependencies are included, artifact filters can be used:
-+-----
+```xml
<project>
...
<build>
@@ -115,17 +106,13 @@ Selecting Contents for Uber JAR
</build>
...
</project>
-+-----
+```
- Here, Ant-like patterns are used to specify that from the dependency <<<junit:junit>>> only certain classes/resources
- should be included in the uber JAR. The second filter demonstrates the use of wildcards for the artifact identity which
- was introduced in plugin version 1.3. It excludes all signature related files from every artifact, regardless of its
- group or artifact id.
+Here, Ant-like patterns are used to specify that from the dependency `junit:junit` only certain classes/resources should be included in the uber JAR. The second filter demonstrates the use of wildcards for the artifact identity which was introduced in plugin version 1.3. It excludes all signature related files from every artifact, regardless of its group or artifact id.
- Besides user-specified filters, the plugin can also be configured to automatically remove all classes of dependencies
- that are not used by the project, thereby minimizing the resulting uber JAR:
+Besides user-specified filters, the plugin can also be configured to automatically remove all classes of dependencies that are not used by the project, thereby minimizing the resulting uber JAR:
-+-----
+```xml
<project>
...
<build>
@@ -150,14 +137,11 @@ Selecting Contents for Uber JAR
</build>
...
</project>
-+-----
+```
- As of version 1.6, minimizeJar will respect classes that were specifically marked for inclusion in a filter.
- Note that specifying an include filter for classes in an artifact implicitly excludes all non-specified
- classes in that artifact. <<<\<excludeDefaults\>false\<\\excludeDefaults\>>>> will override this behavior so that all
- non-specified classes still will be included though.
+As of version 1.6, minimizeJar will respect classes that were specifically marked for inclusion in a filter. Note that specifying an include filter for classes in an artifact implicitly excludes all non-specified classes in that artifact. `<excludeDefaults>false<\excludeDefaults>` will override this behavior so that all non-specified classes still will be included though.
-+-----
+```xml
<project>
...
<build>
@@ -203,4 +187,4 @@ Selecting Contents for Uber JAR
</build>
...
</project>
-+-----
+```
diff --git a/src/site/markdown/examples/resource-transformers.md.vm b/src/site/markdown/examples/resource-transformers.md.vm
index 4af315a..7f38c00 100644
--- a/src/site/markdown/examples/resource-transformers.md.vm
+++ b/src/site/markdown/examples/resource-transformers.md.vm
@@ -1,78 +1,55 @@
- ------
- Resource Transformers
- ------
- Mauro Talevi
- ------
- 2008-07-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
-~~
-~~ 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.
-
-Resource Transformers
-
- Aggregating classes/resources from several artifacts into one uber JAR is straight forward as long as there is no
- overlap. Otherwise, some kind of logic to merge resources from several JARs is required. This is where resource
- transformers kick in.
-
-
-*-----------------------------------------+------------------------------------------+
-| {{ApacheLicenseResourceTransformer}} | Prevents license duplication |
-*-----------------------------------------+------------------------------------------+
-| {{ApacheNoticeResourceTransformer}} | Prepares merged NOTICE |
-*-----------------------------------------+------------------------------------------+
-| {{AppendingTransformer}} | Adds content to a resource |
-*-----------------------------------------+------------------------------------------+
-| {{ComponentsXmlResourceTransformer}} | Aggregates Plexus <<<components.xml>>> |
-*-----------------------------------------+------------------------------------------+
-| {{DontIncludeResourceTransformer}} | Prevents inclusion of matching resources |
-*-----------------------------------------+------------------------------------------+
-| {{GroovyResourceTransformer}} | Merges Apache Groovy extends modules |
-*-----------------------------------------+------------------------------------------+
-| {{IncludeResourceTransformer}} | Adds files from the project |
-*-----------------------------------------+------------------------------------------+
-| {{ManifestResourceTransformer}} | Sets entries in the <<<MANIFEST>>> |
-*-----------------------------------------+------------------------------------------+
-| {{PluginXmlResourceTransformer}} | Aggregates Mavens <<<plugin.xml>>> |
-*-----------------------------------------+------------------------------------------+
-| {{ResourceBundleAppendingTransformer}} | Merges ResourceBundles |
-*-----------------------------------------+------------------------------------------+
-| {{ServicesResourceTransformer}} | Relocated class names in <<<META-INF/services>>> resources and merges them. |
-*-----------------------------------------+------------------------------------------+
-| {{XmlAppendingTransformer}} | Adds XML content to an XML resource |
-*-----------------------------------------+------------------------------------------+
-Transformers in <<<org.apache.maven.plugins.shade.resource>>>
-
-*-----------------------------------------+------------------------------------------+
-| {{PropertiesTransformer}} | Merges properties files owning an ordinal to solve conflicts |
-*-----------------------------------------+------------------------------------------+
-| {{OpenWebBeansPropertiesTransformer}} | Merges Apache OpenWebBeans configuration files |
-*-----------------------------------------+------------------------------------------+
-| {{MicroprofileConfigTransformer}} | Merges conflicting Microprofile Config properties based on an ordinal |
-*-----------------------------------------+------------------------------------------+
-Transformers in <<<org.apache.maven.plugins.shade.resource.properties>>> (available since 3.2.2)
-
-* Merging Plexus Component Descriptors with the {ComponentsXmlResourceTransformer}
-
- JARs for components targeting the Plexus IoC container contain a <<<META-INF/plexus/components.xml>>> entry that
- declares the component and its requirements. If the uber JAR aggregates multiple Plexus components, a
- <<<ComponentsXmlResourceTransformer>>> needs to be used to merge the XML descriptors:
-
-+-----
+<!--
+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.
+-->
+
+# Resource Transformers
+
+Aggregating classes/resources from several artifacts into one uber JAR is straight forward as long as there is no overlap. Otherwise, some kind of logic to merge resources from several JARs is required. This is where resource transformers kick in.
+
+| | |
+|:---|:---|
+|[ApacheLicenseResourceTransformer](#ApacheLicenseResourceTransformer)|Prevents license duplication|
+|[ApacheNoticeResourceTransformer](#ApacheNoticeResourceTransformer)|Prepares merged NOTICE|
+|[AppendingTransformer](#AppendingTransformer)|Adds content to a resource|
+|[ComponentsXmlResourceTransformer](#ComponentsXmlResourceTransformer)|Aggregates Plexus `components.xml`|
+|[DontIncludeResourceTransformer](#DontIncludeResourceTransformer)|Prevents inclusion of matching resources|
+|[GroovyResourceTransformer](#GroovyResourceTransformer)|Merges Apache Groovy extends modules|
+|[IncludeResourceTransformer](#IncludeResourceTransformer)|Adds files from the project|
+|[ManifestResourceTransformer](#ManifestResourceTransformer)|Sets entries in the `MANIFEST`|
+|[PluginXmlResourceTransformer](#PluginXmlResourceTransformer)|Aggregates Mavens `plugin.xml`|
+|[ResourceBundleAppendingTransformer](#ResourceBundleAppendingTransformer)|Merges ResourceBundles|
+|[ServicesResourceTransformer](#ServicesResourceTransformer)|Relocated class names in `META-INF/services` resources and merges them.|
+|[XmlAppendingTransformer](#XmlAppendingTransformer)|Adds XML content to an XML resource|
+Transformers in `org.apache.maven.plugins.shade.resource`
+
+| | |
+|:---|:---|
+|[PropertiesTransformer](#PropertiesTransformer)|Merges properties files owning an ordinal to solve conflicts|
+|[OpenWebBeansPropertiesTransformer](#OpenWebBeansPropertiesTransformer)|Merges Apache OpenWebBeans configuration files|
+|[MicroprofileConfigTransformer](#MicroprofileConfigTransformer)|Merges conflicting Microprofile Config properties based on an ordinal|
+`org.apache.maven.plugins.shade.resource.properties`
+
+Merging Plexus Component Descriptors with the <a id="ComponentsXmlResourceTransformer"></a>ComponentsXmlResourceTransformer
+---------------------------------------------------------------------------------------------------------------------------
+
+JARs for components targeting the Plexus IoC container contain a `META-INF/plexus/components.xml` entry that declares the component and its requirements. If the uber JAR aggregates multiple Plexus components, a `ComponentsXmlResourceTransformer` needs to be used to merge the XML descriptors:
+
+```xml
<project>
...
<build>
@@ -98,18 +75,16 @@ Transformers in <<<org.apache.maven.plugins.shade.resource.properties>>> (availa
</build>
...
</project>
-+-----
+```
- Since plugin version 1.3, this resource transformer will also update the descriptor to account for relocation of
- component interfaces/implementations (if any).
+Since plugin version 1.3, this resource transformer will also update the descriptor to account for relocation of component interfaces/implementations (if any).
-* Relocate classes of the Maven Plugin Descriptor with the {PluginXmlResourceTransformer}
+Relocate classes of the Maven Plugin Descriptor with the <a id="PluginXmlResourceTransformer"></a>PluginXmlResourceTransformer
+------------------------------------------------------------------------------------------------------------------------------
- With {{{http://maven.apache.org/plugin-tools/index.html}Plugin Tools 3.0}} annotations have been introduced. Now references
- to classes are no longer classnames as String, but the actual Class reference. When you wanted to relocate classes, you had to
- maintain the <<<META-INF/maven/plugin.xml>>> by hand, but now this can be done with the <<<PluginXmlResourceTransformer>>>
+With [Plugin Tools 3.0](http://maven.apache.org/plugin-tools/index.html) annotations have been introduced. Now references to classes are no longer classnames as String, but the actual Class reference. When you wanted to relocate classes, you had to maintain the `META-INF/maven/plugin.xml` by hand, but now this can be done with the `PluginXmlResourceTransformer`
-+-----
+```xml
<project>
...
<build>
@@ -135,17 +110,14 @@ Transformers in <<<org.apache.maven.plugins.shade.resource.properties>>> (availa
</build>
...
</project>
-+-----
+```
-* Concatenating Service Entries with the {ServicesResourceTransformer}
+Concatenating Service Entries with the <a id="ServicesResourceTransformer"></a>ServicesResourceTransformer
+----------------------------------------------------------------------------------------------------------
- JAR files providing implementations of some interfaces often ship with a <<<META-INF/services/>>> directory that
- maps interfaces to their implementation classes for lookup by the service locator.
- To relocate the class names of these implementation classes, and to
- merge multiple implementations of the same interface into one service entry,
- the <<<ServicesResourceTransformer>>> can be used:
+JAR files providing implementations of some interfaces often ship with a `META-INF/services/` directory that maps interfaces to their implementation classes for lookup by the service locator. To relocate the class names of these implementation classes, and to merge multiple implementations of the same interface into one service entry, the `ServicesResourceTransformer` can be used:
-+-----
+```xml
<project>
...
<build>
@@ -171,16 +143,14 @@ Transformers in <<<org.apache.maven.plugins.shade.resource.properties>>> (availa
</build>
...
</project>
-+-----
+```
-* Merging Content of Specific Files with {AppendingTransformer}, XmlAppendingTransformer and ResourceBundleAppendingTransformer
+Merging Content of Specific Files with <a id="AppendingTransformer"></a>AppendingTransformer, XmlAppendingTransformer and ResourceBundleAppendingTransformer
+------------------------------------------------------------------------------------------------------------------------------------------------------------
- Some jars contain additional resources (such as properties files) that have the same file name. To avoid overwriting, you can
- opt to merge them by appending their content into one file. One good example for this is when aggregating both the spring-context
- and plexus-spring jars. Both of them have the <<<META-INF/spring.handlers>>> file which is used by Spring to handle XML schema
- namespaces. You can merge the contents of all the files with that specific name using the <<<AppendingTransformer>>> as shown below:
-
-+-----
+Some jars contain additional resources (such as properties files) that have the same file name. To avoid overwriting, you can opt to merge them by appending their content into one file. One good example for this is when aggregating both the spring-context and plexus-spring jars. Both of them have the `META-INF/spring.handlers` file which is used by Spring to handle XML schema namespaces. You can merge the contents of all the files with that specific name using the `AppendingTransformer` [...]
+
+```xml
<project>
...
<build>
@@ -211,11 +181,11 @@ Transformers in <<<org.apache.maven.plugins.shade.resource.properties>>> (availa
</build>
...
</project>
-+-----
+```
- For XML files, you can use the <<<{XmlAppendingTransformer}>>> instead:
+For XML files, you can use the `<a id="XmlAppendingTransformer"></a>XmlAppendingTransformer` instead:
-+-----
+```xml
<project>
...
<build>
@@ -246,17 +216,13 @@ Transformers in <<<org.apache.maven.plugins.shade.resource.properties>>> (availa
</build>
...
</project>
-+-----
+```
+
+Since plugin version 1.3.1, the `XmlAppendingTransformer` will by default not load DTDs, thereby avoiding network access. The potential downside of this mode is that external entities cannot be resolved which could fail the transformation, e.g. when using the Crimson XML parser as used in some JRE 1.4. If the transformed resource uses external entities, DTD resolution can either be turned back on or a plugin dependency on `xerces:xercesImpl:2.9.1` is added to the POM.
- Since plugin version 1.3.1, the <<<XmlAppendingTransformer>>> will by default not load DTDs, thereby avoiding network
- access. The potential downside of this mode is that external entities cannot be resolved which could fail the
- transformation, e.g. when using the Crimson XML parser as used in some JRE 1.4. If the transformed resource uses
- external entities, DTD resolution can either be turned back on or a plugin dependency on <<<xerces:xercesImpl:2.9.1>>>
- is added to the POM.
-
- For ResourceBundles properties files, you can use the <<<{ResourceBundleAppendingTransformer}>>> instead, which will respect all available Locales as well:
+For ResourceBundles properties files, you can use the `<a id="ResourceBundleAppendingTransformer"></a>ResourceBundleAppendingTransformer` instead, which will respect all available Locales as well:
-+-----
+```xml
<project>
...
<build>
@@ -285,16 +251,16 @@ Transformers in <<<org.apache.maven.plugins.shade.resource.properties>>> (availa
</build>
...
</project>
-+-----
+```
-* Excluding Resources with the {DontIncludeResourceTransformer}
+Excluding Resources with the <a id="DontIncludeResourceTransformer"></a>DontIncludeResourceTransformer
+------------------------------------------------------------------------------------------------------
- The <<<DontIncludeResourceTransformer>>> allows resources to be excluded when
- their name ends in a given value.
+The `DontIncludeResourceTransformer` allows resources to be excluded when their name ends in a given value.
- For example, the following sample excludes all resources ending in <<<.txt>>>.
+For example, the following sample excludes all resources ending in `.txt`.
-+-----
+```xml
<project>
...
<build>
@@ -322,30 +288,27 @@ Transformers in <<<org.apache.maven.plugins.shade.resource.properties>>> (availa
</build>
...
</project>
-+-----
+```
- Since maven-shade-plugin-3.0 it is also possible to give a list of resources which should not be included, like:
+Since maven-shade-plugin-3.0 it is also possible to give a list of resources which should not be included, like:
-+-----
+```xml
<transformer implementation="org.apache.maven.plugins.shade.resource.DontIncludeResourceTransformer">
<resources>
<resource>.txt</resource>
<resource>READ.me</resource>
</resources>
</transformer>
-+-----
-
+```
+Adding New Resources with the <a id="IncludeResourceTransformer"></a>IncludeResourceTransformer
+-----------------------------------------------------------------------------------------------
-* Adding New Resources with the {IncludeResourceTransformer}
+The `IncludeResourceTransformer` allows project files to be included in the package under a given name.
- The <<<IncludeResourceTransformer>>> allows project files to be included in
- the package under a given name.
+For example, the following sample includes `README.txt` in the package as `README` in the `META-INF` directory.
- For example, the following sample includes <<<README.txt>>> in the package
- as <<<README>>> in the <<<META-INF>>> directory.
-
-+-----
+```xml
<project>
...
<build>
@@ -374,36 +337,29 @@ Transformers in <<<org.apache.maven.plugins.shade.resource.properties>>> (availa
</build>
...
</project>
-+-----
-
+```
-* Setting Manifest Entries with the {ManifestResourceTransformer}
+Setting Manifest Entries with the <a id="ManifestResourceTransformer"></a>ManifestResourceTransformer
+-----------------------------------------------------------------------------------------------------
- The <<<ManifestResourceTransformer>>> allows existing entries in the <<<MANIFEST>>>
- to be replaced and new entries added.
+The `ManifestResourceTransformer` allows existing entries in the `MANIFEST` to be replaced and new entries added.
- For example, the following sample sets
-
- * the <<<Main-Class>>> entry to the value of the <<<app.main.class>>> property,
-
- * the <<<X-Compile-Source-JDK>>> entry to the value of the <<<maven.compile.source>>> property and
-
- * the <<<X-Compile-Target-JDK>>> entry to the value of the <<<maven.compile.target>>> property.
+For example, the following sample sets
- By default the <<<ManifestResourceTransformer>>> will relocate the following attributes:
+- the `Main-Class` entry to the value of the `app.main.class` property,
+- the `X-Compile-Source-JDK` entry to the value of the `maven.compile.source` property and
+- the `X-Compile-Target-JDK` entry to the value of the `maven.compile.target` property.
- * Export-Package
+By default the `ManifestResourceTransformer` will relocate the following attributes:
- * Import-Package
+- Export-Package
+- Import-Package
+- Provide-Capability
+- Require-Capability
- * Provide-Capability
+With `additionalAttributes` you can specify the attributes that need to be relocated too.
- * Require-Capability
-
- With <<<additionalAttributes>>> you can specify the attributes that need to be relocated too.
-
-
-+-----
+```xml
<project>
...
<build>
@@ -435,25 +391,18 @@ Transformers in <<<org.apache.maven.plugins.shade.resource.properties>>> (availa
</build>
...
</project>
-+-----
+```
+Licensing
+---------
-* Licensing
+#[[### Preventing License Duplication with the <a id="ApacheLicenseResourceTransformer"></a>ApacheLicenseResourceTransformer]]#
-** Preventing License Duplication with the {ApacheLicenseResourceTransformer}
+Some open source producers (including the [ Apache Software Foundation](https://www.apache.org)) include a copy of their license in the META-INF directory. These are conventionally named either `LICENSE`,`LICENSE.txt` or `LICENSE.md`. When merging these dependencies, adding these resources may cause confusion. The `ApacheLicenseResourceTransformer` ensures that duplicate licenses (named according to this convention) are not merged.
- Some open source producers
- (including the {{{https://www.apache.org} Apache Software Foundation}})
- include a copy of their license in the META-INF directory. These are conventionally named
- either <<<LICENSE>>>,<<<LICENSE.txt>>> or <<<LICENSE.md>>>. When merging these dependencies, adding these
- resources may cause confusion.
- The <<<ApacheLicenseResourceTransformer>>> ensures that duplicate licenses (named according
- to this convention) are not merged.
+For example, the following prevents the license from a `commons-collections` dependency being merged in
- For example, the following prevents the license from a <<<commons-collections>>> dependency
- being merged in
-
-+-----
+```xml
<project>
...
<build>
@@ -480,18 +429,15 @@ Transformers in <<<org.apache.maven.plugins.shade.resource.properties>>> (availa
</build>
...
</project>
-+-----
+```
+
+#[[### Aggregating Notices with the <a id="ApacheNoticeResourceTransformer"></a>ApacheNoticeResourceTransformer]]#
-** Aggregating Notices with the {ApacheNoticeResourceTransformer}
+Some licenses (including the [ Apache License, Version 2](https://www.apache.org/licenses/LICENSE-2.0.html)) require that notices are preserved by downstream distributors. `ApacheNoticeResourceTransformer` automates the assembly of an appropriate `NOTICE`.
- Some licenses
- (including the {{{https://www.apache.org/licenses/LICENSE-2.0.html} Apache License, Version 2}})
- require that notices are preserved by downstream distributors. <<<ApacheNoticeResourceTransformer>>>
- automates the assembly of an appropriate <<<NOTICE>>>.
+For example, to simply merge in dependent notices:
- For example, to simply merge in dependent notices:
-
-+-----
+```xml
<project>
...
<build>
@@ -519,17 +465,15 @@ Transformers in <<<org.apache.maven.plugins.shade.resource.properties>>> (availa
</build>
...
</project>
-+-----
+```
-** Aggregating Apache Groovy extension modules descriptors with the {GroovyResourceTransformer}
+#[[### Aggregating Apache Groovy extension modules descriptors with the <a id="GroovyResourceTransformer"></a>GroovyResourceTransformer]]#
- The Apache Groovy language provides extension modules located at
- <<<META-INF/services/org.codehaus.groovy.runtime.ExtensionModule>>>, these modules use the property file format.
- <<<GroovyResourceTransformer>>> automates the assembly of Groovy extension modules <<<NOTICE>>>.
+The Apache Groovy language provides extension modules located at `META-INF/services/org.codehaus.groovy.runtime.ExtensionModule`, these modules use the property file format. `GroovyResourceTransformer` automates the assembly of Groovy extension modules `NOTICE`.
- For example, to simply merge the extension modules of several jars:
+For example, to simply merge the extension modules of several jars:
-+-----
+```xml
<project>
...
<build>
@@ -558,17 +502,14 @@ Transformers in <<<org.apache.maven.plugins.shade.resource.properties>>> (availa
</build>
...
</project>
-+-----
+```
-* Merging properties files with {PropertiesTransformer}
+Merging properties files with <a id="PropertiesTransformer"></a>PropertiesTransformer
+-------------------------------------------------------------------------------------
- The <<<PropertiesTransformer>>> allows a set of properties files to be merged and to resolve conflicts
- based on an ordinal giving the priority of each file.
- An optional <<<alreadyMergedKey>>> enables to have a boolean flag in the file which, if set to true,
- request to use the file as it as the result of the merge. If two files are considered complete in the
- merge process then the shade will fail.
+The `PropertiesTransformer` allows a set of properties files to be merged and to resolve conflicts based on an ordinal giving the priority of each file. An optional `alreadyMergedKey` enables to have a boolean flag in the file which, if set to true, request to use the file as it as the result of the merge. If two files are considered complete in the merge process then the shade will fail.
-+-----
+```xml
<project>
...
<build>
@@ -602,15 +543,14 @@ Transformers in <<<org.apache.maven.plugins.shade.resource.properties>>> (availa
</build>
...
</project>
-+-----
-
-* Merging Apache OpenWebBeans configuration with {OpenWebBeansPropertiesTransformer}
+```
- <<<OpenWebBeansPropertiesTransformer>>> preconfigure a <<<PropertiesTransformer>>>
- for Apache OpenWebBeans configuration files.
+Merging Apache OpenWebBeans configuration with <a id="OpenWebBeansPropertiesTransformer"></a>OpenWebBeansPropertiesTransformer
+------------------------------------------------------------------------------------------------------------------------------
+`OpenWebBeansPropertiesTransformer` preconfigure a `PropertiesTransformer` for Apache OpenWebBeans configuration files.
-+-----
+```xml
<project>
...
<build>
@@ -636,16 +576,14 @@ Transformers in <<<org.apache.maven.plugins.shade.resource.properties>>> (availa
</build>
...
</project>
-+-----
+```
-* Merging Microprofile Config properties with {MicroprofileConfigTransformer}
+Merging Microprofile Config properties with <a id="MicroprofileConfigTransformer"></a>MicroprofileConfigTransformer
+-------------------------------------------------------------------------------------------------------------------
- <<<MicroprofileConfigTransformer>>> preconfigure a <<<PropertiesTransformer>>>
- for Microprofile Config. The only required configuration is the ordinal.
- The <<<alreadyMergedKey>>> is supported but is not defined by the specification.
+`MicroprofileConfigTransformer` preconfigure a `PropertiesTransformer` for Microprofile Config. The only required configuration is the ordinal. The `alreadyMergedKey` is supported but is not defined by the specification.
-
-+-----
+```xml
<project>
...
<build>
@@ -673,5 +611,4 @@ Transformers in <<<org.apache.maven.plugins.shade.resource.properties>>> (availa
</build>
...
</project>
-+-----
-
+```
diff --git a/src/site/markdown/examples/use-shader-other-impl.md.vm b/src/site/markdown/examples/use-shader-other-impl.md.vm
index 83dfa31..c5b7517 100644
--- a/src/site/markdown/examples/use-shader-other-impl.md.vm
+++ b/src/site/markdown/examples/use-shader-other-impl.md.vm
@@ -1,35 +1,29 @@
- ------
- Using an other Shader Implementation
- ------
- Olivier Lamy
- ------
- 2012-03-13
- ------
+<!--
+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
-Using your own Shader implementation
+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.
+-->
- By default, the plugin provide a DefaultShader implementation but with version 1.6 you can use your own implementation.
+# Using your own Shader implementation
- Create a standard Maven project with your implementation.
+By default, the plugin provide a DefaultShader implementation but with version 1.6 you can use your own implementation.
-+-----
+Create a standard Maven project with your implementation.
+
+```unknown
Dependency to Plexus annotations
@@ -62,11 +56,11 @@ public class MockShader
</execution>
</executions>
</plugin>
-+-----
+```
- Assuming your project has coordinate org.foo.bar:wine:1.0, you must add it as a dependency of the shade plugin.
+Assuming your project has coordinate org.foo.bar:wine:1.0, you must add it as a dependency of the shade plugin.
-+-----
+```xml
<project>
...
<build>
@@ -98,6 +92,6 @@ public class MockShader
</build>
...
</project>
-+-----
+```
- Now the mojo will use your own implementation.
+Now the mojo will use your own implementation.
diff --git a/src/site/markdown/index.md b/src/site/markdown/index.md
index 697ad00..3b1029f 100644
--- a/src/site/markdown/index.md
+++ b/src/site/markdown/index.md
@@ -1,74 +1,45 @@
- ------
- Introduction
- ------
- Mauro Talevi
- ------
- 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
-${project.name}
+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.
+-->
- This plugin provides the capability to package the artifact in an uber-jar, including its dependencies and
- to <shade> - i.e. rename - the packages of some of the dependencies.
+# Apache Maven Shade Plugin
+This plugin provides the capability to package the artifact in an uber-jar, including its dependencies and to _shade_ - i.e. rename - the packages of some of the dependencies.
-* Goals Overview
+## Goals Overview
- The Shade Plugin has a single goal:
+The Shade Plugin has a single goal:
- * {{{./shade-mojo.html}shade:shade}} is bound to the <<<package>>> phase and
- is used to create a shaded jar.
+- [shade:shade](./shade-mojo.html) is bound to the `package` phase and is used to create a shaded jar.
+## Usage
-* Usage
+General instructions on how to use the Shade Plugin can be found on the [usage page](./usage.html). Some more specific use cases are described in the examples given below.
- General instructions on how to use the Shade Plugin can be found on the {{{./usage.html}usage page}}. Some more
- specific use cases are described in the examples given below.
+In case you still have questions regarding the plugin's usage, please 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](./mail-lists.html).
- In case you still have questions regarding the plugin's usage, please 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 {{{./mail-lists.html}mail archive}}.
+If you feel like the plugin is missing a feature or has a defect, you can fill a feature request or bug report in our [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 wel [...]
- If you feel like the plugin is missing a feature or has a defect, you can fill a feature request or bug report in our
- {{{./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
- {{{http://maven.apache.org/guides/development/guide-helping.html}guide to helping with Maven}}.
+## Examples
+To provide you with better understanding on some usages of the Shade Plugin, you can take a look into the following examples:
-* Examples
-
- To provide you with better understanding on some usages of the Shade Plugin,
- you can take a look into the following examples:
-
- * {{{./examples/includes-excludes.html}Selecting Contents for Uber JAR}}
-
- * {{{./examples/class-relocation.html}Relocating Classes}}
-
- * {{{./examples/attached-artifact.html}Attaching the Shaded Artifact}}
-
- * {{{./examples/executable-jar.html}Executable JAR}}
-
- * {{{./examples/resource-transformers.html}Resource Transformers}}
-
- * {{{./examples/use-shader-other-impl.html}Using another Shader implementation}}
-
- []
+- [Selecting Contents for Uber JAR](./examples/includes-excludes.html)
+- [Relocating Classes](./examples/class-relocation.html)
+- [Attaching the Shaded Artifact](./examples/attached-artifact.html)
+- [Executable JAR](./examples/executable-jar.html)
+- [Resource Transformers](./examples/resource-transformers.html)
+- [Using another Shader implementation](./examples/use-shader-other-impl.html)
diff --git a/src/site/markdown/usage.md.vm b/src/site/markdown/usage.md.vm
index 378b620..c65b062 100644
--- a/src/site/markdown/usage.md.vm
+++ b/src/site/markdown/usage.md.vm
@@ -1,42 +1,37 @@
- ------
- Usage
- ------
- Mauro Talevi
- ------
- 2008-07-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
-Usage
+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.
+-->
-* Creating a Shaded JAR
+# Usage
- The goals for the Shade Plugin are bound to the <<<package>>> phase in the
- build lifecycle.
+Creating a Shaded JAR
+---------------------
-+-----
+The goals for the Shade Plugin are bound to the `package` phase in the build lifecycle.
+
+```shell
mvn package
-+-----
+```
-* Configuring Your Shade Plugin
+Configuring Your Shade Plugin
+-----------------------------
-+-----
+```xml
<project>
...
<build>
@@ -61,29 +56,22 @@ mvn package
</build>
...
</project>
-+-----
+```
-* Resource Transformers
+Resource Transformers
+---------------------
-*-----------------------------------------+--------------------------------------+
-| ApacheLicenseResourceTransformer | Prevents license duplication |
-*-----------------------------------------+--------------------------------------+
-| ApacheNoticeResourceTransformer | Prepares merged NOTICE |
-*-----------------------------------------+--------------------------------------+
-| AppendingTransformer | Adds content to a resource |
-*-----------------------------------------+--------------------------------------+
-| ComponentsXmlResourceTransformer | Aggregates Plexus <<<components.xml>>>|
-*-----------------------------------------+--------------------------------------+
-| DontIncludeResourceTransformer | Prevents inclusion of matching resources |
-*-----------------------------------------+--------------------------------------+
-| IncludeResourceTransformer | Adds files from the project |
-*-----------------------------------------+--------------------------------------+
-| ManifestResourceTransformer | Sets entries in the <<<MANIFEST>>> |
-*-----------------------------------------+--------------------------------------+
-| ServicesResourceTransformer | Merges <<<META-INF/services>>> resources |
-*-----------------------------------------+--------------------------------------+
-| XmlAppendingTransformer | Adds XML content to an XML resource |
-*-----------------------------------------+--------------------------------------+
-Transformers in <<<org.apache.maven.plugins.shade.resource>>>
+| | |
+|:---|:---|
+|ApacheLicenseResourceTransformer|Prevents license duplication|
+|ApacheNoticeResourceTransformer|Prepares merged NOTICE|
+|AppendingTransformer|Adds content to a resource|
+|ComponentsXmlResourceTransformer|Aggregates Plexus `components.xml`|
+|DontIncludeResourceTransformer|Prevents inclusion of matching resources|
+|IncludeResourceTransformer|Adds files from the project|
+|ManifestResourceTransformer|Sets entries in the `MANIFEST`|
+|ServicesResourceTransformer|Merges `META-INF/services` resources|
+|XmlAppendingTransformer|Adds XML content to an XML resource|
+Transformers in `org.apache.maven.plugins.shade.resource`
- For more information, see {{{./examples/resource-transformers.html}samples}}.
+For more information, see [samples](./examples/resource-transformers.html).