From f5af72bd6ce4406705b3611e366b5c4749405fca Mon Sep 17 00:00:00 2001 From: Sylwester Lachiewicz Date: Thu, 6 Aug 2026 19:44:55 +0200 Subject: [PATCH 1/2] Rename the site documents ahead of converting them A pure rename, so that git records it and `git log --follow` and `git blame` still reach the history of each page after the conversion that follows. The content is still APT at this point and the site does not build between the two commits. --- src/site/{apt/index.apt.vm => markdown/index.md.vm} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename src/site/{apt/index.apt.vm => markdown/index.md.vm} (100%) diff --git a/src/site/apt/index.apt.vm b/src/site/markdown/index.md.vm similarity index 100% rename from src/site/apt/index.apt.vm rename to src/site/markdown/index.md.vm From 96922f0c3bf95977df9da0b8426e486e0b252c61 Mon Sep 17 00:00:00 2001 From: Sylwester Lachiewicz Date: Thu, 6 Aug 2026 19:44:55 +0200 Subject: [PATCH 2/2] Port the index page from APT to Markdown Converted with doxia-converter and then cleaned up by hand: - <<>> becomes backticks, <> becomes **bold**, {{{url}text}} becomes [text](url) - the ASF license header becomes a single block HTML comment - the page keeps a Velocity reference, so it stays a .vm. Velocity reads ## as a line comment and would silently swallow every ATX heading below level one, so subsections use setext underlines and anything deeper is wrapped in #[[ ... ]]# Two things needed fixing beyond the mechanical conversion: - APT wrote $\{project.reporting.plugins\} to show a literal reference. The parser unescapes that, which in a .vm file turns it into a live reference resolving to the object's toString, so it now uses the ${esc.d} trick that the code sample below it already used. - <<>>> collapsed into a single link and lost its closing angle bracket. Verified by building the site before and after: the rendered page is unchanged apart from / becoming / and quotes in prose picking up the Markdown module's typographic substitution. --- src/site/markdown/index.md.vm | 132 +++++++++++++--------------------- 1 file changed, 48 insertions(+), 84 deletions(-) diff --git a/src/site/markdown/index.md.vm b/src/site/markdown/index.md.vm index bac93fe..c790fc1 100644 --- a/src/site/markdown/index.md.vm +++ b/src/site/markdown/index.md.vm @@ -1,77 +1,50 @@ - ----- - Introduction - ----- - Hervé Boutemy - ----- - 2013-07-24 - ----- - - ~~ 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} - - Classes to prepare report plugins execution with Maven 3, through - {{{./apidocs/org/apache/maven/reporting/exec/MavenReportExecutor.html}MavenReportExecutor}} - ({{{./apidocs/org/apache/maven/reporting/exec/DefaultMavenReportExecutor.html}implementation}}). - - Contrary to Maven 2.x: - - [[1]] report <<<\>>> explicit definition is optional:\ - if no version is specified for a report plugin, version is determined by - - [[1]] searching for the plugin in the <<>> section of the pom, - - [[2]] searching for the plugin in the <<>> section of the pom, - - [[3]] asking {{{/ref/current/maven-core/apidocs/org/apache/maven/plugin/version/PluginVersionResolver.html}PluginVersionResolver}} - to get a fallback version and display a warning as it's not a recommended use, - - [] - - [[2]] plugin configuration from <<>> is injected into <<>> - (since Maven Reporting Executor 1.2, which is {{{/plugins/maven-site-plugin/history.html}used by Maven Site Plugin 3.4}}). - - [] - -* Notice on now obsolete reportPlugin format - - Since 1.4 (used by Maven Site Plugin 3.7), the request can (and should) be populated from - {{{/ref/current/maven-model/maven.html#class_reporting}pom's <<<\>>> section}}, - injected in Mojo parameter as <<<$\{project.reporting.plugins\}>>> default value: - -+----+ + + +# ${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 `` 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 `` 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 - {{{/plugins-archives/maven-site-plugin-3.9.0/maven-3.html#New_Configuration_Maven_3_only_no_reports_configuration_inheritance}Maven Site Plugin 3.9.0 documentation}} - for more details. +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 <<<\>>> element of <<>> or any other - report building plugin with following XML model corresponding to plugin's - <<>>> parameter: +Report plugins can be configured in `` 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 @@ -88,22 +61,13 @@ ${project.name} -+----+ - - Notice this is the model from plugins in - {{{/ref/current/maven-model/maven.html#class_reporting}<<<\>>> section of POM}}: - - * without <<<\>>> element: reporting plugins configuration inheritance is not supported at this level - (see {{{https://issues.apache.org/jira/browse/MSITE-484}MSITE-484}}), +``` - * with additional <<<\>>> list outside <<<\>>> that simplifies reports configuration in usual cases. +Notice this is the model from plugins in [`` section of POM](/ref/current/maven-model/maven.html#class_reporting): - [] +- without `` element: reporting plugins configuration inheritance is not supported at this level (see [MSITE-484](https://issues.apache.org/jira/browse/MSITE-484)), +- with additional `` list outside `` that simplifies reports configuration in usual cases. - Maven 3 core makes an automatic transformation of <<<\>>> POM section (which supports configuration inheritance) - to <<>>'s <<>> configuration through the - {{{/ref/current/maven-model-builder/apidocs/org/apache/maven/model/plugin/ReportingConverter.html}ReportingConverter}} - component. +Maven 3 core makes an automatic transformation of `` 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 <<>> for example: - this is one of the key limitations that made Maven team drop this approach. +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.