Port the site documentation from APT to Markdown

src/site/markdown/index.md.vm

@@ -0,0 +1,63 @@
+---
+title: Introduction
+author: 
+  - Hervé Boutemy
+date: 2014-12-07
+---
+
+<!--
+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}
+
+Abstract classes to manage report generation, which can be run both:
+
+1\. as part of a **site generation**, as a [maven-reporting-api](../maven-reporting-api/)'s [`MavenReport`](../maven-reporting-api/apidocs/org/apache/maven/reporting/MavenReport.html),
+
+2\. or as a direct standalone **goal invocation**, as a [maven-plugin-api](/ref/current/maven-plugin-api/)'s [`Mojo`](/ref/current/maven-plugin-api/apidocs/org/apache/maven/plugin/Mojo.html).
+
+The two APIs implementations are provided by [`AbstractMavenReport`](./apidocs/org/apache/maven/reporting/AbstractMavenReport.html), that delegates to extender's `executeReport( Locale )` reporting method implementation.
+
+Notice that Doxia version used at runtime varies between **site generation** and **goal invocation**:
+
+1\. when used as report during **site generation**, `maven-site-plugin` provides Doxia implementation to the plugin, overriding normal plugin dependency: see [DefaultMavenReportExecutor](/shared/maven-reporting-exec/xref/org/apache/maven/reporting/exec/DefaultMavenReportExecutor.html) in [`maven-reporting-exec`](/shared/maven-reporting-exec/).
+
+2\. when used as a direct standalone **goal invocation**, Doxia implementation used is the version used during plugin compilation and kept as transitive dependency of the plugin.
+
+Usage
+-----
+
+A full working sample is included in `maven-reporting-impl` ITs, which are part of [the component source tree](../scm.html): see [`src/it/setup-reporting-plugin`](https://github.com/apache/maven-reporting-impl/tree/${project.scm.tag}/src/it/setup-reporting-plugin).
+
+History
+-------
+
+|release date|maven-maven-reporting-impl|[Doxia](/doxia/)|
+|:---:|:---:|:---:|
+|2024-10|4.0.0|**2.0.0**|
+|2022-08|[3.2.0](/shared-archives/maven-reporting-impl-3.2.0/)|1.11.1|
+|2022-02|[3.1.0](/shared-archives/maven-reporting-impl-3.1.0/)|1.11.1|
+|2017-06|[3.0.0](/shared-archives/maven-reporting-impl-3.0.0/)|1.7|
+
+See also Maven Site Plugin's [history](/plugins/maven-site-plugin/history.html#maven-site-plugin-vs-doxia-vs-doxia-sitetools).
+
+#[[### Upgrading to `maven-reporting-impl 2.3+`]]#
+
+When upgrading a reporting plugin from an old version of `maven-reporting-impl` to version 2.3 or more, a lot of copy/pasted code can be removed by upgrading the plugin to [plugin-tools with Java 5 annotations](/plugin-tools/maven-plugin-tools-annotations/): see [MSHARED-347](https://issues.apache.org/jira/browse/MSHARED-347) for more details.
+