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/07 20:50:38 UTC
(maven-reporting-impl) 02/02: Port the site documentation from APT to Markdown
This is an automated email from the ASF dual-hosted git repository.
slachiewicz pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven-reporting-impl.git
commit d4c4f6b6f98c3a291b9ba3f65206fd5c758436a0
Author: Sylwester Lachiewicz <sl...@apache.org>
AuthorDate: Fri Aug 7 22:35:17 2026 +0200
Port the site documentation from APT to Markdown
The page keeps its .vm suffix: it interpolates ${project.scm.tag} into a link to
the sample in the source tree, so Velocity still has work to do.
Velocity reads ## as a line comment, which would silently delete every heading
below level one before Doxia sees the page, so level two uses a setext underline
and the level three heading is wrapped in an unparsed block.
Verified by building the site before and after and comparing every generated page:
the meta tags, title, headings, visible text and every link target are identical.
The only change is the 'edit this page' link, which now points at the new path.
---
src/site/markdown/index.md.vm | 143 +++++++++++++++++++-----------------------
1 file changed, 63 insertions(+), 80 deletions(-)
diff --git a/src/site/markdown/index.md.vm b/src/site/markdown/index.md.vm
index 0c5782c..e970aa8 100644
--- a/src/site/markdown/index.md.vm
+++ b/src/site/markdown/index.md.vm
@@ -1,80 +1,63 @@
- -----
- Introduction
- -----
- Hervé Boutemy
- -----
- 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.
-
- ~~ NOTE: For help with the syntax of this file, see:
- ~~ http://maven.apache.org/doxia/references/apt-format.html
-
-${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
- <<<{{{../maven-reporting-api/apidocs/org/apache/maven/reporting/MavenReport.html}MavenReport}}>>>,
-
- 2. or as a direct standalone <<goal invocation>>, as a {{{/ref/current/maven-plugin-api/}maven-plugin-api}}'s
- <<<{{{/ref/current/maven-plugin-api/apidocs/org/apache/maven/plugin/Mojo.html}Mojo}}>>>.
-
- []
-
- The two APIs implementations are provided by <<<{{{./apidocs/org/apache/maven/reporting/AbstractMavenReport.html}AbstractMavenReport}}>>>,
- 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
- {{{/shared/maven-reporting-exec/xref/org/apache/maven/reporting/exec/DefaultMavenReportExecutor.html}DefaultMavenReportExecutor}}
- in <<<{{{/shared/maven-reporting-exec/}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
- {{{../scm.html}the component source tree}}: see {{{https://github.com/apache/maven-reporting-impl/tree/${project.scm.tag}/src/it/setup-reporting-plugin}<<<src/it/setup-reporting-plugin>>>}}.
-
-* History
-
-*---------------*---------------------------------------------------------*---------------------*
-|| release date || maven-maven-reporting-impl || {{{/doxia/}Doxia}} ||
-*---------------*---------------------------------------------------------*---------------------*
-| 2024-10 | 4.0.0 | <<2.0.0>>
-*---------------*---------------------------------------------------------*---------------------*
-| 2022-08 | {{{/shared-archives/maven-reporting-impl-3.2.0/}3.2.0}} | 1.11.1
-*---------------*---------------------------------------------------------*---------------------*
-| 2022-02 | {{{/shared-archives/maven-reporting-impl-3.1.0/}3.1.0}} | 1.11.1
-*---------------*---------------------------------------------------------*---------------------*
-| 2017-06 | {{{/shared-archives/maven-reporting-impl-3.0.0/}3.0.0}} | 1.7
-*---------------*---------------------------------------------------------*---------------------*
-
- See also Maven Site Plugin's {{{/plugins/maven-site-plugin/history.html#maven-site-plugin-vs-doxia-vs-doxia-sitetools}history}}.
-
-** 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/maven-plugin-tools-annotations/}plugin-tools with Java 5 annotations}}:
- see {{{https://issues.apache.org/jira/browse/MSHARED-347}MSHARED-347}} for more details.
+---
+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.
+