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/08 21:07:58 UTC
(maven-site) 02/02: Port the last APT documents 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-site.git
commit ccb2c10205742ce38de6b5e765c7872d2a04f6bf
Author: Sylwester Lachiewicz <sl...@apache.org>
AuthorDate: Fri Aug 7 22:48:14 2026 +0200
Port the last APT documents to Markdown
Six guides and the fragment one of them parses. Four keep their .vm suffix because
they interpolate a version or a path; guides/index.md.vm and guides/mini/index.md.vm
keep theirs for the #set and #parse directives that build the mini-guide list.
Three things the conversion needed by hand:
* Velocity reads ## as a line comment, so level two headings use a setext underline
and deeper ones are wrapped in an unparsed block.
* APT writes $\{foo\} for a reference it means to display, and its parser strips
the backslashes, so the converted page carried a live ${prefix}, ${groupId},
${user.home} and friends. Those are now ${esc.d}{foo}.
* mini/index.txt is parsed into a Markdown page, so its APT comments and link
syntax had to become Markdown too, and it moves with the page that parses it.
Verified by building the site before and after and comparing all 265 generated
pages: 264 are identical in title, author and date metadata, visible text and every
link target. The one difference is that a Markdown table must have a header row
where the APT table had none, so two tables in the Java plugin guide gain an empty
one.
---
content/apt/guides/mini/index.txt | 50 --
.../development/guide-plugin-documentation.md.vm | 613 ++++++++++-----------
content/markdown/guides/index.md.vm | 276 ++++------
.../introduction-to-plugin-prefix-mapping.md.vm | 199 +++----
content/markdown/guides/mini/index.md.vm | 53 +-
content/markdown/guides/mini/index.txt | 36 ++
.../plugin/guide-java-plugin-development.md.vm | 362 +++++-------
.../guide-java-report-plugin-development.md.vm | 341 +++++-------
8 files changed, 797 insertions(+), 1133 deletions(-)
diff --git a/content/apt/guides/mini/index.txt b/content/apt/guides/mini/index.txt
deleted file mode 100644
index ad0a4808..00000000
--- a/content/apt/guides/mini/index.txt
+++ /dev/null
@@ -1,50 +0,0 @@
-~~ 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.
-
- * {{{$prefix/guide-reproducible-builds.html}Configuring for Reproducible Builds}}
-
- * {{{$prefix/guide-assemblies.html}Creating Assemblies}}
-
- * {{{$prefix/guide-archive-configuration.html}Configuring Archive Plugins}}
-
- * {{{$prefix/guide-configuring-maven.html}Configuring Maven}}
-
- * {{{$prefix/guide-generating-sources.html}Generating Sources}}
-
- * {{{$prefix/guide-manifest.html}Working with Manifests}}
-
- * {{{$prefix/guide-maven-classloading.html}Maven Classloading}}
-
- * {{{$prefix/guide-multiple-modules.html}Using Multiple Modules in a Build}}
-
- * {{{$prefix/guide-releasing.html}Using the Release Plugin}}
-
- * {{{$prefix/guide-using-ant.html}Using Ant with Maven}}
-
- * {{{$prefix/guide-using-modello.html}Using Modello}}
-
- * {{{$prefix/guide-using-extensions.html}Using Extensions}}
-
- * {{{$prefix/guide-building-for-different-environments.html}Building For Different Environments}}
-
- * {{{$prefix/guide-using-toolchains.html}Using Toolchains}}
-
- * {{{/examples/injecting-properties-via-settings.html}Injecting POM Properties via settings.xml}}
-
-~~ ** Testing
-
-~~ * {{{$prefix/guide-attached-tests.html}Reusable Test JARs}}
diff --git a/content/markdown/guides/development/guide-plugin-documentation.md.vm b/content/markdown/guides/development/guide-plugin-documentation.md.vm
index 0edbf9df..ba7e38ec 100644
--- a/content/markdown/guides/development/guide-plugin-documentation.md.vm
+++ b/content/markdown/guides/development/guide-plugin-documentation.md.vm
@@ -1,123 +1,95 @@
- ------
- Guide to the Plugin Documentation Standard
- ------
- Maven Team
- ------
- 2006-07-06
- ------
-
-~~ 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
-
-Introduction
-
-*Where did the standard come from?
-
- The plugin documentation standard was created to address frequent complaints about the lack of
- documentation, specifically on the Maven plugins. The standard was based on the suggestions made
- on the Maven dev mailing list with some refinements. It is a community consensus of the basic
- documentation a Maven plugin should have.
-
- {{{/plugins/maven-docck-plugin/}Maven Documentation Checker Plugin}} (aka. DocCK) was created at that time to help check plugin documentation,
- but it is now unmaintained.
-
-*Why do we need a documentation standard?
-
- The standard is not a set of rules but a guide to help plugin developers document their plugins
- better, for the benefit of the users of the plugin. The standard also reminds plugin developers
- of important details that need to be documented to help speed up the adoption of the plugin.
-
-*Generated Documentation
-
- It is recommended that you let Maven generate the basic information for the plugin to make sure that
- that the basic information is always accurate and synchronized with the plugin implementation.
-
- Documentation is generated by running
+---
+title: Guide to the Plugin Documentation Standard
+author:
+ - Maven Team
+date: 2006-07-06
+---
------------------
-mvn site
------------------
+<!--
+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
- Like any Maven project, this will generate a site based on the information in the POM used by {{{/plugins/maven-project-info-reports-plugin/}Maven Project Info Reports Plugin}},
- <<<src/site>>> and other reporting plugins configured in the POM (like javadoc, jxr, or any other classical project report plugin).
+http://www.apache.org/licenses/LICENSE-2.0
- In addition, the most important additional reporting plugin for a plugin is the
- {{{/plugins/maven-plugin-report-plugin/}Maven Plugin Report Plugin}}, which will generate
- the <<documentation for each plugin goal>> based on the Mojo annotations. But in order for the generated site to be
- usable, the required information should be available to the Maven Site Plugin.
+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.
+-->
-*POM Elements
+# Introduction
- Like any Maven project, Maven extracts the information from the POM to let {{{/plugins/maven-project-info-reports-plugin/}Maven Project Info Reports Plugin}} generate the pages under {{{/project-info.html}"Project Information"}}.
- The first step in good documentation is to have accurate and visible basic project
- information. Maven can provide this for the plugin as long as the information in the POM is
- complete, descriptive, and accurate.
+Where did the standard come from?
+---------------------------------
-**Required Elements
+The plugin documentation standard was created to address frequent complaints about the lack of documentation, specifically on the Maven plugins. The standard was based on the suggestions made on the Maven dev mailing list with some refinements. It is a community consensus of the basic documentation a Maven plugin should have.
- Minimum elements for a valid POM:
+[Maven Documentation Checker Plugin](/plugins/maven-docck-plugin/) (aka. DocCK) was created at that time to help check plugin documentation, but it is now unmaintained.
- * <<<\<modelVersion\>>>> - POM model version, currently 4.0.0
+Why do we need a documentation standard?
+----------------------------------------
- * <<<\<groupId\>>>> - the package name
+The standard is not a set of rules but a guide to help plugin developers document their plugins better, for the benefit of the users of the plugin. The standard also reminds plugin developers of important details that need to be documented to help speed up the adoption of the plugin.
- * <<<\<artifactId\>>>> - artifact name
+Generated Documentation
+-----------------------
- * <<<\<packaging\>>>> - type of artifact produced by the POM
+It is recommended that you let Maven generate the basic information for the plugin to make sure that that the basic information is always accurate and synchronized with the plugin implementation.
- * <<<\<version\>>>> - the plugin version
+Documentation is generated by running
-**Optional Elements
-
- These might be optional elements in a valid POM but they are important basic project information
- required by the users to effectively use the plugin:
-
- * <<<\<name\>>>> - plugin's name, <Maven NNN Plugin> for plugins hosted at the Maven project or
- <NNN Maven Plugin> for all others
+```
+mvn site
+```
- * <<<\<description\>>>> - project description, an overview of what the plugin can do
+Like any Maven project, this will generate a site based on the information in the POM used by [Maven Project Info Reports Plugin](/plugins/maven-project-info-reports-plugin/), `src/site` and other reporting plugins configured in the POM (like javadoc, jxr, or any other classical project report plugin).
- * <<<\<url\>>>> - the site of the plugin, normally <maven.apache.org> or <org.mojohaus>
+In addition, the most important additional reporting plugin for a plugin is the [Maven Plugin Report Plugin](/plugins/maven-plugin-report-plugin/), which will generate the **documentation for each plugin goal** based on the Mojo annotations. But in order for the generated site to be usable, the required information should be available to the Maven Site Plugin.
- * <<<\<prerequisites\>>>> - the minimum version of Maven required to use this plugin
+POM Elements
+------------
- * <<<\<issueManagement\>>>> - describes the system used for reporting problems and modification requests
+Like any Maven project, Maven extracts the information from the POM to let [Maven Project Info Reports Plugin](/plugins/maven-project-info-reports-plugin/) generate the pages under ["Project Information"](/project-info.html). The first step in good documentation is to have accurate and visible basic project information. Maven can provide this for the plugin as long as the information in the POM is complete, descriptive, and accurate.
- * <<<\<inceptionYear\>>>> - year the plugin was first created
+#[[### Required Elements]]#
- * <<<\<mailingLists\>>>> - lists where other users or the developers can be contacted for help and discussions
+Minimum elements for a valid POM:
- * <<<\<licenses\>>>> - plugin license
+- `<modelVersion>` - POM model version, currently 4.0.0
+- `<groupId>` - the package name
+- `<artifactId>` - artifact name
+- `<packaging>` - type of artifact produced by the POM
+- `<version>` - the plugin version
+#[[### Optional Elements]]#
- * <<<\<scm\>>>> - the source code management configuration - a plugin without this would raise suspicion, might not be OSS
+These might be optional elements in a valid POM but they are important basic project information required by the users to effectively use the plugin:
- * <<<\<organization\>>>> - the organization maintaining the plugin, just in case we need someone to blame
+- `<name>` - plugin's name, _Maven NNN Plugin_ for plugins hosted at the Maven project or _NNN Maven Plugin_ for all others
+- `<description>` - project description, an overview of what the plugin can do
+- `<url>` - the site of the plugin, normally _maven.apache.org_ or _org.mojohaus_
+- `<prerequisites>` - the minimum version of Maven required to use this plugin
+- `<issueManagement>` - describes the system used for reporting problems and modification requests
+- `<inceptionYear>` - year the plugin was first created
+- `<mailingLists>` - lists where other users or the developers can be contacted for help and discussions
+- `<licenses>` - plugin license
+- `<scm>` - the source code management configuration - a plugin without this would raise suspicion, might not be OSS
+- `<organization>` - the organization maintaining the plugin, just in case we need someone to blame
-*Plugin Goals List and Configuration Parameters for each Goal
+Plugin Goals List and Configuration Parameters for each Goal
+------------------------------------------------------------
- The {{{/plugin-tools/maven-plugin-report-plugin/}Maven Plugin Report Plugin}} is responsible for generating the {{{/plugin-tools/maven-plugin-report-plugin/plugin-info.html}"Plugin Documentation" <<<plugin-info.html>>>}} page
- and one <<<[goal]-mojo.html>>> page for each goal.
+The [Maven Plugin Report Plugin](/plugin-tools/maven-plugin-report-plugin/) is responsible for generating the ["Plugin Documentation" `plugin-info.html`](/plugin-tools/maven-plugin-report-plugin/plugin-info.html) page and one `[goal]-mojo.html` page for each goal.
- It needs to be added to the <<<\<reporting\>>>> section, unless it is already inherited from a parent POM:
+It needs to be added to the `<reporting>` section, unless it is already inherited from a parent POM:
-+--------------+
+```unknown
<project>
[...]
<reporting>
@@ -131,85 +103,77 @@ mvn site
</reporting>
[...]
</project>
-+--------------+
-
- The comments, annotations and plugin goals parameter
- names are extracted from the plugin source and rendered in the "Plugin Documentation" page. In order for the generated site to
- be useful, here are some guidelines for documenting your plugin.
-
- * All <<<...@Parameter>>> fields should have a descriptive comment, informative enough that a regular user can understand.
-
-+--------------+
- [...]
- /**
- * Put something informative here that a regular user can understand.
- */
- @Parameter
- private boolean someparameter;
- [...]
-+--------------+
-
- * If a parameter is not just a simple Java type or a list of simple types, but a specific additional class, give a sample
- XML snippet showing the structure of objects that can be configured.
-
-+--------------+
+```
+
+The comments, annotations and plugin goals parameter names are extracted from the plugin source and rendered in the "Plugin Documentation" page. In order for the generated site to be useful, here are some guidelines for documenting your plugin.
+
+- All `@Parameter` fields should have a descriptive comment, informative enough that a regular user can understand.
+
+ ```unknown
+ [...]
+ /**
+ * Put something informative here that a regular user can understand.
+ */
+ @Parameter
+ private boolean someparameter;
+ [...]
+ ```
+
+- If a parameter is not just a simple Java type or a list of simple types, but a specific additional class, give a sample XML snippet showing the structure of objects that can be configured.
+
+ ```unknown
+ [...]
+ /**
+ * A complex configuration
+ * <pre>
+ * <complexparameter>
+ * <field1>field 1 value</field1>
+ * [...]
+ * </complexparameter>
+ * </pre>
+ */
+ @Parameter
+ private MyComplexObject complexparameter;
+ [...]
+ ```
+
+ The class does not need any specific annotation. `@Parameter` on the `Mojo` field is sufficient to inject a bean instance created from XML configuration.
+
+ See, for example, [`requirementsHistories` parameter documentation](/plugin-tools/maven-plugin-report-plugin/report-mojo.html#requirementsHistories) rendered from [plugin source code](https://github.com/apache/maven-plugin-tools/blob/maven-plugin-tools-3.15.1/maven-plugin-report-plugin/src/main/java/org/apache/maven/plugin/plugin/report/PluginReport.java#L93) and [`RequirementsHistory`](https://github.com/apache/maven-plugin-tools/blob/maven-plugin-tools-3.15.1/maven-plugin-report-pl [...]
+
+- The class level comment should explain what the goal does.
+
+ ```unknown
[...]
/**
- * A complex configuration
- * <pre>
- * <complexparameter>
- * <field1>field 1 value</field1>
- * [...]
- * </complexparameter>
- * </pre>
+ * Everything here will show up on the top of the generated plugin info page.
*/
- @Parameter
- private MyComplexObject complexparameter;
- [...]
-+--------------+
-
- The class does not need any specific annotation. <<<...@Parameter>>> on the <<<Mojo>>> field is sufficient to inject a bean instance created from XML configuration.
-
- See, for example, {{{/plugin-tools/maven-plugin-report-plugin/report-mojo.html#requirementsHistories}<<<requirementsHistories>>> parameter documentation}}
-rendered from {{{https://github.com/apache/maven-plugin-tools/blob/maven-plugin-tools-3.15.1/maven-plugin-report-plugin/src/main/java/org/apache/maven/plugin/plugin/report/PluginReport.java#L93}plugin source code}}
-and {{{https://github.com/apache/maven-plugin-tools/blob/maven-plugin-tools-3.15.1/maven-plugin-report-plugin/src/main/java/org/apache/maven/plugin/plugin/report/RequirementsHistory.java}<<<RequirementsHistory>>>}}
-class,
-
- * The class level comment should explain what the goal does.
-
-+--------------+
-[...]
-/**
- * Everything here will show up on the top of the generated plugin info page.
- */
-@Mojo(name = "somegoal", defaultPhase = LifecyclePhase.COMPILE)
-public class ExampleMojo
- extends AbstractWarMojo
-{
- public void execute()
- throws MojoExecutionException, MojoFailureException
+ @Mojo(name = "somegoal", defaultPhase = LifecyclePhase.COMPILE)
+ public class ExampleMojo
+ extends AbstractWarMojo
{
-[...]
-+--------------+
+ public void execute()
+ throws MojoExecutionException, MojoFailureException
+ {
+ [...]
+ ```
- * The <<<...@Component>>> and <<<readonly>>> parameters are not required to have any comments, but it's still a good practice to provide them.
+- The `@Component` and `readonly` parameters are not required to have any comments, but it's still a good practice to provide them.
-*Site Organization
+Site Organization
+-----------------
- Visibility of the information is also crucial. Uniform navigation links greatly improve the visibility of the
- documentation. The index page can help emphasize important sections and pages of the plugin documentation.
+Visibility of the information is also crucial. Uniform navigation links greatly improve the visibility of the documentation. The index page can help emphasize important sections and pages of the plugin documentation.
-**Site Descriptor
+#[[### Site Descriptor]]#
- The {{{/plugins/maven-site-plugin/examples/sitedescriptor.html}site descriptor}} describes the navigation links and the layout of the page.
- It can be found in <<<src/site/site.xml>>>.
+The [site descriptor](/plugins/maven-site-plugin/examples/sitedescriptor.html) describes the navigation links and the layout of the page. It can be found in `src/site/site.xml`.
- You must define a {{{../../skins/}skin}} if you are using a site descriptor.
- No default skin is applied automatically.
+You must define a [skin](../../skins/) if you are using a site descriptor. No default skin is applied automatically.
- Below is the suggested site descriptor template (with maven-fluido-skin).
+Below is the suggested site descriptor template (with maven-fluido-skin).
-+--------------+
+```unknown
<?xml version="1.0" encoding="UTF-8"?>
<project>
<skin>
@@ -232,172 +196,163 @@ public class ExampleMojo
</menu>
</body>
</project>
-+--------------+
-
-***Navigation Links
-
- * Introduction
-
- The introduction is the front page of the plugin documentation. This is a good place to put any section and pages that need
- to be emphasized. The generated plugin parameter configuration should be linked here. Below is the suggested
- <<<src/site/apt/index.apt>>> template:
-
-----------------
- ------
- Introduction
- ------
- Author
- ------
- YYYY-MM-DD
- ------
-
-
-Plugin Name
-
- Plugin introduction, description, and other relevant information.
-
-* Goals Overview
-
- General information about the goals.
-
- * {{{<goal>.html}prefix:goal}} short description for this plugin goal.
-
-* Usage
-
- General instructions for using the Plugin Name can be found on the {{{usage.html}usage page}}. Some more
- specific use cases are described in the examples given below. Last but not least, users occasionally contribute
- additional examples, tips or errata to the plugin's wiki page.
-
- If you have questions regarding the plugin, consult the {{{faq.html}FAQ}} and feel
- free to contact the {{{mailing-lists.html}user mailing list}}. Posts to the mailing list are archived and might
- already contain the answer to your question. 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, you can file a feature request or bug report in the
- {{{issue-management.html}issue management system}}. 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 help you understand some usages of the Plugin Name,
- you can take a look at the following examples:
-
- * {{{./examples/example-one.html}Example Description One}}
-
- * {{{./examples/example-two.html}Example Description Two}}
-
-----------------
-
- * Goals
-
- <<<plugin-info.html>>> is generated by the Maven Plugin Report Plugin. Until the Maven Site Plugin is updated it would be better to pull it out
- to the main menu for greater visibility. This contains the goals and their descriptions with a link to the configuration parameters.
- The information is based on the comments and annotations of the plugin.
-
- * Usage (this was previously called Howto)
-
- The usage page describes the the basic use cases for the plugin goals which includes sample POM configurations and explanation of
- how the goals work.
-
- * FAQ
-
- A well documented project always collates frequently asked questions which are usually located in <<<src/site/fml/faq.fml>>>.
- The example below provides a template for your FAQ:
-
-+--------------+
-<?xml version="1.0" encoding="UTF-8"?>
-<faqs id="FAQ" title="Frequently Asked Questions">
- <part id="General">
- <faq id="question">
- <question>Question?</question>
- <answer>
- <p>
- Answer
- </p>
- </answer>
- </faq>
- </part>
-</faqs>
-+--------------+
-
- * Examples
-
- Advanced configurations and examples not covered in the usage page are located here. Advanced users who want to maximize the use
- of a plugin can check the items here. Tips on how to use the plugin effectively are also a good thing to put here.
-
- For examples of items under "Examples" check these plugin sites:
-
- * {{{/plugins/maven-javadoc-plugin/}Maven Javadoc Plugin Examples}}
-
- * {{{/plugins/maven-war-plugin/}Maven War Plugin Examples}}
-
-* Recommended Configured Reports
-
- There are 2 recommended report plugins to enhance the plugin documentation, Javadoc and JXR.
-
- * Maven Javadoc Plugin
-
- Javadocs provide documentation that makes it easier for developers to know how to use a particular class. Instead of reading and
- understanding the actual source code, the developer can use the Javadocs instead to lookup the class attributes and methods.
-
- To enable javadoc for your plugin add the following to your <<<pom.xml>>>
-
-+--------------+
-<project>
- [...]
- <build>
- [...]
- </build>
- <reporting>
- <plugins>
- <plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-javadoc-plugin</artifactId>
- <version>$context.get("version.maven-javadoc-plugin")</version>
- <configuration>
- <minmemory>128m</minmemory>
- <maxmemory>512</maxmemory>
- ...
- </configuration>
- </plugin>
- </plugins>
- [...]
- </reporting>
- [...]
-</project>
-+--------------+
-
- Check the documentation about the plugin's {{{/plugins/maven-javadoc-plugin/javadoc-mojo.html}<<<javadoc:javadoc>>>}} goal for the advanced configurations.
-
- * Maven JXR Plugin
-
- The Maven JXR Plugin generates a cross-reference of the project sources. The generated cross-references are also linked to the corresponding
- javadoc if javadoc is generated. The cross-reference is great for those who want to better understand the inner workings of the
- plugin.
-
- To enable source code cross-references, add the following to your <<<pom.xml>>>
-
-+--------------+
-<project>
- [...]
- <build>
- [...]
- </build>
- <reporting>
- <plugins>
- <plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-jxr-plugin</artifactId>
- <version>3.3.1</version>
- </plugin>
- </plugins>
- </reporting>
- [...]
-</project>
-+--------------+
+```
+
+#[[#### Navigation Links]]#
+
+- Introduction
+
+ The introduction is the front page of the plugin documentation. This is a good place to put any section and pages that need to be emphasized. The generated plugin parameter configuration should be linked here. Below is the suggested `src/site/apt/index.apt` template:
+
+ ```
+ ------
+ Introduction
+ ------
+ Author
+ ------
+ YYYY-MM-DD
+ ------
+
+
+ Plugin Name
+
+ Plugin introduction, description, and other relevant information.
+
+ * Goals Overview
+
+ General information about the goals.
+
+ * {{{<goal>.html}prefix:goal}} short description for this plugin goal.
+
+ * Usage
+
+ General instructions for using the Plugin Name can be found on the {{{usage.html}usage page}}. Some more
+ specific use cases are described in the examples given below. Last but not least, users occasionally contribute
+ additional examples, tips or errata to the plugin's wiki page.
+
+ If you have questions regarding the plugin, consult the {{{faq.html}FAQ}} and feel
+ free to contact the {{{mailing-lists.html}user mailing list}}. Posts to the mailing list are archived and might
+ already contain the answer to your question. 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, you can file a feature request or bug report in the
+ {{{issue-management.html}issue management system}}. 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 help you understand some usages of the Plugin Name,
+ you can take a look at the following examples:
+
+ * {{{./examples/example-one.html}Example Description One}}
+
+ * {{{./examples/example-two.html}Example Description Two}}
+
+ ```
+
+- Goals
+
+ `plugin-info.html` is generated by the Maven Plugin Report Plugin. Until the Maven Site Plugin is updated it would be better to pull it out to the main menu for greater visibility. This contains the goals and their descriptions with a link to the configuration parameters. The information is based on the comments and annotations of the plugin.
+
+- Usage (this was previously called Howto)
+
+ The usage page describes the the basic use cases for the plugin goals which includes sample POM configurations and explanation of how the goals work.
+
+- FAQ
+
+ A well documented project always collates frequently asked questions which are usually located in `src/site/fml/faq.fml`. The example below provides a template for your FAQ:
+
+ ```unknown
+ <?xml version="1.0" encoding="UTF-8"?>
+ <faqs id="FAQ" title="Frequently Asked Questions">
+ <part id="General">
+ <faq id="question">
+ <question>Question?</question>
+ <answer>
+ <p>
+ Answer
+ </p>
+ </answer>
+ </faq>
+ </part>
+ </faqs>
+ ```
+
+- Examples
+
+ Advanced configurations and examples not covered in the usage page are located here. Advanced users who want to maximize the use of a plugin can check the items here. Tips on how to use the plugin effectively are also a good thing to put here.
+
+ For examples of items under "Examples" check these plugin sites:
+
+ - [Maven Javadoc Plugin Examples](/plugins/maven-javadoc-plugin/)
+ - [Maven War Plugin Examples](/plugins/maven-war-plugin/)
+
+Recommended Configured Reports
+------------------------------
+
+There are 2 recommended report plugins to enhance the plugin documentation, Javadoc and JXR.
+
+- Maven Javadoc Plugin
+
+ Javadocs provide documentation that makes it easier for developers to know how to use a particular class. Instead of reading and understanding the actual source code, the developer can use the Javadocs instead to lookup the class attributes and methods.
+
+ To enable javadoc for your plugin add the following to your `pom.xml`
+
+ ```unknown
+ <project>
+ [...]
+ <build>
+ [...]
+ </build>
+ <reporting>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-javadoc-plugin</artifactId>
+ <version>$context.get("version.maven-javadoc-plugin")</version>
+ <configuration>
+ <minmemory>128m</minmemory>
+ <maxmemory>512</maxmemory>
+ ...
+ </configuration>
+ </plugin>
+ </plugins>
+ [...]
+ </reporting>
+ [...]
+ </project>
+ ```
+
+ Check the documentation about the plugin's [`javadoc:javadoc`](/plugins/maven-javadoc-plugin/javadoc-mojo.html) goal for the advanced configurations.
+
+- Maven JXR Plugin
+
+ The Maven JXR Plugin generates a cross-reference of the project sources. The generated cross-references are also linked to the corresponding javadoc if javadoc is generated. The cross-reference is great for those who want to better understand the inner workings of the plugin.
+
+ To enable source code cross-references, add the following to your `pom.xml`
+
+ ```unknown
+ <project>
+ [...]
+ <build>
+ [...]
+ </build>
+ <reporting>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-jxr-plugin</artifactId>
+ <version>3.3.1</version>
+ </plugin>
+ </plugins>
+ </reporting>
+ [...]
+ </project>
+ ```
+
+ Check the [JXR configuration page](/plugins/maven-jxr-plugin/jxr-mojo.html) for the possible configuration parameters.
- Check the {{{/plugins/maven-jxr-plugin/jxr-mojo.html}JXR configuration page}} for the possible configuration parameters.
diff --git a/content/markdown/guides/index.md.vm b/content/markdown/guides/index.md.vm
index b74ee298..efbda816 100644
--- a/content/markdown/guides/index.md.vm
+++ b/content/markdown/guides/index.md.vm
@@ -1,172 +1,128 @@
- ------
- Maven Documentation
- ------
- Jason van Zyl
- Eric Redmond
- ------
- 2009-08-01
- ------
-
-~~ 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
-
-Documentation
-
-* User Centre
-
-** Maven Build Fundamentals
-
- * {{{./getting-started/maven-in-five-minutes.html}Getting Started in 5 Minutes}}
-
- * {{{./getting-started/index.html}Getting Started in 30 Minutes}}
-
-** Maven Build Config Fundamentals
-
- * {{{./introduction/introduction-to-the-standard-directory-layout.html}Standard Directory Layout}}
-
- * {{{./introduction/introduction-to-repositories.html}Repositories}}
-
- * {{{./introduction/introduction-to-archetypes.html}What is an Archetype}}
-
- * {{{./mini/guide-creating-archetypes.html}Creating Archetypes}}
-
- * {{{./introduction/introduction-to-dependency-mechanism.html}The Dependency Mechanism}}
-
- * {{{./introduction/introduction-to-optional-and-excludes-dependencies.html} Optional Dependencies and Dependency Exclusions}}
-
- * {{{../glossary.html}Glossary}}
-
-*** Site
-
- * {{{./mini/guide-site.html}Creating a Site}}
-
- * {{{/doxia/references/apt-format.html}The APT Format}}
-
- * {{{./mini/guide-snippet-macro.html}Snippet Macro}}
-
-** Getting Started with Maven
-
- * {{{./introduction/introduction-to-the-lifecycle.html}The Build Lifecycle}}
-
- * {{{./introduction/introduction-to-the-pom.html}The POM}}
-
- * {{{./introduction/introduction-to-profiles.html}Profiles}}
-
- * {{{./mini/guide-configuring-plugins.html}Configuring Plug-ins}}
-
- * {{{../pom.html}POM Overview}} ({{{../ref/current/maven-model/maven.html}Technical Project Descriptor}})
-
- * {{{../settings.html}Settings Overview}} ({{{../ref/current/maven-settings/settings.html}Technical Settings Descriptor}})
-
-* Plugin Developer Centre
-
- * {{{./introduction/introduction-to-plugins.html}Plugin Development}}
-
- * {{{./introduction/introduction-to-plugin-prefix-mapping.html}Plugin Prefix Resolution}}
-
- * {{{./plugin/guide-java-plugin-development.html}Developing Java Plugins}}
-
- * {{{./development/guide-plugin-documentation.html}The Plugin Documentation Standard}}
-
- * {{{./development/guide-testing-development-plugins.html}Testing Development Versions of Plugins}}
-
- * {{{../developers/mojo-api-specification.html}Mojo API}}
-
-* Maven Repository Centre
-
- * {{{./mini/guide-3rd-party-jars-local.html}Installing 3rd party JARs to Local Repository}}
-
- * {{{./mini/guide-3rd-party-jars-remote.html}Deploying 3rd party JARs to Remote Repository}}
-
- * {{{/repository-management.html}Repository Management}}
-
- * {{{./mini/guide-multiple-repositories.html}Using Multiple Repositories}}
-
- * {{{./mini/guide-large-scale-centralized-deployments.html}Large Scale Centralized Deployments}}
-
- * {{{./mini/guide-mirror-settings.html}Mirror Settings}}
-
- * {{{./mini/guide-deployment-security-settings.html}Deployment and Security Settings}}
-
- * {{{./mini/guide-proxies.html}Using Proxies}}
-
- * {{{./mini/guide-repository-ssl.html}Authenticated HTTPS}}
-
- * {{{./mini/guide-repository-ssl.html}Remote repository access through authenticated HTTPS}}
-
- * {{{./mini/guide-relocation.html}Relocation of Artifacts}}
-
-** The Central Repository
-
- * {{{/repository/}Introduction to the Central Repository}}
-
- * {{{/repository/guide-central-repository-upload.html}Uploading Artifacts to the Central Repository}}
-
- * {{{/repository/central-metadata.html}Improving the Repository}}
-
-* Guides
+---
+title: Maven Documentation
+author:
+ - Jason van Zyl
+ - Eric Redmond
+date: 2009-08-01
+---
+
+<!--
+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.
+-->
+
+# Documentation
+
+User Centre
+-----------
+
+#[[### Maven Build Fundamentals]]#
+
+- [Getting Started in 5 Minutes](./getting-started/maven-in-five-minutes.html)
+- [Getting Started in 30 Minutes](./getting-started/index.html)
+#[[### Maven Build Config Fundamentals]]#
+
+- [Standard Directory Layout](./introduction/introduction-to-the-standard-directory-layout.html)
+- [Repositories](./introduction/introduction-to-repositories.html)
+- [What is an Archetype](./introduction/introduction-to-archetypes.html)
+- [Creating Archetypes](./mini/guide-creating-archetypes.html)
+- [The Dependency Mechanism](./introduction/introduction-to-dependency-mechanism.html)
+- [ Optional Dependencies and Dependency Exclusions](./introduction/introduction-to-optional-and-excludes-dependencies.html)
+- [Glossary](../glossary.html)
+#[[#### Site]]#
+
+- [Creating a Site](./mini/guide-site.html)
+- [The APT Format](/doxia/references/apt-format.html)
+- [Snippet Macro](./mini/guide-snippet-macro.html)
+#[[### Getting Started with Maven]]#
+
+- [The Build Lifecycle](./introduction/introduction-to-the-lifecycle.html)
+- [The POM](./introduction/introduction-to-the-pom.html)
+- [Profiles](./introduction/introduction-to-profiles.html)
+- [Configuring Plug-ins](./mini/guide-configuring-plugins.html)
+- [POM Overview](../pom.html) ([Technical Project Descriptor](../ref/current/maven-model/maven.html))
+- [Settings Overview](../settings.html) ([Technical Settings Descriptor](../ref/current/maven-settings/settings.html))
+
+Plugin Developer Centre
+-----------------------
+
+- [Plugin Development](./introduction/introduction-to-plugins.html)
+- [Plugin Prefix Resolution](./introduction/introduction-to-plugin-prefix-mapping.html)
+- [Developing Java Plugins](./plugin/guide-java-plugin-development.html)
+- [The Plugin Documentation Standard](./development/guide-plugin-documentation.html)
+- [Testing Development Versions of Plugins](./development/guide-testing-development-plugins.html)
+- [Mojo API](../developers/mojo-api-specification.html)
+
+Maven Repository Centre
+-----------------------
+
+- [Installing 3rd party JARs to Local Repository](./mini/guide-3rd-party-jars-local.html)
+- [Deploying 3rd party JARs to Remote Repository](./mini/guide-3rd-party-jars-remote.html)
+- [Repository Management](/repository-management.html)
+- [Using Multiple Repositories](./mini/guide-multiple-repositories.html)
+- [Large Scale Centralized Deployments](./mini/guide-large-scale-centralized-deployments.html)
+- [Mirror Settings](./mini/guide-mirror-settings.html)
+- [Deployment and Security Settings](./mini/guide-deployment-security-settings.html)
+- [Using Proxies](./mini/guide-proxies.html)
+- [Authenticated HTTPS](./mini/guide-repository-ssl.html)
+- [Remote repository access through authenticated HTTPS](./mini/guide-repository-ssl.html)
+- [Relocation of Artifacts](./mini/guide-relocation.html)
+#[[### The Central Repository]]#
+
+- [Introduction to the Central Repository](/repository/)
+- [Uploading Artifacts to the Central Repository](/repository/guide-central-repository-upload.html)
+- [Improving the Repository](/repository/central-metadata.html)
+
+Guides
+------
#set( $prefix = './mini' )
#parse( "mini/index.txt" )
- * {{{./mini/guide-bash-m2-completion.html}Maven Auto-Completion Using BASH}}
-
-* Maven Developer Centre
-
- * {{{./development/guide-building-maven.html}Building Maven from Scratch}}
-
- * {{{./development/guide-maven-development.html}Developing Maven}}
-
- * {{{./development/guide-documentation-style.html}Maven Documentation Style}}
-
- * {{{../maven-conventions.html}Maven Conventions}}
-
- * {{{./mini/guide-naming-conventions.html}Naming Conventions}}
-
- * {{{./mini/guide-using-one-source-directory.html}When You Can't Use the Conventions}}
-
-* The Maven Community
-
- * {{{../community.html}The Maven Community}}
-
- * {{{./development/guide-helping.html}Helping with Maven}}
-
- * {{{./mini/guide-new-committers.html}Guide for New Committers}}
-
- * {{{../articles.html}3rd Party Resources}}
-
-* Javadoc API
+- [Maven Auto-Completion Using BASH](./mini/guide-bash-m2-completion.html)
- Here is some useful Javadoc API links to the current version of Maven:
+Maven Developer Centre
+----------------------
- * {{{/ref/current/maven-artifact/apidocs/}Maven Artifact}}
+- [Building Maven from Scratch](./development/guide-building-maven.html)
+- [Developing Maven](./development/guide-maven-development.html)
+- [Maven Documentation Style](./development/guide-documentation-style.html)
+- [Maven Conventions](../maven-conventions.html)
+- [Naming Conventions](./mini/guide-naming-conventions.html)
+- [When You Can't Use the Conventions](./mini/guide-using-one-source-directory.html)
- * {{{/shared/maven-reporting-api/apidocs/}Maven Reporting}}
+The Maven Community
+-------------------
- * {{{/ref/current/maven-plugin-api/apidocs/}Maven Plugin API}}
+- [The Maven Community](../community.html)
+- [Helping with Maven](./development/guide-helping.html)
+- [Guide for New Committers](./mini/guide-new-committers.html)
+- [3rd Party Resources](../articles.html)
- * {{{/ref/current/maven-model/apidocs/}Maven Model}}
+Javadoc API
+-----------
- * {{{/ref/current/maven-core/apidocs/}Maven Core}}
+Here is some useful Javadoc API links to the current version of Maven:
- * {{{/ref/current/maven-settings/apidocs/}Maven Settings}}
+- [Maven Artifact](/ref/current/maven-artifact/apidocs/)
+- [Maven Reporting](/shared/maven-reporting-api/apidocs/)
+- [Maven Plugin API](/ref/current/maven-plugin-api/apidocs/)
+- [Maven Model](/ref/current/maven-model/apidocs/)
+- [Maven Core](/ref/current/maven-core/apidocs/)
+- [Maven Settings](/ref/current/maven-settings/apidocs/)
- []
+You can also browse the [full technical documentation references](/ref/current/) of the current version of Maven.
- You can also browse the {{{/ref/current/}full technical documentation references}} of the current version of Maven.
diff --git a/content/markdown/guides/introduction/introduction-to-plugin-prefix-mapping.md.vm b/content/markdown/guides/introduction/introduction-to-plugin-prefix-mapping.md.vm
index a0ca0a55..a6fc7c50 100644
--- a/content/markdown/guides/introduction/introduction-to-plugin-prefix-mapping.md.vm
+++ b/content/markdown/guides/introduction/introduction-to-plugin-prefix-mapping.md.vm
@@ -1,71 +1,48 @@
- ---
- Introduction to Plugin Prefix Resolution
- ---
- John Casey
- ---
- 2009-08-01
- ------
-
-~~ 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
-
-Introduction to Plugin Prefix Resolution
-
- When you execute Maven using a standard lifecycle phase, resolving the
- plugins that participate in that lifecycle is a relatively simple process.
- However, when you directly invoke a mojo from the command line, as in the case
- of <<clean>>, Maven must have some way of reliably resolving the
- <<clean>> plugin prefix to the <<maven-clean-plugin>>. This provides brevity
- for command-line invocations, while preserving the descriptiveness of the
- plugin's real artifactId.
-
- To complicate matters even more, not all plugins should be forced to have the
- same groupId in the repository. Since groupIds are presumed to be controlled
- by one project, and multiple projects may release plugins for Maven, it
- follows that plugin-prefix mappings must also accommodate multiple plugin
- groupIds.
-
- To address these concerns, Maven provides a new piece of repository-level
- metadata (not associated with any single artifact) for plugin groups, along
- with a plugin mapping manager to organize multiple plugin groups and provide
- search functionality.
-
-* Specifying a Plugin's Prefix
-
- In order to give users a convenient prefix with which to reference your plugin
- a prefix must be associated with your plugin when it is built. By default, Maven
- will make a guess at the plugin-prefix to be used, by removing any instances of
- "maven" or "plugin" surrounded by hyphens in the plugin's artifact ID. The
- conventional artifact ID formats to use are:
-
- * <<<maven-$\{prefix\}-plugin>>> - for official plugins maintained by the Apache Maven team itself (you <<must not>> use this naming pattern for your plugin, see {{{../plugin/guide-java-plugin-development.html#Plugin_Naming_Convention_and_Apache_Maven_Trademark}this note for more informations}})
-
- * <<<$\{prefix\}-maven-plugin>>> - for plugins from other sources
-
- If your plugin's artifactId fits this pattern, Maven will automatically map
- your plugin to the correct prefix in the metadata stored within your plugin's
- groupId path on the repository. However, if you want to customize the prefix
- used to reference your plugin, you can specify the prefix directly through a
- configuration parameter on the <<<maven-plugin-plugin>>> in your plugin's POM:
-
-+---+
+---
+title: Introduction to Plugin Prefix Resolution
+author:
+ - John Casey
+date: 2009-08-01
+---
+
+<!--
+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.
+-->
+
+# Introduction to Plugin Prefix Resolution
+
+When you execute Maven using a standard lifecycle phase, resolving the plugins that participate in that lifecycle is a relatively simple process. However, when you directly invoke a mojo from the command line, as in the case of **clean**, Maven must have some way of reliably resolving the **clean** plugin prefix to the **maven-clean-plugin**. This provides brevity for command-line invocations, while preserving the descriptiveness of the plugin's real artifactId.
+
+To complicate matters even more, not all plugins should be forced to have the same groupId in the repository. Since groupIds are presumed to be controlled by one project, and multiple projects may release plugins for Maven, it follows that plugin-prefix mappings must also accommodate multiple plugin groupIds.
+
+To address these concerns, Maven provides a new piece of repository-level metadata (not associated with any single artifact) for plugin groups, along with a plugin mapping manager to organize multiple plugin groups and provide search functionality.
+
+Specifying a Plugin's Prefix
+----------------------------
+
+In order to give users a convenient prefix with which to reference your plugin a prefix must be associated with your plugin when it is built. By default, Maven will make a guess at the plugin-prefix to be used, by removing any instances of "maven" or "plugin" surrounded by hyphens in the plugin's artifact ID. The conventional artifact ID formats to use are:
+
+- `maven-${esc.d}{prefix}-plugin` - for official plugins maintained by the Apache Maven team itself (you **must not** use this naming pattern for your plugin, see [this note for more informations](../plugin/guide-java-plugin-development.html#Plugin_Naming_Convention_and_Apache_Maven_Trademark))
+- `${esc.d}{prefix}-maven-plugin` - for plugins from other sources
+
+If your plugin's artifactId fits this pattern, Maven will automatically map your plugin to the correct prefix in the metadata stored within your plugin's groupId path on the repository. However, if you want to customize the prefix used to reference your plugin, you can specify the prefix directly through a configuration parameter on the `maven-plugin-plugin` in your plugin's POM:
+
+```unknown
<project>
...
<build>
@@ -83,85 +60,55 @@ Introduction to Plugin Prefix Resolution
</plugins>
</build>
</project>
-+---+
+```
- The above configuration will allow users to refer to your plugin by the prefix
- <<somePrefix>>, as in the following example:
+The above configuration will allow users to refer to your plugin by the prefix **somePrefix**, as in the following example:
------
+```
mvn somePrefix:goal
------
+```
-* Mapping Prefixes to Plugins
+Mapping Prefixes to Plugins
+---------------------------
- For each groupId configured for searching, Maven will:
+For each groupId configured for searching, Maven will:
- [[1]] Download <<<maven-metadata.xml>>> from each remote repository into the local repository,
- and name it <<<maven-metadata-$\{repoId\}.xml>>> within the path of $\{groupId\}.
+1. Download `maven-metadata.xml` from each remote repository into the local repository, and name it `maven-metadata-${esc.d}{repoId}.xml` within the path of ${esc.d}{groupId}.
+1. Load these metadata files, along with `maven-metadata-local.xml` (if it exists), within the path of ${esc.d}{groupId}. Merge them.
+1. Lookup the plugin prefix in the merged metadata. If it's mapped, it should refer to a concrete groupId-artifactId pair. Otherwise, go on to #1 for the next groupId in the user's plugin-groups.
- [[2]] Load these metadata files, along with <<<maven-metadata-local.xml>>> (if it exists),
- within the path of $\{groupId\}. Merge them.
+These metadata files consist of the **groupId** it represents (for clarity when the file is opened outside the context of the directory), and a group of **plugin** elements. Each **plugin** in this list contains a **prefix** element denoting the plugin's command-line prefix, and an **artifactId** element, which provides the other side of the prefix mapping and provides enough information to lookup and use the plugin. When a plugin is installed or deployed, the appropriate metadata file i [...]
- [[3]] Lookup the plugin prefix in the merged metadata. If it's mapped, it should refer to
- a concrete groupId-artifactId pair. Otherwise, go on to #1 for the next groupId in the
- user's plugin-groups.
+Configuring Maven to Search for Plugins
+---------------------------------------
- []
+By default, Maven will search the groupId **org.apache.maven.plugins** for prefix-to-artifactId mappings for the plugins it needs to perform a given build. However, as previously mentioned, the user may have a need for third-party plugins. Since the Maven project is assumed to have control over the default plugin groupId, this means configuring Maven to search other groupId locations for plugin-prefix mappings.
- These metadata files consist of the <<groupId>> it represents (for clarity when
- the file is opened outside the context of the directory), and a group of
- <<plugin>> elements. Each <<plugin>> in this list contains a <<prefix>>
- element denoting the plugin's command-line prefix, and an <<artifactId>>
- element, which provides the other side of the prefix mapping and provides
- enough information to lookup and use the plugin. When a plugin is installed
- or deployed, the appropriate metadata file is located - and if the prefix
- mapping is missing - modified to include the plugin-prefix mapping.
+As it turns out, this is simple. In the Maven settings file (per-user: `${esc.d}{user.home}/.m2/settings.xml`; global: `${esc.d}{maven.home}/conf/settings.xml`), you can provide a custom **pluginGroups** section, listing the plugin groupIds you want to search (each groupId goes in its own **pluginGroup** sub-element). For example, if my project uses a Modello model file, I might have the following in my settings:
-* Configuring Maven to Search for Plugins
-
- By default, Maven will search the groupId <<org.apache.maven.plugins>>
- for prefix-to-artifactId mappings for the plugins it needs to perform a given
- build. However, as previously mentioned, the user may have a need for
- third-party plugins. Since the Maven project is assumed to have control over
- the default plugin groupId, this means configuring Maven to search other
- groupId locations for plugin-prefix mappings.
-
- As it turns out, this is simple. In the Maven settings file (per-user:
- <<<$\{user.home\}/.m2/settings.xml>>>; global: <<<$\{maven.home\}/conf/settings.xml>>>), you can
- provide a custom <<pluginGroups>> section, listing the plugin groupIds you
- want to search (each groupId goes in its own <<pluginGroup>> sub-element).
- For example, if my project uses a Modello model file, I might have the
- following in my settings:
-
-+---+
+```unknown
<pluginGroups>
<pluginGroup>org.codehaus.modello</pluginGroup>
</pluginGroups>
-+---+
+```
- This allows me to execute the following, which will generate Java classes
- from the model:
+This allows me to execute the following, which will generate Java classes from the model:
------
+```
mvn -Dversion=4.0.0 -Dmodel=maven.mdo modello:java
------
-
- Maven will always search the following groupId's <<after>> searching any plugin groups
- specified in the user's settings:
+```
- * org.apache.maven.plugins
+Maven will always search the following groupId's **after** searching any plugin groups specified in the user's settings:
- * org.codehaus.mojo
+- org.apache.maven.plugins
+- org.codehaus.mojo
- []
+**NOTE:** When specifying plugin groups to be used in searching for a prefix mapping, order is critical\! By specifying a pluginGroup of `com.myco.plugins` with a prefix of `clean`, I can override the usage of the `maven-clean-plugin` when `clean:clean` is invoked.
- <<NOTE:>> When specifying plugin groups to be used in searching for a prefix mapping,
- order is critical! By specifying a pluginGroup of <<<com.myco.plugins>>> with a prefix
- of <<<clean>>>, I can override the usage of the <<<maven-clean-plugin>>> when
- <<<clean:clean>>> is invoked.
+**NOTE2:** For more information on `settings.xml`, see \[[1](#a1)\].
- <<NOTE2:>> For more information on <<<settings.xml>>>, see \[{{{a1}1}}\].
+Resources
+---------
-*Resources
+<a id="a1"></a>1 [Guide to Configuring Maven](../mini/guide-configuring-maven.html)
- {1} {{{../mini/guide-configuring-maven.html}Guide to Configuring Maven}}
diff --git a/content/markdown/guides/mini/index.md.vm b/content/markdown/guides/mini/index.md.vm
index be721d02..7546cafb 100644
--- a/content/markdown/guides/mini/index.md.vm
+++ b/content/markdown/guides/mini/index.md.vm
@@ -1,32 +1,31 @@
- ------
- Maven Mini Guides
- ------
- Jason van Zyl
- ------
- 2005-10-12
- ------
-
-~~ 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.
+---
+title: Maven Mini Guides
+author:
+ - Jason van Zyl
+date: 2005-10-12
+---
-~~ NOTE: For help with the syntax of this file, see:
-~~ http://maven.apache.org/doxia/references/apt-format.html
+<!--
+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
-Maven Mini Guides
+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.
+-->
+
+# Maven Mini Guides
#set( $prefix = '.' )
#parse( "index.txt" )
+
diff --git a/content/markdown/guides/mini/index.txt b/content/markdown/guides/mini/index.txt
new file mode 100644
index 00000000..fb0bf472
--- /dev/null
+++ b/content/markdown/guides/mini/index.txt
@@ -0,0 +1,36 @@
+<!--
+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.
+** Testing
+* {{{$prefix/guide-attached-tests.html}Reusable Test JARs}}
+-->
+
+- [Configuring for Reproducible Builds]($prefix/guide-reproducible-builds.html)
+- [Creating Assemblies]($prefix/guide-assemblies.html)
+- [Configuring Archive Plugins]($prefix/guide-archive-configuration.html)
+- [Configuring Maven]($prefix/guide-configuring-maven.html)
+- [Generating Sources]($prefix/guide-generating-sources.html)
+- [Working with Manifests]($prefix/guide-manifest.html)
+- [Maven Classloading]($prefix/guide-maven-classloading.html)
+- [Using Multiple Modules in a Build]($prefix/guide-multiple-modules.html)
+- [Using the Release Plugin]($prefix/guide-releasing.html)
+- [Using Ant with Maven]($prefix/guide-using-ant.html)
+- [Using Modello]($prefix/guide-using-modello.html)
+- [Using Extensions]($prefix/guide-using-extensions.html)
+- [Building For Different Environments]($prefix/guide-building-for-different-environments.html)
+- [Using Toolchains]($prefix/guide-using-toolchains.html)
+- [Injecting POM Properties via settings.xml](/examples/injecting-properties-via-settings.html)
diff --git a/content/markdown/guides/plugin/guide-java-plugin-development.md.vm b/content/markdown/guides/plugin/guide-java-plugin-development.md.vm
index d899f97a..f4387bb8 100644
--- a/content/markdown/guides/plugin/guide-java-plugin-development.md.vm
+++ b/content/markdown/guides/plugin/guide-java-plugin-development.md.vm
@@ -1,74 +1,62 @@
- ------
- Guide to Developing Java Plugins
- ------
- Bob Allison
- Vincent Siveton
- Olivier Lamy
- ------
- 2013-01-02
- ------
+---
+title: Guide to Developing Java Plugins
+author:
+ - Bob Allison
+ - Vincent Siveton
+ - Olivier Lamy
+date: 2013-01-02
+---
-~~ 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.
+<!--
+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
-~~ NOTE: For help with the syntax of this file, see:
-~~ http://maven.apache.org/doxia/references/apt-format.html
+http://www.apache.org/licenses/LICENSE-2.0
-Guide to Developing Java Plugins
+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 guide is intended to assist users in developing Java plugins for
- Maven.
+# Guide to Developing Java Plugins
-%{toc|fromDepth=2}
+This guide is intended to assist users in developing Java plugins for Maven.
-* Important Notice
+<!-- MACRO{toc|fromDepth=2} -->
- {{{../mini/guide-naming-conventions.html}<<Plugin Naming Convention and Apache Maven Trademark>>}}
+Important Notice
+----------------
- You will typically name your plugin <<<<yourplugin>-maven-plugin>>>.
+[**Plugin Naming Convention and Apache Maven Trademark**](../mini/guide-naming-conventions.html)
- Calling it <<<maven-<yourplugin>-plugin>>> (note "Maven" is at the beginning
- of the plugin name) is <<strongly discouraged>> since it's a
- <<reserved naming pattern for official Apache Maven plugins maintained by the Apache Maven team>>
- with groupId <<<org.apache.maven.plugins>>>.
+You will typically name your plugin `<yourplugin>-maven-plugin`.
- Using this naming pattern is an infringement of the Apache Maven Trademark.
+Calling it `maven-<yourplugin>-plugin` (note "Maven" is at the beginning of the plugin name) is **strongly discouraged** since it's a **reserved naming pattern for official Apache Maven plugins maintained by the Apache Maven team** with groupId `org.apache.maven.plugins`.
-* Your First Plugin
+Using this naming pattern is an infringement of the Apache Maven Trademark.
- In this section we will build a simple plugin with one goal that takes no parameters
- and displays a message on the screen when run. Along the way, we
- will cover setting up a project to create a plugin, the
- minimal contents of a Java mojo which will define goal code, and a couple ways to execute the mojo.
+Your First Plugin
+-----------------
-** Your First Mojo
+In this section we will build a simple plugin with one goal that takes no parameters and displays a message on the screen when run. Along the way, we will cover setting up a project to create a plugin, the minimal contents of a Java mojo which will define goal code, and a couple ways to execute the mojo.
- At its simplest, a Java mojo consists simply of a single class representing one plugin's goal.
- When processing the source tree to find mojos, {{{/plugin-tools/} <<<plugin-tools>>>}}
- looks for classes with the <<<...@Mojo>>> annotation.
- Any class with this annotation is included in the plugin configuration file.
+#[[### Your First Mojo]]#
-*** A Simple Mojo
+At its simplest, a Java mojo consists simply of a single class representing one plugin's goal. When processing the source tree to find mojos, [ `plugin-tools`](/plugin-tools/) looks for classes with the `@Mojo` annotation. Any class with this annotation is included in the plugin configuration file.
- Listed below is a simple mojo class which has no parameters. This is
- about as simple as a mojo can be. After the listing is a description
- of the various parts of the source.
+#[[#### A Simple Mojo]]#
-+---+
+Listed below is a simple mojo class which has no parameters. This is about as simple as a mojo can be. After the listing is a description of the various parts of the source.
+
+```unknown
package sample.plugin;
import org.apache.maven.plugin.AbstractMojo;
@@ -88,52 +76,30 @@ public class GreetingMojo extends AbstractMojo
getLog().info("Hello, world.");
}
}
-+---+
-
- * The class <<<org.apache.maven.plugin.AbstractMojo>>> provides most of the
- infrastructure required to implement a mojo except for the
- <<<execute>>> method.
-
- * The annotation "<<<...@Mojo>>>" is required and controls how and
- when the mojo is executed.
-
- * The <<<execute>>> method can throw <<<org.apache.maven.plugin.MojoExecutionException>>> if a problem occurs.
- Throwing this exception causes a <<<BUILD FAILURE>>> message to be displayed.
-
- * The <<<getLog>>> method (defined in <<<AbstractMojo>>>) returns a
- log4j-like logger object which allows plugins to create messages at levels
- of "debug", "info", "warn", and "error". This logger is the accepted means
- to display information to the user. See
- {{{../../plugin-developers/common-bugs.html#Retrieving_the_Mojo_Logger}Retrieving the Mojo Logger}} for a hint on
- its proper usage.
+```
- []
+- The class `org.apache.maven.plugin.AbstractMojo` provides most of the infrastructure required to implement a mojo except for the `execute` method.
+- The annotation "`@Mojo`" is required and controls how and when the mojo is executed.
+- The `execute` method can throw `org.apache.maven.plugin.MojoExecutionException` if a problem occurs. Throwing this exception causes a `BUILD FAILURE` message to be displayed.
+- The `getLog` method (defined in `AbstractMojo`) returns a log4j-like logger object which allows plugins to create messages at levels of "debug", "info", "warn", and "error". This logger is the accepted means to display information to the user. See [Retrieving the Mojo Logger](../../plugin-developers/common-bugs.html#Retrieving_the_Mojo_Logger) for a hint on its proper usage.
- All Mojo annotations are described by the {{{../../developers/mojo-api-specification.html#The_Descriptor_and_Annotations}Mojo API Specification}}.
+All Mojo annotations are described by the [Mojo API Specification](../../developers/mojo-api-specification.html#The_Descriptor_and_Annotations).
-** Project Definition
+#[[### Project Definition]]#
- Once the mojos have been written for the plugin, it is time to
- build the plugin. To do this properly, the project's pom.xml
- must set these things:
+Once the mojos have been written for the plugin, it is time to build the plugin. To do this properly, the project's pom.xml must set these things:
-*------------------+----------------------------------------------------------+
-|<<<groupId>>> |This is the group ID for the plugin, and should match the |
-| |common prefix to the packages used by the mojos. |
-*------------------+----------------------------------------------------------+
-|<<<artifactId>>> |This is the name of the plugin. |
-*------------------+----------------------------------------------------------+
-|<<<version>>> |This is the version of the plugin. |
-*------------------+----------------------------------------------------------+
-|<<<packaging>>> |This must be set to "<<<maven-plugin>>>" |
-*------------------+----------------------------------------------------------+
-|<<<dependencies>>>|A dependency must be declared on the Maven Plugin Tools |
-| |API to resolve "<<<AbstractMojo>>>" and related classes |
-*------------------+----------------------------------------------------------+
+| | |
+|:---|:---|
+|`groupId`|This is the group ID for the plugin, and should match the common prefix to the packages used by the mojos.|
+|`artifactId`|This is the name of the plugin.|
+|`version`|This is the version of the plugin.|
+|`packaging`|This must be set to "`maven-plugin`"|
+|`dependencies`|A dependency must be declared on the Maven Plugin Tools API to resolve "`AbstractMojo`" and related classes|
- Listed below is an illustration of the sample mojo project's pom with the parameters set as described in the above table:
+Listed below is an illustration of the sample mojo project's pom with the parameters set as described in the above table:
-+----+
+```unknown
<project>
<modelVersion>4.0.0</modelVersion>
@@ -197,37 +163,28 @@ public class GreetingMojo extends AbstractMojo
</plugins>
</reporting>
</project>
-+----+
+```
-** Building a Plugin
+#[[### Building a Plugin]]#
- There are few plugin goals bound to the standard build lifecycle
- defined with the <<<maven-plugin>>> packaging:
+There are few plugin goals bound to the standard build lifecycle defined with the `maven-plugin` packaging:
-*-------------+----------------------------------------------------+
-|<<<compile>>>|Compiles the Java code for the plugin |
-*-------------+----------------------------------------------------+
-|<<<process-classes>>>|Extracts data to build the {{{/ref/current/maven-plugin-api/plugin.html}plugin descriptor}}|
-*-------------+----------------------------------------------------+
-|<<<test>>> |Runs the plugin's unit tests |
-*-------------+----------------------------------------------------+
-|<<<package>>>|Builds the plugin jar |
-*-------------+----------------------------------------------------+
-|<<<install>>>|Installs the plugin jar in the local repository |
-*-------------+----------------------------------------------------+
-|<<<deploy>>> |Deploys the plugin jar to the remote repository |
-*-------------+----------------------------------------------------+
+| | |
+|:---|:---|
+|`compile`|Compiles the Java code for the plugin|
+|`process-classes`|Extracts data to build the [plugin descriptor](/ref/current/maven-plugin-api/plugin.html)|
+|`test`|Runs the plugin's unit tests|
+|`package`|Builds the plugin jar|
+|`install`|Installs the plugin jar in the local repository|
+|`deploy`|Deploys the plugin jar to the remote repository|
- For more details, you can look at
- {{{/ref/current/maven-core/default-bindings.html#Plugin_bindings_for_maven-plugin_packaging} detailed bindings for <<<maven-plugin>>> packaging}}.
+For more details, you can look at [ detailed bindings for `maven-plugin` packaging](/ref/current/maven-core/default-bindings.html#Plugin_bindings_for_maven-plugin_packaging).
-** Executing Your First Mojo
+#[[### Executing Your First Mojo]]#
- The most direct means of executing your new plugin is to specify the
- plugin goal directly on the command line. To do this,
- configure the <<<hello-maven-plugin>>> plugin in the project:
+The most direct means of executing your new plugin is to specify the plugin goal directly on the command line. To do this, configure the `hello-maven-plugin` plugin in the project:
-+----+
+```unknown
<project>
...
<build>
@@ -243,56 +200,39 @@ public class GreetingMojo extends AbstractMojo
</build>
...
</project>
-+----+
+```
- Then on the command line specify a fully-qualified goal in the form of:
+Then on the command line specify a fully-qualified goal in the form of:
-------
+```
mvn groupId:artifactId:version:goal
-------
+```
- For example, to run the simple mojo in the sample plugin, enter
- "<<<mvn sample.plugin:hello-maven-plugin:1.0-SNAPSHOT:sayhi>>>" on the
- command line.
+For example, to run the simple mojo in the sample plugin, enter "`mvn sample.plugin:hello-maven-plugin:1.0-SNAPSHOT:sayhi`" on the command line.
- <<Tips>>: <<<version>>> is not required to run a standalone goal.
+**Tips**: `version` is not required to run a standalone goal.
-*** Shortening the Command Line
+#[[#### Shortening the Command Line]]#
- There are several ways to reduce the amount of required typing:
+There are several ways to reduce the amount of required typing:
- * To run the latest version of a plugin installed in the local
- repository, you can omit its version number. So just use
- "<<<mvn sample.plugin:hello-maven-plugin:sayhi>>>" to run your plugin.
+- To run the latest version of a plugin installed in the local repository, you can omit its version number. So just use "`mvn sample.plugin:hello-maven-plugin:sayhi`" to run your plugin.
+- You can assign a shortened prefix to your plugin, such as `mvn hello:sayhi`. This is done automatically if you follow the convention of using `${esc.d}{prefix}-maven-plugin` (or `maven-${esc.d}{prefix}-plugin` if the plugin is part of the Apache Maven project). You may also assign one through additional configuration. For more information, see [ Introduction to Plugin Prefix Mapping](../introduction/introduction-to-plugin-prefix-mapping.html).
+- Finally, you can also add your plugin's group ID to the list of group IDs searched by default. To do this, add the following to your `${esc.d}{user.home}/.m2/settings.xml` file:
- * You can assign a shortened prefix to your plugin, such as <<<mvn hello:sayhi>>>.
- This is done automatically if you follow the convention of using
- <<<$\{prefix\}-maven-plugin>>> (or <<<maven-$\{prefix\}-plugin>>> if the plugin is
- part of the Apache Maven project). You may also assign one through additional
- configuration. For more information, see
- {{{../introduction/introduction-to-plugin-prefix-mapping.html} Introduction to Plugin Prefix Mapping}}.
+ ```unknown
+ <pluginGroups>
+ <pluginGroup>sample.plugin</pluginGroup>
+ </pluginGroups>
+ ```
- * Finally, you can also add your plugin's group ID to the list of group IDs
- searched by default. To do this, add the following to
- your <<<$\{user.home\}/.m2/settings.xml>>> file:
+At this point, you can run the mojo with "`mvn hello:sayhi`".
-+----+
-<pluginGroups>
- <pluginGroup>sample.plugin</pluginGroup>
-</pluginGroups>
-+----+
+#[[#### Attaching the Mojo to the Build Lifecycle]]#
- []
+You can also configure the plugin to attach specific goals to a particular phase of the build lifecycle. Here is an example:
- At this point, you can run the mojo with "<<<mvn hello:sayhi>>>".
-
-
-*** Attaching the Mojo to the Build Lifecycle
-
- You can also configure the plugin to attach specific goals to a particular
- phase of the build lifecycle. Here is an example:
-
-+-----+
+```unknown
<build>
<pluginManagement>
<plugins>
@@ -318,69 +258,49 @@ mvn groupId:artifactId:version:goal
</plugin>
</plugins>
</build>
-+-----+
+```
- This causes the simple mojo to be executed whenever Java code is compiled.
- For more information on binding a mojo to phases in the lifecycle,
- see the {{{../introduction/introduction-to-the-lifecycle.html}Build Lifecycle}} document.
+This causes the simple mojo to be executed whenever Java code is compiled. For more information on binding a mojo to phases in the lifecycle, see the [Build Lifecycle](../introduction/introduction-to-the-lifecycle.html) document.
-* Mojo archetype
+Mojo archetype
+--------------
- To create a new plugin project, you can use the Mojo
- {{{../introduction/introduction-to-archetypes.html}archetype}} with the following command line:
+To create a new plugin project, you can use the Mojo [archetype](../introduction/introduction-to-archetypes.html) with the following command line:
------
+```
mvn archetype:generate \
-DgroupId=sample.plugin \
-DartifactId=hello-maven-plugin \
-DarchetypeGroupId=org.apache.maven.archetypes \
-DarchetypeArtifactId=maven-archetype-plugin
------
-
-* Parameters
+```
- It is unlikely that a mojo will be very useful without parameters.
- Parameters provide a few very important functions:
+Parameters
+----------
- * They provide hooks to allow the user to adjust the operation of the
- plugin to suit their needs.
+It is unlikely that a mojo will be very useful without parameters. Parameters provide a few very important functions:
- * They provide a means to easily extract the value of elements from
- the POM without the need to navigate the objects.
+- They provide hooks to allow the user to adjust the operation of the plugin to suit their needs.
+- They provide a means to easily extract the value of elements from the POM without the need to navigate the objects.
+#[[### Defining Parameters Within a Mojo]]#
- []
+Defining a parameter is as simple as creating an instance variable in the mojo and adding the proper annotations. Listed below is an example of a parameter for the simple mojo:
-** Defining Parameters Within a Mojo
-
- Defining a parameter is as simple as creating an instance variable
- in the mojo and adding the proper annotations. Listed below is an
- example of a parameter for the simple mojo:
-
-+-----+
+```unknown
/**
* The greeting to display.
*/
@Parameter(property = "sayhi.greeting", defaultValue = "Hello World!" )
private String greeting;
-+-----+
+```
- The Javadoc comment is the description of the
- parameter. The <<<...@Parameter>>> annotation identifies
- the variable as a mojo parameter. The <<<defaultValue>>>
- element defines the default value for the parameter. This value can
- include expressions which reference the project, such as
- "<<<$\{project.version\}>>>". (More can be found in the
- {{{/ref/current/maven-core/apidocs/org/apache/maven/plugin/PluginParameterExpressionEvaluator.html}"Parameter Expressions" document.}})
- The <<<property>>> element enables configuration
- of the mojo parameter from the command line by referencing a system property that the user sets
- via the <<<-D>>> option.
+The Javadoc comment is the description of the parameter. The `@Parameter` annotation identifies the variable as a mojo parameter. The `defaultValue` element defines the default value for the parameter. This value can include expressions which reference the project, such as "`${esc.d}{project.version}`". (More can be found in the ["Parameter Expressions" document.](/ref/current/maven-core/apidocs/org/apache/maven/plugin/PluginParameterExpressionEvaluator.html)) The `property` element enab [...]
-** Configuring Parameters in a Project
+#[[### Configuring Parameters in a Project]]#
- Each Maven project can configure the plugins it uses
- in the <<<pluginManagement>>> section of the pom.xml. For example:
+Each Maven project can configure the plugins it uses in the `pluginManagement` section of the pom.xml. For example:
-+-----+
+```unknown
<plugin>
<groupId>sample.plugin</groupId>
<artifactId>hello-maven-plugin</artifactId>
@@ -389,27 +309,20 @@ mvn archetype:generate \
<greeting>Welcome</greeting>
</configuration>
</plugin>
-+-----+
-
- In the configuration section, the element name
- ("<<<greeting>>>") is the parameter name and the content of
- the element ("<<<Welcome>>>") is the value to be assigned to
- the parameter.
+```
- <<Note>>: More details can be found in the
- {{{../mini/guide-configuring-plugins.html}Guide to Configuring Plugins}}.
+In the configuration section, the element name ("`greeting`") is the parameter name and the content of the element ("`Welcome`") is the value to be assigned to the parameter.
-* Using Setters
+**Note**: More details can be found in the [Guide to Configuring Plugins](../mini/guide-configuring-plugins.html).
- You are not restricted to using private field mapping which is helpful
- if you are trying to make your Mojos reusable outside the context of Maven.
- In the example above, we could define public setter methods that the configuration mapping mechanism can use.
- You can also add an <<<...@Parameter>>> annotation on the setter method (from version 3.7.0 of `plugin-tools`)
+Using Setters
+-------------
+You are not restricted to using private field mapping which is helpful if you are trying to make your Mojos reusable outside the context of Maven. In the example above, we could define public setter methods that the configuration mapping mechanism can use. You can also add an `@Parameter` annotation on the setter method (from version 3.7.0 of \`plugin-tools\`)
- So the Mojo would look like the following:
+So the Mojo would look like the following:
-+----+
+```unknown
public class MyQueryMojo extends AbstractMojo {
@@ -443,27 +356,20 @@ public class MyQueryMojo extends AbstractMojo {
...
}
}
+```
-+----+
-
- The property annotation for each parameter tells Maven which setter and getter to use when
- the field's name does not match the name of the parameter in the plugin configuration.
-
-* Plugin Documentation
-
- To make it easy for others to use your plugin, you should document it. See the {{{../development/guide-plugin-documentation.html}Plugin Documentation Guide}}
- for more information.
-
-* Resources
-
- [[1]] {{{../../developers/mojo-api-specification.html}Mojo Documentation}}: Mojo API, Mojo annotations
-
- [[2]] {{{/shared/maven-plugin-testing-harness/}Maven Plugin Testing Harness}}: Testing framework for your Mojos.
+The property annotation for each parameter tells Maven which setter and getter to use when the field's name does not match the name of the parameter in the plugin configuration.
- [[3]] {{{https://eclipse.dev/sisu/index.html}Eclipse Sisu}}: The IoC container used by Maven 3.
+Plugin Documentation
+--------------------
- [[4]] {{{../../maven-jsr330.html}Maven & JSR 330}}: How to use JSR 330 in Plugins
+To make it easy for others to use your plugin, you should document it. See the [Plugin Documentation Guide](../development/guide-plugin-documentation.html) for more information.
- [[5]] {{{../../plugin-developers/common-bugs.html}Common Bugs and Pitfalls}}: Overview of problematic coding patterns.
+Resources
+---------
- []
+1. [Mojo Documentation](../../developers/mojo-api-specification.html): Mojo API, Mojo annotations
+1. [Maven Plugin Testing Harness](/shared/maven-plugin-testing-harness/): Testing framework for your Mojos.
+1. [Eclipse Sisu](https://eclipse.dev/sisu/index.html): The IoC container used by Maven 3.
+1. [Maven & JSR 330](../../maven-jsr330.html): How to use JSR 330 in Plugins
+1. [Common Bugs and Pitfalls](../../plugin-developers/common-bugs.html): Overview of problematic coding patterns.
diff --git a/content/markdown/guides/plugin/guide-java-report-plugin-development.md.vm b/content/markdown/guides/plugin/guide-java-report-plugin-development.md.vm
index 2988be85..82175814 100644
--- a/content/markdown/guides/plugin/guide-java-report-plugin-development.md.vm
+++ b/content/markdown/guides/plugin/guide-java-report-plugin-development.md.vm
@@ -1,150 +1,106 @@
- ------
- Guide to Developing Java Report Plugins
- ------
- Hervé Boutemy
- Bertrand Martin
- ------
- 2018-01-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.
-
-~~ NOTE: For help with the syntax of this file, see:
-~~ http://maven.apache.org/doxia/references/apt-format.html
-
-Introduction
-
- This guide is intended to assist users in developing reporting plugins for
- Maven in Java, that will contribute to sites generated by {{{/plugins/maven-site-plugin/}<<<maven-site-plugin>>>}}
- or site PDF documents generated by {{{/plugins/maven-pdf-plugin/}<<<maven-pdf-site>>>}}.
-
- First and foremost, a <report plugin> is a <Maven plugin> and it is strongly advised to first read the
- {{{./guide-java-plugin-development.html}Guide to Developing Java Plugins}} to properly understand
- its core mechanisms.
-
- A plugin is actually not a <report plugin> in itself. But one (or several) of its goals or <Mojos> may be
- specialized to be invoked by {{{/plugins/maven-site-plugin/}<<<maven-site-plugin>>>}}, typically during the
- <<<site>>> build life cycle.
-
- A Maven plugin can therefore implement <regular> goals and <report> goals. The below details how to write a <Mojo>
- that will get invoked as a <report> by {{{/plugins/maven-site-plugin/}<<<maven-site-plugin>>>}}.
-
-* How It Works
-
- [[1]]
- A regular Maven project usually invokes <reporting goals> of a plugin by declaring such plugin in the
- {{{/plugins/maven-site-plugin/examples/configuring-reports.html}<<<<reporting\>>>>}} section of its <<<pom.xml>>> as in the example below:
-
-+---+
-<project>
- ...
- <reporting>
- <plugins>
- <plugin>
- <groupId>com.mycompany.maven</groupId>
- <artifactId>simple-maven-plugin</artifactId>
- <version>1.0-SNAPSHOT</version>
- </plugin>
- </plugins>
- </reporting>
- ...
-+---+
-
- [[2]]
- When {{{/plugins/maven-site-plugin/}<<<maven-site-plugin>>>}} is invoked (for example with the <<<mvn site>>> command),
- the specified plugins are loaded and the <<<generate()>>> method of each Mojo class that implements
- {{{/shared/maven-reporting-api/apidocs/org/apache/maven/reporting/MavenReport.html}<<<MavenReport>>>}}
- is executed.
-
- [[3]]
- The <<<generate()>>> method generates a document through Maven's {{{/doxia/doxia/doxia-sink-api/}Doxia Sink API}}.
- This document is comprised of basic elements like title, headings, text, links, tables, etc.
- This is where you will put the logic of your report, assembling elements, based on the content of the Maven project.
+---
+title: Guide to Developing Java Report Plugins
+author:
+ - Hervé Boutemy
+ - Bertrand Martin
+date: 2018-01-21
+---
- [[4]]
- These document elements are passed to Doxia to generate an HTML document, which itself gets wrapped into a {{{/skins/}Maven Skin}},
- as specified in the projects {{{/guides/mini/guide-site.html}<<<./src/site/site.xml>>>}}.
+<!--
+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
- [[5]]
- The result produces an HTML file in the <<<./target/site>>> directory of your project.
+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.
+-->
- {{{/doxia/doxia-sitetools/doxia-site-renderer/}More details about Doxia Site Renderer}}
+# Introduction
-* Basic Requirements of a Report <Mojo>
+This guide is intended to assist users in developing reporting plugins for Maven in Java, that will contribute to sites generated by [`maven-site-plugin`](/plugins/maven-site-plugin/) or site PDF documents generated by [`maven-pdf-site`](/plugins/maven-pdf-plugin/).
- Each goal or <Mojo> is implemented with a separate Java class. For a <Mojo> to become a <report Mojo>, it needs to
- implement {{{/shared/maven-reporting-api/apidocs/org/apache/maven/reporting/MavenReport.html}<<<org.apache.maven.reporting.MavenReport>>>}}
- (in addition to {{{/ref/current/apidocs/org/apache/maven/plugin/Mojo.html}<<<org.apache.maven.plugin.Mojo>>>}}).
+First and foremost, a _report plugin_ is a _Maven plugin_ and it is strongly advised to first read the [Guide to Developing Java Plugins](./guide-java-plugin-development.html) to properly understand its core mechanisms.
- An easy way to implement both <<<Mojo>>> and <<<MavenReport>>> interfaces is to extend
- the {{{/shared/maven-reporting-impl/apidocs/org/apache/maven/reporting/AbstractMavenReport.html}<<<org.apache.maven.reporting.AbstractMavenReport>>>}}
- class provided by {{{/shared/maven-reporting-impl/}<<<maven-reporting-impl>>>}} (instead of <<<org.apache.maven.plugin.AbstractMojo>>> for a regular <Mojo>).
+A plugin is actually not a _report plugin_ in itself. But one (or several) of its goals or _Mojos_ may be specialized to be invoked by [`maven-site-plugin`](/plugins/maven-site-plugin/), typically during the `site` build life cycle.
- The class will need to implement the following methods:
+A Maven plugin can therefore implement _regular_ goals and _report_ goals. The below details how to write a _Mojo_ that will get invoked as a _report_ by [`maven-site-plugin`](/plugins/maven-site-plugin/).
- * <<<public String getOutputName()>>>: returns the name of page that will be produced
+How It Works
+------------
- * <<<public String getName(Locale locale)>>>: returns the display name of the report
+1. A regular Maven project usually invokes _reporting goals_ of a plugin by declaring such plugin in the [`<reporting>`](/plugins/maven-site-plugin/examples/configuring-reports.html) section of its `pom.xml` as in the example below:
- * <<<public String getDescription(Locale locale)>>>: returns the description of the report
-
- * <<<protected void executeReport(Locale locale) throws MavenReportException>>>: produces the actual report
-
- []
-
- To build a Maven plugin that includes <report Mojos>, the <<<pom.xml>>> of your project will need declare the project
- as a regular plugin, and include specific dependencies required by the report <Mojos>:
+ ```unknown
+ <project>
+ ...
+ <reporting>
+ <plugins>
+ <plugin>
+ <groupId>com.mycompany.maven</groupId>
+ <artifactId>simple-maven-plugin</artifactId>
+ <version>1.0-SNAPSHOT</version>
+ </plugin>
+ </plugins>
+ </reporting>
+ ...
+ ```
- * {{{/shared/maven-reporting-impl/dependency-info.html}<<<org.apache.maven.reporting:maven-reporting-impl>>>}}
+1. When [`maven-site-plugin`](/plugins/maven-site-plugin/) is invoked (for example with the `mvn site` command), the specified plugins are loaded and the `generate()` method of each Mojo class that implements [`MavenReport`](/shared/maven-reporting-api/apidocs/org/apache/maven/reporting/MavenReport.html) is executed.
+1. The `generate()` method generates a document through Maven's [Doxia Sink API](/doxia/doxia/doxia-sink-api/). This document is comprised of basic elements like title, headings, text, links, tables, etc. This is where you will put the logic of your report, assembling elements, based on the content of the Maven project.
+1. These document elements are passed to Doxia to generate an HTML document, which itself gets wrapped into a [Maven Skin](/skins/), as specified in the projects [`./src/site/site.xml`](/guides/mini/guide-site.html).
+1. The result produces an HTML file in the `./target/site` directory of your project.
- * {{{/shared/maven-reporting-api/project-summary.html}<<<org.apache.maven.reporting:maven-reporting-api>>>}}
+[More details about Doxia Site Renderer](/doxia/doxia-sitetools/doxia-site-renderer/)
- []
+Basic Requirements of a Report _Mojo_
+-------------------------------------
-* A (Very) Simple Report
+Each goal or _Mojo_ is implemented with a separate Java class. For a _Mojo_ to become a _report Mojo_, it needs to implement [`org.apache.maven.reporting.MavenReport`](/shared/maven-reporting-api/apidocs/org/apache/maven/reporting/MavenReport.html) (in addition to [`org.apache.maven.plugin.Mojo`](/ref/current/apidocs/org/apache/maven/plugin/Mojo.html)).
- Let's write a very simple <report Mojo> in a very simple Maven plugin:
+An easy way to implement both `Mojo` and `MavenReport` interfaces is to extend the [`org.apache.maven.reporting.AbstractMavenReport`](/shared/maven-reporting-impl/apidocs/org/apache/maven/reporting/AbstractMavenReport.html) class provided by [`maven-reporting-impl`](/shared/maven-reporting-impl/) (instead of `org.apache.maven.plugin.AbstractMojo` for a regular _Mojo_).
- * Plugin's name: <<Simple Plugin>>
+The class will need to implement the following methods:
- * Plugin's artifact coordinates: <<<com.mycompany.maven:simple-maven-plugin:1.0-SNAPSHOT>>>
+- `public String getOutputName()`: returns the name of page that will be produced
+- `public String getName(Locale locale)`: returns the display name of the report
+- `public String getDescription(Locale locale)`: returns the description of the report
+- `protected void executeReport(Locale locale) throws MavenReportException`: produces the actual report
- * One goal: <<simple>>
+To build a Maven plugin that includes _report Mojos_, the `pom.xml` of your project will need declare the project as a regular plugin, and include specific dependencies required by the report _Mojos_:
- * One result: <<<simple-report.html>>>
+- [`org.apache.maven.reporting:maven-reporting-impl`](/shared/maven-reporting-impl/dependency-info.html)
+- [`org.apache.maven.reporting:maven-reporting-api`](/shared/maven-reporting-api/project-summary.html)
- []
+A (Very) Simple Report
+----------------------
- Our Maven plugin project has 2 files only:
+Let's write a very simple _report Mojo_ in a very simple Maven plugin:
- * <<<./pom.xml>>>
+- Plugin's name: **Simple Plugin**
+- Plugin's artifact coordinates: `com.mycompany.maven:simple-maven-plugin:1.0-SNAPSHOT`
+- One goal: **simple**
+- One result: `simple-report.html`
- * <<<./src/main/java/com/mycompany/maven/SimpleReport.java>>>
+Our Maven plugin project has 2 files only:
- []
+- `./pom.xml`
+- `./src/main/java/com/mycompany/maven/SimpleReport.java`
- The below examples can be copied and pasted as a template.
+The below examples can be copied and pasted as a template.
-** ./pom.xml
+#[[### ./pom.xml]]#
-+---
+```unknown
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
@@ -240,11 +196,11 @@ Introduction
</build>
</project>
-+---
+```
-** ./src/main/java/com/mycompany/maven/SimpleReport.java
+#[[### ./src/main/java/com/mycompany/maven/SimpleReport.java]]#
-+---
+```unknown
package com.mycompany.maven;
import java.util.Locale;
@@ -343,31 +299,25 @@ public class SimpleReport extends AbstractMavenReport {
}
}
-+---
+```
-** Building the Simple Plugin
+#[[### Building the Simple Plugin]]#
- Building the plugin is done by executing the below command in the root directory of the plugin project:
+Building the plugin is done by executing the below command in the root directory of the plugin project:
-----
+```
$ mvn install
-----
-
- This command will:
-
- * compile your code
+```
- * produces the plugin JAR artifact (<<<./target/simple-maven-plugin-1.0-SNAPSHOT.jar>>>)
+This command will:
- * copy the artifact to your local repository so that it can be "consumed" by other projects (which
- is the purpose of a plugin, right?).
+- compile your code
+- produces the plugin JAR artifact (`./target/simple-maven-plugin-1.0-SNAPSHOT.jar`)
+- copy the artifact to your local repository so that it can be "consumed" by other projects (which is the purpose of a plugin, right?).
- []
+To make sure everything went well and is properly declared, you can now execute the below command in any other Maven project directory:
- To make sure everything went well and is properly declared, you can now execute the below command
- in any other Maven project directory:
-
-----
+```
$ mvn com.mycompany.maven:simple-maven-plugin:1.0-SNAPSHOT:help
[INFO] --- simple-maven-plugin:1.0-SNAPSHOT:help (default-cli) @ hardware-connectors ---
@@ -390,14 +340,13 @@ simple:simple
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
-----
+```
-** Invoking the Simple Plugin
+#[[### Invoking the Simple Plugin]]#
- To invoke the <report Mojo> of our plugin in another Maven project, we just need to declare the plugin in the
- {{{/plugins/maven-site-plugin/examples/configuring-reports.html}<<<<reporting\>>>>}} section of its <<<pom.xml>>> as in the example below:
+To invoke the _report Mojo_ of our plugin in another Maven project, we just need to declare the plugin in the [`<reporting>`](/plugins/maven-site-plugin/examples/configuring-reports.html) section of its `pom.xml` as in the example below:
-+---
+```unknown
<project>
...
<reporting>
@@ -411,77 +360,50 @@ simple:simple
</reporting>
...
</project>
-+---
-
- Note: When no specific report is specified, all of the <Mojos> in the plugin, that are declared as "reporting" will be executed.
- {{{/plugins/maven-site-plugin/examples/configuring-reports.html}More information about configuring reports}}.
+```
+Note: When no specific report is specified, all of the _Mojos_ in the plugin, that are declared as "reporting" will be executed. [More information about configuring reports](/plugins/maven-site-plugin/examples/configuring-reports.html).
-* More Information
+More Information
+----------------
-** The Doxia Sink API
+#[[### The Doxia Sink API]]#
- In your <<<executeReport()>>> method, you will leverage the {{{/doxia/doxia/doxia-sink-api/}Doxia Sink API}}
- to add elements to the report document.
+In your `executeReport()` method, you will leverage the [Doxia Sink API](/doxia/doxia/doxia-sink-api/) to add elements to the report document.
- You will use the {{{/doxia/doxia/doxia-sink-api/apidocs/org/apache/maven/doxia/sink/Sink.html}<<<Sink>>>}} object associated to the report:
+You will use the [`Sink`](/doxia/doxia/doxia-sink-api/apidocs/org/apache/maven/doxia/sink/Sink.html) object associated to the report:
-+---
+```unknown
Sink sink = getSink();
-+---
-
- This object allows you to append new elements to the report document (initially empty). Unlike some DOM manipulation APIs,
- you cannot insert elements in already existing elements, or remove elements.
-
- The elements that you append to the document will look familiar if you have basic knowledge of HTML. Most of the elements
- have opening and closing tags, like <<<sink.body()>>> (opening) and <<<sink.body_()>>> (closing).
-
- * <<<sink.head()>>> and <<<sink.head_()>>>
-
- * <<<sink.paragraph()>>> and <<<sink.paragraph_()>>>
+```
- * <<<sink.section1()>>> and <<<sink.section1_()>>>
+This object allows you to append new elements to the report document (initially empty). Unlike some DOM manipulation APIs, you cannot insert elements in already existing elements, or remove elements.
- * <<<sink.bold()>>> and <<<sink.bold_()>>>
+The elements that you append to the document will look familiar if you have basic knowledge of HTML. Most of the elements have opening and closing tags, like `sink.body()` (opening) and `sink.body_()` (closing).
- * etc.
+- `sink.head()` and `sink.head_()`
+- `sink.paragraph()` and `sink.paragraph_()`
+- `sink.section1()` and `sink.section1_()`
+- `sink.bold()` and `sink.bold_()`
+- etc.
- []
+**Do not forget to close elements\!**
- <<Do not forget to close elements!>>
+At the very least, a document should include the following:
- At the very least, a document should include the following:
+- Head and title (`sink.head()` and `sink.title()`)
+- Body (`sink.body()`)
+- Section 1 with title (`sink.section1()` and `sink.sectionTitle1()`)
- * Head and title (<<<sink.head()>>> and <<<sink.title()>>>)
+The [`Sink`](/doxia/doxia/doxia-sink-api/apidocs/org/apache/maven/doxia/sink/Sink.html) object allows you to add raw text with the _rawText()_ method. More precisely, it allows you to add raw HTML code into the document for full flexibility. However, you should limit the usage of this method as you may add elements that are not supported by non-HTML renderers (like [`maven-pdf-site`](/plugins/maven-pdf-plugin/)).
- * Body (<<<sink.body()>>>)
+The Doxia Sink API allows you to specify [_SinkEventAttributes_](/doxia/doxia/doxia-sink-api/apidocs/org/apache/maven/doxia/sink/SinkEventAttributes.html) to each element, i.e. HTML properties, notably the class and the ID of an object, which allows for easy customization with an appropriate CSS (either provided by the specified Maven Skin, or by the project itself).
- * Section 1 with title (<<<sink.section1()>>> and <<<sink.sectionTitle1()>>>)
+#[[### Creating more than one document]]#
- []
+You may need to create not just one HTML file, but several of them (like Javadoc produces one HTML file for each Java class). To do so, you will need to get a new _Sink_ for each HTML file you need to produce. This is achieved by using the [`SinkFactory`](/doxia/doxia/doxia-sink-api/apidocs/org/apache/maven/doxia/sink/SinkFactory.html) object that you can easily obtain with the [`getSinkFactory()`](/shared/maven-reporting-impl/apidocs/org/apache/maven/reporting/AbstractMavenReport.html#g [...]
- The {{{/doxia/doxia/doxia-sink-api/apidocs/org/apache/maven/doxia/sink/Sink.html}<<<Sink>>>}} object
- allows you to add raw text with the <rawText()> method. More precisely, it allows you to add raw HTML code into the
- document for full flexibility. However, you should limit the usage of this method as you may add elements that are not supported
- by non-HTML renderers (like {{{/plugins/maven-pdf-plugin/}<<<maven-pdf-site>>>}}).
-
- The Doxia Sink API allows you to specify {{{/doxia/doxia/doxia-sink-api/apidocs/org/apache/maven/doxia/sink/SinkEventAttributes.html}<SinkEventAttributes>}}
- to each element, i.e. HTML properties, notably the class and the ID of an object, which allows for easy customization
- with an appropriate CSS (either provided by the specified Maven Skin, or by the project itself).
-
-** Creating more than one document
-
- You may need to create not just one HTML file, but several of them (like Javadoc produces one HTML file for
- each Java class). To do so, you will need to get a new <Sink> for each HTML file you need to produce.
- This is achieved by using the
- {{{/doxia/doxia/doxia-sink-api/apidocs/org/apache/maven/doxia/sink/SinkFactory.html}<<<SinkFactory>>>}} object
- that you can easily obtain with the
- {{{/shared/maven-reporting-impl/apidocs/org/apache/maven/reporting/AbstractMavenReport.html#getSinkFactory()}<<<getSinkFactory()>>>}}
- method of your
- {{{/shared/maven-reporting-impl/apidocs/org/apache/maven/reporting/AbstractMavenReport.html}<<<AbstractMavenReport>>>}} instance,
- as in the example below.
-
-+---
+```unknown
public class SimpleReport extends AbstractMavenReport {
...
@@ -513,23 +435,16 @@ public class SimpleReport extends AbstractMavenReport {
otherSink.title();
otherSink.text("The Other Report");
...
-+---
-
- The above example will create a <<<other-report.html>>> HTML file along with <<<simple-report.html>>>.
-
- Note: Despite the fact that you will be creating additional HTML files, the Velocity variable <<<$currentFileName>>>
- passed to the <<<site.vm>>> script of the Maven Skin will keep the name of the original report (i.e. the result of
- your <getOutputName()> method). {{{/doxia/doxia-sitetools/doxia-site-renderer/}More information about the Velocity
- variables}}.
-
-* Resources
-
- [[1]] {{{./guide-java-plugin-development.html}Guide to Developing Java Plugins}}: Starting point, since a reporting plugin is a plugin...
+```
- [[2]] {{{/shared/maven-reporting-api/}Maven Reporting API}}: The Reporting API to implement when a Mojo provides reporting for site.
+The above example will create a `other-report.html` HTML file along with `simple-report.html`.
- [[3]] {{{/shared/maven-reporting-impl/}Maven Reporting Implementation}}: Base implementation of both Reporting API and Plugin API.
+Note: Despite the fact that you will be creating additional HTML files, the Velocity variable `$currentFileName` passed to the `site.vm` script of the Maven Skin will keep the name of the original report (i.e. the result of your _getOutputName()_ method). [More information about the Velocity variables](/doxia/doxia-sitetools/doxia-site-renderer/).
- [[4]] {{{/doxia/doxia/doxia-sink-api/}Doxia Sink API}}: API to generate content.
+Resources
+---------
- []
+1. [Guide to Developing Java Plugins](./guide-java-plugin-development.html): Starting point, since a reporting plugin is a plugin...
+1. [Maven Reporting API](/shared/maven-reporting-api/): The Reporting API to implement when a Mojo provides reporting for site.
+1. [Maven Reporting Implementation](/shared/maven-reporting-impl/): Base implementation of both Reporting API and Plugin API.
+1. [Doxia Sink API](/doxia/doxia/doxia-sink-api/): API to generate content.