Port the site documentation from APT to Markdown

src/site/markdown/index.md.vm

@@ -0,0 +1,73 @@
+<!--
+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.
+-->
+
+# ${project.name}
+
+Classes to prepare report plugins execution with Maven 3, through [MavenReportExecutor](./apidocs/org/apache/maven/reporting/exec/MavenReportExecutor.html) ([implementation](./apidocs/org/apache/maven/reporting/exec/DefaultMavenReportExecutor.html)).
+
+Contrary to Maven 2.x:
+
+1. report `<version>` explicit definition is optional:  
+    if no version is specified for a report plugin, version is determined by
+    1. searching for the plugin in the `build/plugins` section of the pom,
+    1. searching for the plugin in the `build/pluginManagement` section of the pom,
+    1. asking [PluginVersionResolver](/ref/current/maven-core/apidocs/org/apache/maven/plugin/version/PluginVersionResolver.html) to get a fallback version and display a warning as it's not a recommended use,
+1. plugin configuration from `build/pluginManagement` is injected into `reporting/plugins` (since Maven Reporting Executor 1.2, which is [used by Maven Site Plugin 3.4](/plugins/maven-site-plugin/history.html)).
+
+Notice on now obsolete reportPlugin format
+------------------------------------------
+
+Since 1.4 (used by Maven Site Plugin 3.7), the request can (and should) be populated from [pom's `<reporting.plugins>` section](/ref/current/maven-model/maven.html#class_reporting), injected in Mojo parameter as `${esc.d}{project.reporting.plugins}` default value:
+
+```unknown
+    @Parameter( defaultValue = "${esc.d}{project.reporting.plugins}", readonly = true )
+    private org.apache.maven.model.ReportPlugin[] reportingPlugins;
+```
+
+This section is kept to explain what happened in previous releases of the component, but this approach has been abandonned so far after discovering major limitations: see [Maven Site Plugin 3.9.0 documentation](/plugins-archives/maven-site-plugin-3.9.0/maven-3.html#New_Configuration_Maven_3_only_no_reports_configuration_inheritance) for more details.
+
+Report plugins can be configured in `<configuration>` element of `maven-site-plugin` or any other report building plugin with following XML model corresponding to plugin's `List<`[`ReportPlugin`](./apidocs/org/apache/maven/reporting/exec/ReportPlugin.html)`>` parameter:
+
+```unknown
+<reportPlugins>
+  <reportPlugin>
+    <groupId/>
+    <artifactId/>
+    <version/>
+    <configuration/>
+    <reports/>
+    <reportSets>
+      <reportSet>
+        <id/>
+        <configuration/>
+        <reports/>
+      </reportSet>
+    </reportSets>
+  </reportPlugin>
+</reportPlugins>
+```
+
+Notice this is the model from plugins in [`<reporting>` section of POM](/ref/current/maven-model/maven.html#class_reporting):
+
+- without `<inherited>` element: reporting plugins configuration inheritance is not supported at this level (see [MSITE-484](https://issues.apache.org/jira/browse/MSITE-484)),
+- with additional `<reports>` list outside `<reportSet>` that simplifies reports configuration in usual cases.
+
+Maven 3 core makes an automatic transformation of `<reporting>` POM section (which supports configuration inheritance) to `maven-site-plugin`'s `reportPlugins` configuration through the [ReportingConverter](/ref/current/maven-model-builder/apidocs/org/apache/maven/model/plugin/ReportingConverter.html) component.
+
+But Maven 3 does not do the same job for any other plugin wanting to use reports, like `maven-pdf-plugin` for example: this is one of the key limitations that made Maven team drop this approach.