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/17 17:02:56 UTC

(maven-surefire) branch surefire-3.5.x updated (c804d9776 -> 23963d095)

This is an automated email from the ASF dual-hosted git repository.

slachiewicz pushed a change to branch surefire-3.5.x
in repository https://gitbox.apache.org/repos/asf/maven-surefire.git


    from c804d9776 Upgrade Doxia to 2.1.0 on the 3.5.x line
     new a93e5d1f3 Rename the site documents ahead of converting them
     new 23963d095 Convert the site documents from APT to Markdown

The 2 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails.  The revisions
listed as "add" were already present in the repository and have only
been added to this reference.


Summary of changes:
 maven-surefire-plugin/src/site/apt/api.apt.vm      |  94 -----
 .../src/site/apt/developing.apt.vm                 | 143 --------
 .../src/site/apt/examples/class-loading.apt.vm     | 174 ---------
 .../site/apt/examples/configuring-classpath.apt.vm | 188 ----------
 .../src/site/apt/examples/cucumber.apt.vm          | 115 ------
 .../src/site/apt/examples/cwd.apt.vm               |  50 ---
 .../src/site/apt/examples/debugging.apt.vm         |  92 -----
 .../fork-options-and-parallel-execution.apt.vm     | 406 ---------------------
 .../site/apt/examples/inclusion-exclusion.apt.vm   | 252 -------------
 .../src/site/apt/examples/jpms.apt.vm              | 205 -----------
 .../src/site/apt/examples/junit.apt.vm             | 314 ----------------
 .../src/site/apt/examples/logging.apt.vm           |  56 ---
 .../src/site/apt/examples/pojo-test.apt.vm         |  49 ---
 .../site/apt/examples/process-communication.apt.vm | 153 --------
 .../src/site/apt/examples/providers.apt.vm         |  65 ----
 .../site/apt/examples/rerun-failing-tests.apt.vm   | 162 --------
 .../src/site/apt/examples/shutdown.apt.vm          | 132 -------
 .../src/site/apt/examples/single-test.apt.vm       | 165 ---------
 .../site/apt/examples/skip-after-failure.apt.vm    |  85 -----
 .../src/site/apt/examples/skipping-tests.apt.vm    | 173 ---------
 .../src/site/apt/examples/spock.apt.vm             | 174 ---------
 .../src/site/apt/examples/system-properties.apt.vm | 164 ---------
 .../src/site/apt/examples/toolchains.apt.vm        |  89 -----
 .../src/site/apt/featurematrix.apt.vm              |  68 ----
 maven-surefire-plugin/src/site/apt/history.apt.vm  |  90 -----
 maven-surefire-plugin/src/site/apt/index.apt.vm    | 174 ---------
 maven-surefire-plugin/src/site/markdown/api.md     |  76 ++++
 .../src/site/markdown/developing.md                | 108 ++++++
 .../src/site/markdown/examples/class-loading.md.vm | 118 ++++++
 .../markdown/examples/configuring-classpath.md.vm  | 157 ++++++++
 .../src/site/markdown/examples/cucumber.md.vm      |  92 +++++
 .../src/site/markdown/examples/cwd.md              |  41 +++
 .../src/site/markdown/examples/debugging.md.vm     |  77 ++++
 .../fork-options-and-parallel-execution.md.vm      | 261 +++++++++++++
 .../markdown/examples/inclusion-exclusion.md.vm    | 196 ++++++++++
 .../src/site/markdown/examples/jpms.md.vm          | 194 ++++++++++
 .../examples/junit-platform.md.vm}                 | 398 +++++++++-----------
 .../src/site/markdown/examples/junit.md.vm         | 284 ++++++++++++++
 .../src/site/markdown/examples/logging.md.vm       |  46 +++
 .../src/site/markdown/examples/pojo-test.md        |  40 ++
 .../markdown/examples/process-communication.md.vm  | 139 +++++++
 .../src/site/markdown/examples/providers.md.vm     |  57 +++
 .../markdown/examples/rerun-failing-tests.md.vm    | 139 +++++++
 .../src/site/markdown/examples/shutdown.md.vm      |  95 +++++
 .../src/site/markdown/examples/single-test.md.vm   | 139 +++++++
 .../markdown/examples/skip-after-failure.md.vm     |  60 +++
 .../site/markdown/examples/skipping-tests.md.vm    | 147 ++++++++
 .../src/site/markdown/examples/spock.md.vm         | 122 +++++++
 .../site/markdown/examples/system-properties.md.vm | 153 ++++++++
 .../examples/testng.md.vm}                         | 249 ++++++-------
 .../src/site/markdown/examples/toolchains.md.vm    |  80 ++++
 .../src/site/markdown/featurematrix.md             |  51 +++
 .../src/site/markdown/history.md.vm                |  41 +++
 .../src/site/markdown/index.md.vm                  | 116 ++++++
 .../{apt/usage.apt.vm => markdown/usage.md.vm}     | 217 +++++------
 .../site/apt/examples/changing-report-name.apt.vm  |  52 ---
 .../src/site/apt/examples/cross-referencing.apt.vm |  78 ----
 .../src/site/apt/examples/linking-to-tests.apt.vm  |  57 ---
 .../apt/examples/report-custom-location.apt.vm     |  72 ----
 .../src/site/apt/examples/show-failures.apt.vm     |  57 ---
 .../src/site/apt/index.apt                         |  82 -----
 .../src/site/apt/usage.apt.vm                      |  65 ----
 .../markdown/examples/changing-report-name.md.vm   |  44 +++
 .../site/markdown/examples/cross-referencing.md.vm |  62 ++++
 .../src/site/markdown/examples/linking-to-tests.md |  45 +++
 .../markdown/examples/report-custom-location.md.vm |  61 ++++
 .../src/site/markdown/examples/show-failures.md.vm |  50 +++
 .../src/site/markdown/index.md                     |  50 +++
 .../src/site/markdown/usage.md.vm                  |  59 +++
 surefire-api/src/site/apt/index.apt                |  52 ---
 surefire-api/src/site/markdown/index.md            |  46 +++
 71 files changed, 3820 insertions(+), 4837 deletions(-)
 delete mode 100644 maven-surefire-plugin/src/site/apt/api.apt.vm
 delete mode 100644 maven-surefire-plugin/src/site/apt/developing.apt.vm
 delete mode 100644 maven-surefire-plugin/src/site/apt/examples/class-loading.apt.vm
 delete mode 100644 maven-surefire-plugin/src/site/apt/examples/configuring-classpath.apt.vm
 delete mode 100644 maven-surefire-plugin/src/site/apt/examples/cucumber.apt.vm
 delete mode 100644 maven-surefire-plugin/src/site/apt/examples/cwd.apt.vm
 delete mode 100644 maven-surefire-plugin/src/site/apt/examples/debugging.apt.vm
 delete mode 100644 maven-surefire-plugin/src/site/apt/examples/fork-options-and-parallel-execution.apt.vm
 delete mode 100644 maven-surefire-plugin/src/site/apt/examples/inclusion-exclusion.apt.vm
 delete mode 100644 maven-surefire-plugin/src/site/apt/examples/jpms.apt.vm
 delete mode 100644 maven-surefire-plugin/src/site/apt/examples/junit.apt.vm
 delete mode 100644 maven-surefire-plugin/src/site/apt/examples/logging.apt.vm
 delete mode 100644 maven-surefire-plugin/src/site/apt/examples/pojo-test.apt.vm
 delete mode 100644 maven-surefire-plugin/src/site/apt/examples/process-communication.apt.vm
 delete mode 100644 maven-surefire-plugin/src/site/apt/examples/providers.apt.vm
 delete mode 100644 maven-surefire-plugin/src/site/apt/examples/rerun-failing-tests.apt.vm
 delete mode 100644 maven-surefire-plugin/src/site/apt/examples/shutdown.apt.vm
 delete mode 100644 maven-surefire-plugin/src/site/apt/examples/single-test.apt.vm
 delete mode 100644 maven-surefire-plugin/src/site/apt/examples/skip-after-failure.apt.vm
 delete mode 100644 maven-surefire-plugin/src/site/apt/examples/skipping-tests.apt.vm
 delete mode 100644 maven-surefire-plugin/src/site/apt/examples/spock.apt.vm
 delete mode 100644 maven-surefire-plugin/src/site/apt/examples/system-properties.apt.vm
 delete mode 100644 maven-surefire-plugin/src/site/apt/examples/toolchains.apt.vm
 delete mode 100644 maven-surefire-plugin/src/site/apt/featurematrix.apt.vm
 delete mode 100644 maven-surefire-plugin/src/site/apt/history.apt.vm
 delete mode 100644 maven-surefire-plugin/src/site/apt/index.apt.vm
 create mode 100644 maven-surefire-plugin/src/site/markdown/api.md
 create mode 100644 maven-surefire-plugin/src/site/markdown/developing.md
 create mode 100644 maven-surefire-plugin/src/site/markdown/examples/class-loading.md.vm
 create mode 100644 maven-surefire-plugin/src/site/markdown/examples/configuring-classpath.md.vm
 create mode 100644 maven-surefire-plugin/src/site/markdown/examples/cucumber.md.vm
 create mode 100644 maven-surefire-plugin/src/site/markdown/examples/cwd.md
 create mode 100644 maven-surefire-plugin/src/site/markdown/examples/debugging.md.vm
 create mode 100644 maven-surefire-plugin/src/site/markdown/examples/fork-options-and-parallel-execution.md.vm
 create mode 100644 maven-surefire-plugin/src/site/markdown/examples/inclusion-exclusion.md.vm
 create mode 100644 maven-surefire-plugin/src/site/markdown/examples/jpms.md.vm
 rename maven-surefire-plugin/src/site/{apt/examples/junit-platform.apt.vm => markdown/examples/junit-platform.md.vm} (54%)
 create mode 100644 maven-surefire-plugin/src/site/markdown/examples/junit.md.vm
 create mode 100644 maven-surefire-plugin/src/site/markdown/examples/logging.md.vm
 create mode 100644 maven-surefire-plugin/src/site/markdown/examples/pojo-test.md
 create mode 100644 maven-surefire-plugin/src/site/markdown/examples/process-communication.md.vm
 create mode 100644 maven-surefire-plugin/src/site/markdown/examples/providers.md.vm
 create mode 100644 maven-surefire-plugin/src/site/markdown/examples/rerun-failing-tests.md.vm
 create mode 100644 maven-surefire-plugin/src/site/markdown/examples/shutdown.md.vm
 create mode 100644 maven-surefire-plugin/src/site/markdown/examples/single-test.md.vm
 create mode 100644 maven-surefire-plugin/src/site/markdown/examples/skip-after-failure.md.vm
 create mode 100644 maven-surefire-plugin/src/site/markdown/examples/skipping-tests.md.vm
 create mode 100644 maven-surefire-plugin/src/site/markdown/examples/spock.md.vm
 create mode 100644 maven-surefire-plugin/src/site/markdown/examples/system-properties.md.vm
 rename maven-surefire-plugin/src/site/{apt/examples/testng.apt.vm => markdown/examples/testng.md.vm} (57%)
 create mode 100644 maven-surefire-plugin/src/site/markdown/examples/toolchains.md.vm
 create mode 100644 maven-surefire-plugin/src/site/markdown/featurematrix.md
 create mode 100644 maven-surefire-plugin/src/site/markdown/history.md.vm
 create mode 100644 maven-surefire-plugin/src/site/markdown/index.md.vm
 rename maven-surefire-plugin/src/site/{apt/usage.apt.vm => markdown/usage.md.vm} (56%)
 delete mode 100644 maven-surefire-report-plugin/src/site/apt/examples/changing-report-name.apt.vm
 delete mode 100644 maven-surefire-report-plugin/src/site/apt/examples/cross-referencing.apt.vm
 delete mode 100644 maven-surefire-report-plugin/src/site/apt/examples/linking-to-tests.apt.vm
 delete mode 100644 maven-surefire-report-plugin/src/site/apt/examples/report-custom-location.apt.vm
 delete mode 100644 maven-surefire-report-plugin/src/site/apt/examples/show-failures.apt.vm
 delete mode 100644 maven-surefire-report-plugin/src/site/apt/index.apt
 delete mode 100644 maven-surefire-report-plugin/src/site/apt/usage.apt.vm
 create mode 100644 maven-surefire-report-plugin/src/site/markdown/examples/changing-report-name.md.vm
 create mode 100644 maven-surefire-report-plugin/src/site/markdown/examples/cross-referencing.md.vm
 create mode 100644 maven-surefire-report-plugin/src/site/markdown/examples/linking-to-tests.md
 create mode 100644 maven-surefire-report-plugin/src/site/markdown/examples/report-custom-location.md.vm
 create mode 100644 maven-surefire-report-plugin/src/site/markdown/examples/show-failures.md.vm
 create mode 100644 maven-surefire-report-plugin/src/site/markdown/index.md
 create mode 100644 maven-surefire-report-plugin/src/site/markdown/usage.md.vm
 delete mode 100644 surefire-api/src/site/apt/index.apt
 create mode 100644 surefire-api/src/site/markdown/index.md


(maven-surefire) 02/02: Convert the site documents from APT to Markdown

Posted by sl...@apache.org.
This is an automated email from the ASF dual-hosted git repository.

slachiewicz pushed a commit to branch surefire-3.5.x
in repository https://gitbox.apache.org/repos/asf/maven-surefire.git

commit 23963d0953e5eacc64905c45bfaf3e053678c668
Author: Sylwester Lachiewicz <sl...@apache.org>
AuthorDate: Mon Aug 17 17:11:58 2026 +0200

    Convert the site documents from APT to Markdown
    
    Eighteen pages are taken verbatim from master, whose APT sources are
    byte-identical to these; the rest carry the 3.5.x wording, which still
    documents the per-framework providers master no longer has.
    
    history.md.vm stays a pipe table and so loses table-bordered: writing it
    as raw HTML would restore the border but strip class=externalLink from
    every link in it.
---
 maven-surefire-plugin/src/site/markdown/api.md     | 112 +++---
 .../src/site/markdown/developing.md                | 175 ++++----
 .../src/site/markdown/examples/class-loading.md.vm | 250 +++++-------
 .../markdown/examples/configuring-classpath.md.vm  | 187 ++++-----
 .../src/site/markdown/examples/cucumber.md.vm      | 131 +++---
 .../src/site/markdown/examples/cwd.md              |  83 ++--
 .../src/site/markdown/examples/debugging.md.vm     | 109 +++--
 .../fork-options-and-parallel-execution.md.vm      | 441 +++++++--------------
 .../markdown/examples/inclusion-exclusion.md.vm    | 226 ++++-------
 .../src/site/markdown/examples/jpms.md.vm          | 145 ++++---
 .../site/markdown/examples/junit-platform.md.vm    | 398 ++++++++-----------
 .../src/site/markdown/examples/junit.md.vm         | 242 +++++------
 .../src/site/markdown/examples/logging.md.vm       |  94 ++---
 .../src/site/markdown/examples/pojo-test.md        |  75 ++--
 .../markdown/examples/process-communication.md.vm  | 124 +++---
 .../src/site/markdown/examples/providers.md.vm     |  86 ++--
 .../markdown/examples/rerun-failing-tests.md.vm    | 185 ++++-----
 .../src/site/markdown/examples/shutdown.md.vm      | 143 +++----
 .../src/site/markdown/examples/single-test.md.vm   | 182 ++++-----
 .../markdown/examples/skip-after-failure.md.vm     | 145 +++----
 .../site/markdown/examples/skipping-tests.md.vm    | 140 +++----
 .../src/site/markdown/examples/spock.md.vm         | 136 ++-----
 .../site/markdown/examples/system-properties.md.vm | 149 ++++---
 .../src/site/markdown/examples/testng.md.vm        | 249 ++++++------
 .../src/site/markdown/examples/toolchains.md.vm    | 121 +++---
 .../src/site/markdown/featurematrix.md             | 117 +++---
 .../src/site/markdown/history.md.vm                | 121 ++----
 .../src/site/markdown/index.md.vm                  | 234 ++++-------
 .../src/site/markdown/usage.md.vm                  | 217 ++++------
 .../markdown/examples/changing-report-name.md.vm   |  56 ++-
 .../site/markdown/examples/cross-referencing.md.vm |  84 ++--
 .../src/site/markdown/examples/linking-to-tests.md |  86 ++--
 .../markdown/examples/report-custom-location.md.vm |  79 ++--
 .../src/site/markdown/examples/show-failures.md.vm |  67 ++--
 .../src/site/markdown/index.md                     | 106 ++---
 .../src/site/markdown/usage.md.vm                  |  84 ++--
 surefire-api/src/site/markdown/index.md            |  98 +++--
 37 files changed, 2330 insertions(+), 3347 deletions(-)

diff --git a/maven-surefire-plugin/src/site/markdown/api.md b/maven-surefire-plugin/src/site/markdown/api.md
index eabe558f1..dee7986d8 100644
--- a/maven-surefire-plugin/src/site/markdown/api.md
+++ b/maven-surefire-plugin/src/site/markdown/api.md
@@ -1,94 +1,76 @@
-  ------
-  Provider API
-  ------
-  Kristian Rosenvold
-  ------
-  2010-12-09
-  ------
-  
-~~ 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: Provider API
+author:
+  - Kristian Rosenvold
+date: 2010-12-09
+---
 
-~~ 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
 
+  http://www.apache.org/licenses/LICENSE-2.0
 
-Maven Surefire Provider API
+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.
+-->
 
-  As of version 2.7 of Surefire, there is a proposed public API available for
-  external providers to use Surefire features.
+# Maven Surefire Provider API
 
-  The key features of Surefire are forking, reporting and directory/classpath scanning.
-  The remaining features are implemented in the providers.
+As of version 2.7 of Surefire, there is a proposed public API available for external providers to use Surefire features.
 
-  Please note that this API is still subject to change until otherwise declared, even in minor revisions.
-  Such changes will mostly happen to facilitate needs of new providers.
+The key features of Surefire are forking, reporting and directory/classpath scanning. The remaining features are implemented in the providers.
 
-* Requirements for a Provider
+Please note that this API is still subject to change until otherwise declared, even in minor revisions. Such changes will mostly happen to facilitate needs of new providers.
 
-  There are three things any provider must fulfill:
+## Requirements for a Provider
 
-  * A provider must implement the <<<org.apache.maven.surefire.providerapi.SurefireProvider>>> interface.
+There are three things any provider must fulfill:
 
-  * A provider contains a <<<META-INF/services>>> file entry named <<<org.apache.maven.surefire.providerapi.SurefireProvider>>>
-  (as per {{{http://download.oracle.com/javase/6/docs/api/java/util/ServiceLoader.html}ServiceLoader}}). This file
-  contains the fully qualified name of the actual provider class.
+- A provider must implement the `org.apache.maven.surefire.providerapi.SurefireProvider` interface.
+- A provider contains a `META-INF/services` file entry named `org.apache.maven.surefire.providerapi.SurefireProvider` (as per [ServiceLoader](http://download.oracle.com/javase/6/docs/api/java/util/ServiceLoader.html)). This file contains the fully qualified name of the actual provider class.
+- The actual provider class contains a one-arg constructor that accepts an instance of `org.apache.maven.surefire.providerapi.ProviderParameters`. This interface delivers all Surefire features to the provider implementation. Please see the javadoc of this interface for options.
 
-  * The actual provider class contains a one-arg constructor that accepts an instance of
-  <<<org.apache.maven.surefire.providerapi.ProviderParameters>>>. This interface delivers all Surefire features
-  to the provider implementation. Please see the javadoc of this interface for options.
+There are four well-known providers within Surefire that are also implemented this way, so examples can be found by looking at the Surefire source code itself. `surefire-junit47` is the showcase implementation.
 
-  []
+The javadoc on the intefaces mentioned in this article should otherwise be sufficient to write a provider. Providers are added as dependencies to the Surefire and Failsafe plugins.
 
-  There are four well-known providers within Surefire that are also implemented this way, so
-  examples can be found by looking at the Surefire source code itself. <<<surefire-junit47>>> is
-  the showcase implementation.
+### API Changes for 2.11
 
-  The javadoc on the intefaces mentioned in this article should otherwise be sufficient to write a provider.
-  Providers are added as dependencies to the Surefire and Failsafe plugins.
+Prior to 2.11, the provider would do
 
-** API Changes for 2.11
-
-    Prior to 2.11, the provider would do
-
-+---+
+```text
     TestsToRun scanned = directoryScanner.locateTestClasses( testClassLoader, scannerFilter );
-+---+
+```
 
-    and the classes would arrive in sorted order. In 2.11, an additional step must be implemented by the provider;
+and the classes would arrive in sorted order. In 2.11, an additional step must be implemented by the provider;
 
-+---+
+```text
     TestsToRun scanned = directoryScanner.locateTestClasses( testClassLoader, scannerFilter );
     return providerParameters.getRunOrderCalculator().orderTestClasses(  scanned );
-+---+
+```
 
-** API changes for 2.12.2:
+### API changes for 2.12.2:
 
-   Prior to this version, the provider would do
+Prior to this version, the provider would do
 
-+---+
+```text
     directoryScanner = booterParameters.getDirectoryScanner();
     final TestsToRun scanResult = directoryScanner.locateTestClasses( testClassLoader, testChecker );
-+---+
+```
 
-   In this version <<<ProviderParameters#getDirectoryScanner>>> has been deprecated, and it *will* be removed
-   for the next major version. Instead, use
+In this version `ProviderParameters#getDirectoryScanner` has been deprecated, and it \*will\* be removed for the next major version. Instead, use
 
-+---+
+```text
     scanResult = booterParameters.getScanResult();
     final TestsToRun testsToRun = scanResult.applyFilter(testChecker, testClassLoader );
-+---+
+```
diff --git a/maven-surefire-plugin/src/site/markdown/developing.md b/maven-surefire-plugin/src/site/markdown/developing.md
index 700ffcd56..8175f99e6 100644
--- a/maven-surefire-plugin/src/site/markdown/developing.md
+++ b/maven-surefire-plugin/src/site/markdown/developing.md
@@ -1,143 +1,108 @@
-  ------
-  Developing Surefire
-  ------
-  Kristian Rosenvold
-  ------
- 2011-03-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  
-
-Developer Center
-
-  When working with Surefire, it is necessary to understand a few things:
-
-* Multi-module Project
-
-  The plugin is built as part of a multi-module plugin. You need to check out 
-  the complete module and build from there:
-
-+---+
+---
+title: Developing Surefire
+author:
+  - Kristian Rosenvold
+date: 2011-03-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.
+-->
+
+# Developer Center
+
+When working with Surefire, it is necessary to understand a few things:
+
+## Multi-module Project
+
+The plugin is built as part of a multi-module plugin. You need to check out the complete module and build from there:
+
+```text
   git clone https://gitbox.apache.org/repos/asf/maven-surefire.git
-+---+
+```
 
-* Making Test Cases for Demonstrating Problems
+## Making Test Cases for Demonstrating Problems
 
-  When reporting an issue, it is immensely useful to create a small sample project
-  that demonstrates the problem. Surefire already contains a large number of such
-  projects, and they can be found at
-  {{surefire-its/src/test/resources/}}.
-  Typically you can check out one of the pre-existing projects and run it like this:
+When reporting an issue, it is immensely useful to create a small sample project that demonstrates the problem. Surefire already contains a large number of such projects, and they can be found at [surefire-its/src/test/resources/](#surefire-its.2Fsrc.2Ftest.2Fresources.2F). Typically you can check out one of the pre-existing projects and run it like this:
 
-+---+
+```bash
   cd surefire-its/src/test/resources/failsafe-buildfail
   mvn -Dsurefire.version=2.12 verify
-+---+
+```
 
-* Attaching a Debugger
+## Attaching a Debugger
 
-  Sometimes it's appropriate to attach a remote debugger to the Surefire fork to try to determine what
-  is <really> going on. If you checkout and build trunk, you'd usually do something like this:
+Sometimes it's appropriate to attach a remote debugger to the Surefire fork to try to determine what is _really_ going on. If you checkout and build trunk, you'd usually do something like this:
 
-+---+
+```bash
   mvn -Dmaven.surefire.debug=true install
-+---+
+```
 
-  Load the source in your IDE, set a breakpoint at the start of <<<ForkedBooter#main>>> and attach
-  a debugger to port 5005.
+Load the source in your IDE, set a breakpoint at the start of `ForkedBooter#main` and attach a debugger to port 5005.
 
-* Tracing a Forked Execution
+## Tracing a Forked Execution
 
-  The forked Surefire process uses standard input and output to communicate back to the source. Sometimes when tracking troubles
-  it can be helpful to look at just the output of the fork.
+The forked Surefire process uses standard input and output to communicate back to the source. Sometimes when tracking troubles it can be helpful to look at just the output of the fork.
 
-  This can be done by running:
+This can be done by running:
 
-+---+
+```bash
 mvn -e -X install | grep Forking
-+---+
+```
 
-  If you copy the command part of the output, you should be able to re-run the command by just pasting it on
-  the command line (you might have to do only the bits after <<<&&>>>).
+If you copy the command part of the output, you should be able to re-run the command by just pasting it on the command line (you might have to do only the bits after `&&`).
 
-  You can now paste this command on the command line and capture the output of the fork. This may help you
-  determine if the problem is in the forked end or the receiving end.
+You can now paste this command on the command line and capture the output of the fork. This may help you determine if the problem is in the forked end or the receiving end.
 
-  When investigating a particular class, you probably want to <<<grep>>> the output for the class name.
-  Additionally the booter code (first field) can be seen at
-  {{https://git-wip-us.apache.org/repos/asf?p=maven-surefire.git;a=blob;f=surefire-api/src/main/java/org/apache/maven/surefire/booter/ForkingRunListener.java}}
+When investigating a particular class, you probably want to `grep` the output for the class name. Additionally the booter code (first field) can be seen at [https://git-wip-us.apache.org/repos/asf?p=maven-surefire.git;a=blob;f=surefire-api/src/main/java/org/apache/maven/surefire/booter/ForkingRunListener.java](https://git-wip-us.apache.org/repos/asf?p=maven-surefire.git;a=blob;f=surefire-api/src/main/java/org/apache/maven/surefire/booter/ForkingRunListener.java)
 
-  The second field in the output (after the booter code) is the logical channel number, where different threads in the fork
-  should come in different channels.
+The second field in the output (after the booter code) is the logical channel number, where different threads in the fork should come in different channels.
 
-* Test Cases
+## Test Cases
 
-  All patches to Surefire must contain test coverage, either as an integration test
-  or a unit test. All new features (changed/added plugin options) must be covered by
-  an end-to-end integration test.
+All patches to Surefire must contain test coverage, either as an integration test or a unit test. All new features (changed/added plugin options) must be covered by an end-to-end integration test.
 
-  There are
-  numerous other integration tests that all operate on small sample projects in
-  <<<surefire-its/src/test/resources>>>.
+There are numerous other integration tests that all operate on small sample projects in `surefire-its/src/test/resources`.
 
-  Example integration tests are <<<Surefire141PluggableProvidersIT>>> and the corresponding
-  <<<surefire-its/src/test/resources/surefire-141-pluggableproviders>>>.
+Example integration tests are `Surefire141PluggableProvidersIT` and the corresponding `surefire-its/src/test/resources/surefire-141-pluggableproviders`.
 
-* Essential Source Code Reading List
+## Essential Source Code Reading List
 
-  Some methods/classes reveal more about the basic working of a piece of code than others. The following classes/methods
-  are a "reading list" for getting quickly acquainted with the code:
+Some methods/classes reveal more about the basic working of a piece of code than others. The following classes/methods are a "reading list" for getting quickly acquainted with the code:
 
-+---+
+```text
 AbstractSurefireMojo#executeAllProviders
 ForkStarter#fork
 ForkedBooter#main
-+---+
-
-* JDK Versions
+```
 
-  The surefire booter is capable of booting all the way back to jdk1.8. Specifically
-  this means <<<surefire-api>>>, <<<surefire-booter>>>, <<<common-junit3>>>, <<<surefire-junit3>>>
-  and other modules are compiled with source/target 1.8.
+## JDK Versions
 
-* Provider Isolation
+The surefire booter is capable of booting all the way back to jdk1.8. Specifically this means `surefire-api`, `surefire-booter`, `common-junit3`, `surefire-junit3` and other modules are compiled with source/target 1.8.
 
-  Classes in the SUT (<Subject Under Test>) override any classes within the
-  Surefire providers. This means providers using any
-  third party dependencies (other than the test framework itself) should
-  shade these classes to a different package.
+## Provider Isolation
 
-* Common Provider Modules
+Classes in the SUT (_Subject Under Test_) override any classes within the Surefire providers. This means providers using any third party dependencies (other than the test framework itself) should shade these classes to a different package.
 
-  The <<<surefire-providers>>> module contains <<<common-junitXX>>> modules. These modules
-  depend on the <<<XX>>> version of JUnit and can access the JUnit APIs at the correct
-  JUnit version level. Unit tests can also be written that will run with the
-  correct JUnit version. At build time, all of the relevant parts of these "common"
-  modules are just shaded into the provider jar files.
+## Common Provider Modules
 
-* Shadefire
+The `surefire-providers` module contains `common-junitXX` modules. These modules depend on the `XX` version of JUnit and can access the JUnit APIs at the correct JUnit version level. Unit tests can also be written that will run with the correct JUnit version. At build time, all of the relevant parts of these "common" modules are just shaded into the provider jar files.
 
-  "Shadefire" is the first module to be run in the
-  Surefire build. This creates a shaded version of the JUnit provider, and this provider
-  is thereafter used to build Surefire itself. This is
-  because the SUT overrides the provider, and the Shadefire provider has been
-  relocated to avoid this overriding when Surefire is building itself.
+## Shadefire
 
+"Shadefire" is the first module to be run in the Surefire build. This creates a shaded version of the JUnit provider, and this provider is thereafter used to build Surefire itself. This is because the SUT overrides the provider, and the Shadefire provider has been relocated to avoid this overriding when Surefire is building itself.
diff --git a/maven-surefire-plugin/src/site/markdown/examples/class-loading.md.vm b/maven-surefire-plugin/src/site/markdown/examples/class-loading.md.vm
index 4ff36f9f6..ecf142f91 100644
--- a/maven-surefire-plugin/src/site/markdown/examples/class-loading.md.vm
+++ b/maven-surefire-plugin/src/site/markdown/examples/class-loading.md.vm
@@ -1,148 +1,94 @@
-  ------
-  Class Loading and Forking
-  ------
-  Dan Fabulich
-  ------
-  2010-01-09
-  ------
-
- ~~ 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
-
-Class Loading and Forking in Maven Surefire
-
- This page discusses class loading and forking under Maven Surefire which is a shared component used by both
- the Surefire and Failsafe Maven plugins, with an eye towards troubleshooting problems.
-
-* Executive Summary
-
- If you're having problems, you'll probably want to tinker with these three settings: <<<forkCount>>>, <<<useSystemClassLoader>>>, and <<<useManifestOnlyJar>>>.
-
-* What Problem does the Maven Surefire Project Solve?
-
- Initially, the problem seems simple enough. Just launch Java with a classpath, like this:
- 
-+---+
+---
+title: Class Loading and Forking
+author:
+  - Dan Fabulich
+date: 2010-01-09
+---
+
+<!--
+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.
+-->
+
+# Class Loading and Forking in Maven Surefire
+
+This page discusses class loading and forking under Maven Surefire which is a shared component used by both the Surefire and Failsafe Maven plugins, with an eye towards troubleshooting problems.
+
+Executive Summary
+-----------------
+
+If you're having problems, you'll probably want to tinker with these three settings: `forkCount`, `useSystemClassLoader`, and `useManifestOnlyJar`.
+
+What Problem does the Maven Surefire Project Solve?
+---------------------------------------------------
+
+Initially, the problem seems simple enough. Just launch Java with a classpath, like this:
+
+```bash
 java -classpath foo.jar:bar.jar MyApp
-+---+
- 
- But there's a problem here: on some operating systems (Windows), there's a limit on how long you can make
- your command line, and therefore a limit on how long you can make your classpath. The limit is different
- on different versions of Windows; in some versions only a few hundred characters are allowed, in others
- a few thousand, but the limit can be pretty severe in either case.
-
-* Update for Maven Surefire 2.8.2
-
- It turns out setting the <<<CLASSPATH>>> as an environment variable may remove most of the
- practical length limitations, as documented in {{{https://issues.apache.org/jira/browse/SUREFIRE-727}SUREFIRE-727}}.
- This means most of the length-related problems in this article may be outdated.
-
-* Generic Solutions
-
- There are two "tricks" you can use to workaround this problem; both of them can cause other problems in some cases.
-
- 1. <<Isolated Class Loader>>: One workaround is to use an isolated class loader.
- Instead of launching <MyApp> directly, we can launch some other application (a "booter")
- with a much shorter classpath. We can then create a new java.lang.ClassLoader
- (usually a <<<java.net.URLClassLoader>>>) with the desired classpath configured. The booter
- can then load up <MyApp> from the class loader; when <MyApp> refers to other classes,
- they will be automatically loaded from our isolated class loader.
- 
- The problem with using an isolated class loader is that your classpath isn't
- <really> correct, and some applications can detect this and object. For example, the
- system property <<<java.class.path>>> won't include your jars; if your application notices
- this, it could cause a problem.
- 
- There's another similar problem with using an isolated class loader: any class
- may call the static method <<<ClassLoader.getSystemClassLoader()>>> and attempt to
- load classes out of that class loader, instead of using the default class loader.
- Classes often do this if they need to create class loaders of their own.
- Unfortunately, Java-based web application servers like Jetty, Tomcat, BEA
- WebLogic and IBM WebSphere are very likely to try to escape the confines of an
- isolated class loader.
- 
- 2. <<Manifest-Only JAR>>: Another workaround is to use a "manifest-only JAR." In
- this case, you create a temporary JAR that's almost completely empty, except for
- a <<<META-INF/MANIFEST.MF>>> file. Java manifests can contain attributes that the Java
- virtual machine will honor as directives. For example, you can have a <<<Class-Path>>> attribute,
- which specifies a list of other JARs to add to the classpath. So then you can run
- your code like this:
- 
-+---+
+```
+
+But there's a problem here: on some operating systems (Windows), there's a limit on how long you can make your command line, and therefore a limit on how long you can make your classpath. The limit is different on different versions of Windows; in some versions only a few hundred characters are allowed, in others a few thousand, but the limit can be pretty severe in either case.
+
+Update for Maven Surefire 2.8.2
+-------------------------------
+
+It turns out setting the `CLASSPATH` as an environment variable may remove most of the practical length limitations, as documented in [SUREFIRE-727](https://issues.apache.org/jira/browse/SUREFIRE-727). This means most of the length-related problems in this article may be outdated.
+
+Generic Solutions
+-----------------
+
+There are two "tricks" you can use to workaround this problem; both of them can cause other problems in some cases.
+
+1\. **Isolated Class Loader**: One workaround is to use an isolated class loader. Instead of launching _MyApp_ directly, we can launch some other application (a "booter") with a much shorter classpath. We can then create a new java.lang.ClassLoader (usually a `java.net.URLClassLoader`) with the desired classpath configured. The booter can then load up _MyApp_ from the class loader; when _MyApp_ refers to other classes, they will be automatically loaded from our isolated class loader.
+
+The problem with using an isolated class loader is that your classpath isn't _really_ correct, and some applications can detect this and object. For example, the system property `java.class.path` won't include your jars; if your application notices this, it could cause a problem.
+
+There's another similar problem with using an isolated class loader: any class may call the static method `ClassLoader.getSystemClassLoader()` and attempt to load classes out of that class loader, instead of using the default class loader. Classes often do this if they need to create class loaders of their own. Unfortunately, Java-based web application servers like Jetty, Tomcat, BEA WebLogic and IBM WebSphere are very likely to try to escape the confines of an isolated class loader.
+
+2\. **Manifest-Only JAR**: Another workaround is to use a "manifest-only JAR." In this case, you create a temporary JAR that's almost completely empty, except for a `META-INF/MANIFEST.MF` file. Java manifests can contain attributes that the Java virtual machine will honor as directives. For example, you can have a `Class-Path` attribute, which specifies a list of other JARs to add to the classpath. So then you can run your code like this:
+
+```bash
 java -classpath booter.jar MyApp
-+---+
-  
- This is a bit more realistic, because in this case the system class loader, the
- thread context class loader and the default class loader are all the same; there's
- no possibility of "escaping" the class loader. But this is still a weird
- simulation of a "normal" classpath, and it's still possible for apps to notice
- this. Again, <<<java.class.path>>> may not be what you'd expect ("why does it contain
- only one jar?"). Additionally, it's possible to query the system class loader to
- get the list of jars back out of it; your application may be confused if it finds only
- our <<<booter.jar>>> there!
-
-* Advantages/Disadvantages of each Solution
-
- If your application tries to interrogate its own class loader for a list of JARs, it may
- work better under an isolated class loader than it would with a manifest-only
- JAR.  However, if your application tries to escape its default class loader, it may not
- work under an isolated class loader at all.
-
- One advantage of using an isolated class loader is that it's the only way to use
- an isolated class loader without forking a separate process, running all of the
- tests in the same process as Maven itself.  But that itself can be pretty risky,
- especially if Maven is running embedded in your IDE!
- 
- Finally, of course, you could just try to wire up a plain old Java classpath and hope
- it's short enough.  In the worst case your classpath might work
- on some machines and not others.  Windows boxes would behave differently from
- Linux boxes; users with short user names might have more success than users
- with long user names, etc.  For this reason, we chose not to make the basic
- classpath the default, though we do provide it as an option (mostly as a last
- resort).
- 
-* What does Maven Surefire do?
-
- Surefire provides a mechanism for using multiple strategies.  The main parameter that
- determines this is called <<<useSystemClassLoader>>>.  If <<<useSystemClassLoader>>> is
- <<<true>>>, then we use a manifest-only JAR; otherwise, we use an isolated
- class loader.  If you want to use a basic plain old Java classpath, you can set
- <<<useManifestOnlyJar=false>>> which only has an effect when <<<useSystemClassLoader=true>>>.
-
- The default value for <<<useSystemClassLoader>>> changed between Surefire 2.3 and
- Surefire 2.4, which was a pretty significant change.  In Surefire 2.3,
- <<<useSystemClassLoader>>> was <<<false>>> by default, and we used an isolated class loader.
- In Surefire 2.4, <<<useSystemClassLoader>>> is <<<true>>> by default.  No value works for
- everyone, but we think this default is an improvement; a bunch of
- hard-to-diagnose bugs get better when we <<<useSystemClassLoader=true>>>.
-
- Unfortunately, if <<<useSystemClassLoader>>> is set incorrectly for your application, you're going to
- have a problem on your hands that can be quite difficult to diagnose.  You might
- even be forced to read a long documentation page like this one.  ;-)
-
- If you're having problems loading classes, try setting <<<useSystemClassLoader=false>>>
- to see if that helps.  You can do that with the POM snippet below, or by setting
- <<<-Dsurefire.useSystemClassLoader=false>>>.  If that doesn't work, try setting
- <<<useSystemClassLoader>>> back to <<<true>>> and setting <<<useManifestOnlyJar>>> to <<<false>>>.
-
-+---+
+```
+
+This is a bit more realistic, because in this case the system class loader, the thread context class loader and the default class loader are all the same; there's no possibility of "escaping" the class loader. But this is still a weird simulation of a "normal" classpath, and it's still possible for apps to notice this. Again, `java.class.path` may not be what you'd expect ("why does it contain only one jar?"). Additionally, it's possible to query the system class loader to get the list o [...]
+
+Advantages/Disadvantages of each Solution
+-----------------------------------------
+
+If your application tries to interrogate its own class loader for a list of JARs, it may work better under an isolated class loader than it would with a manifest-only JAR. However, if your application tries to escape its default class loader, it may not work under an isolated class loader at all.
+
+One advantage of using an isolated class loader is that it's the only way to use an isolated class loader without forking a separate process, running all of the tests in the same process as Maven itself. But that itself can be pretty risky, especially if Maven is running embedded in your IDE\!
+
+Finally, of course, you could just try to wire up a plain old Java classpath and hope it's short enough. In the worst case your classpath might work on some machines and not others. Windows boxes would behave differently from Linux boxes; users with short user names might have more success than users with long user names, etc. For this reason, we chose not to make the basic classpath the default, though we do provide it as an option (mostly as a last resort).
+
+What does Maven Surefire do?
+----------------------------
+
+Surefire provides a mechanism for using multiple strategies. The main parameter that determines this is called `useSystemClassLoader`. If `useSystemClassLoader` is `true`, then we use a manifest-only JAR; otherwise, we use an isolated class loader. If you want to use a basic plain old Java classpath, you can set `useManifestOnlyJar=false` which only has an effect when `useSystemClassLoader=true`.
+
+The default value for `useSystemClassLoader` changed between Surefire 2.3 and Surefire 2.4, which was a pretty significant change. In Surefire 2.3, `useSystemClassLoader` was `false` by default, and we used an isolated class loader. In Surefire 2.4, `useSystemClassLoader` is `true` by default. No value works for everyone, but we think this default is an improvement; a bunch of hard-to-diagnose bugs get better when we `useSystemClassLoader=true`.
+
+Unfortunately, if `useSystemClassLoader` is set incorrectly for your application, you're going to have a problem on your hands that can be quite difficult to diagnose. You might even be forced to read a long documentation page like this one. ;-)
+
+If you're having problems loading classes, try setting `useSystemClassLoader=false` to see if that helps. You can do that with the POM snippet below, or by setting `-Dsurefire.useSystemClassLoader=false`. If that doesn't work, try setting `useSystemClassLoader` back to `true` and setting `useManifestOnlyJar` to `false`.
+
+```xml
 <project>
   [...]
   <build>
@@ -159,16 +105,14 @@ java -classpath booter.jar MyApp
   </build>
   [...]
 </project>
-+---+
-
-* Debugging Classpath Problems
-
- If you've read this far, you're probably fully equipped to diagnose problems that may occur during class loading.  Here's some general tips to try:
-
- * Run Maven with <<<--debug>>> (or equivalently, <<<-X>>>) to get more detailed output
+```
 
- * Check your <<<forkCount>>>.  If <<<forkCount=0>>>, it's impossible to use the system class loader or a plain old Java classpath; we have to use an isolated class loader.
+Debugging Classpath Problems
+----------------------------
 
- * If you're using the defaults, <<<useSystemClassLoader=true>>> and <<<useManifestOnlyJar=false>>>.  In that case, look at the generated manifest-only Surefire booter JAR.  Open it up (it's just a zip) and read its manifest.
+If you've read this far, you're probably fully equipped to diagnose problems that may occur during class loading. Here's some general tips to try:
 
- * Run Maven with <<<-Dmaven.${thisPlugin.toLowerCase()}.debug>>>, and attach to the running process with a debugger.
+- Run Maven with `--debug` (or equivalently, `-X`) to get more detailed output
+- Check your `forkCount`. If `forkCount=0`, it's impossible to use the system class loader or a plain old Java classpath; we have to use an isolated class loader.
+- If you're using the defaults, `useSystemClassLoader=true` and `useManifestOnlyJar=false`. In that case, look at the generated manifest-only Surefire booter JAR. Open it up (it's just a zip) and read its manifest.
+- Run Maven with `-Dmaven.${thisPlugin.toLowerCase()}.debug`, and attach to the running process with a debugger.
diff --git a/maven-surefire-plugin/src/site/markdown/examples/configuring-classpath.md.vm b/maven-surefire-plugin/src/site/markdown/examples/configuring-classpath.md.vm
index 23a3a7bed..7bec2e7fb 100644
--- a/maven-surefire-plugin/src/site/markdown/examples/configuring-classpath.md.vm
+++ b/maven-surefire-plugin/src/site/markdown/examples/configuring-classpath.md.vm
@@ -1,71 +1,56 @@
-  ------
-  Configuring the Classpath
-  ------
-  Pascal Lambert
-  ------
-  2010-01-09
-  ------
-  
- ~~ 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
-
-The Default Classpath
-
-  The Surefire plugin builds the test classpath at runtime in the following order:
+---
+title: Configuring the Classpath
+author:
+  - Pascal Lambert
+date: 2010-01-09
+---
+
+<!--
+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.
+-->
+
+# The Default Classpath
+
+The Surefire plugin builds the test classpath at runtime in the following order:
 
 #{if}(${project.artifactId}=="maven-surefire-plugin")
-  [[1]] The {{{../test-mojo.html#testClassesDirectory}test-classes}} directory
-
-  [[2]] The {{{../test-mojo.html#classesDirectory}classes}} directory
-
+1. The [test-classes](../test-mojo.html#testClassesDirectory) directory
+1. The [classes](../test-mojo.html#classesDirectory) directory
 #{else}
-  [[1]] The {{{../integration-test-mojo.html#testClassesDirectory}test-classes}} directory
-
-  [[2]] The {{{../integration-test-mojo.html#classesDirectory}classes}} JAR file or directory
-
+1. The [test-classes](../integration-test-mojo.html#testClassesDirectory) directory
+1. The [classes](../integration-test-mojo.html#classesDirectory) JAR file or directory
 #{end}
-  [[3]] The project dependencies (with all scopes)
-
-  [[4]] Additional classpath elements
-
-
+1. The project dependencies (with all scopes)
+1. Additional classpath elements
 #{if}(${project.artifactId}=="maven-failsafe-plugin")
-  Notice that loading JAR file is preferable over the output classes directory in the maven-failsafe-plugin.
-  This behavior can be changed by configuration parameter <<<classesDirectory>>>.
-#{end}
 
+    Notice that loading JAR file is preferable over the output classes directory in the maven-failsafe-plugin. This behavior can be changed by configuration parameter `classesDirectory`.
+#{end}
 
-Additional Classpath Elements
+# Additional Classpath Elements
 
-  If you need to put more stuff in your classpath when ${thisPlugin} executes (e.g some funky resources or a container specific JAR),
-  we normally recommend you add it to your classpath as a regular project dependency (with scope <<<test>>>). Consider deploying shared JARs to a private remote repository for your
-  organization.
+If you need to put more stuff in your classpath when ${thisPlugin} executes (e.g some funky resources or a container specific JAR), we normally recommend you add it to your classpath as a regular project dependency (with scope `test`). Consider deploying shared JARs to a private remote repository for your organization.
 
-  In case this leads to dependency conflicts usually separating the test classes from the actual test execution into separate Maven modules is the recommended approach then.
+In case this leads to dependency conflicts usually separating the test classes from the actual test execution into separate Maven modules is the recommended approach then.
 
-  But, if you must, you can use the <<<additionalClasspathElements>>> element to add custom resources/JARs to your test classpath at runtime (without affecting the test classpath used for compilation).
-  The items will be treated as absolute file system paths, so you may want use $\{basedir\} or another property combined with a relative path.
-  Note that additional classpath elements are added to the end of the classpath, so you cannot use these to
-  override project dependencies or resources.
+But, if you must, you can use the `additionalClasspathElements` element to add custom resources/JARs to your test classpath at runtime (without affecting the test classpath used for compilation). The items will be treated as absolute file system paths, so you may want use ${esc.d}{basedir} or another property combined with a relative path. Note that additional classpath elements are added to the end of the classpath, so you cannot use these to override project dependencies or resources.
 
-+---+
+```xml
 <project>
   [...]
   <build>
@@ -86,20 +71,11 @@ Additional Classpath Elements
   </build>
   [...]
 </project>
-+---+
-
-  Since version 3.2.0 the <<<additionalClasspathDependencies>>> parameter can be used to add arbitrary dependencies to your test execution classpath via their regular Maven coordinates.
-  Those are resolved from the repository like regular Maven project dependencies and afterwards added as additional classpath elements to the end of the classpath, so you cannot use these to
-  override project dependencies or resources (except those which are filtered with <<<classpathDependencyExclude>>>).
-  All artifacts of scope <<<compile>>> and <<<runtime>>> scope from the dependency tree rooted in the given dependency are added.
-  The parametrization works like for regular {{{https://maven.apache.org/pom.html#dependencies}Maven dependencies in a POM}}.
-  {{{https://maven.apache.org/pom.html#exclusions}Exclusions}} are supported as well.
-  Neither the dependency management section from the underlying POM is used nor are the conflicts among the different dependency trees 
-  (from the project dependencies or from the additional dependencies) automatically resolved. 
-  Conflicts lead to warnings, though, which help you clean up the classpath manually.
-  Only external dependencies (outside the current Maven reactor) are supported.
-
-+---+
+```
+
+Since version 3.2.0 the `additionalClasspathDependencies` parameter can be used to add arbitrary dependencies to your test execution classpath via their regular Maven coordinates. Those are resolved from the repository like regular Maven project dependencies and afterwards added as additional classpath elements to the end of the classpath, so you cannot use these to override project dependencies or resources (except those which are filtered with `classpathDependencyExclude`). All artifac [...]
+
+```xml
 <project>
   [...]
   <build>
@@ -128,16 +104,13 @@ Additional Classpath Elements
   </build>
   [...]
 </project>
-+---+
-Removing Dependency Classpath Elements
+```
+
+# Removing Dependency Classpath Elements
 
-  Dependencies can be removed from the test classpath using the parameters <<<classpathDependencyExcludes>>> and
-  <<<classpathDependencyScopeExclude>>>.  A list of specific dependencies can be removed from the
-  classpath by specifying the <<<groupId:artifactId>>> to be removed. Details of the pattern matching mechanism
-  are outlined in the goal parameter description for <<<classpathDependencyScopeExcludes>>>.
-  It is important to note that this filtering is only applied to the effective project dependencies (this includes transitive project dependencies).
+Dependencies can be removed from the test classpath using the parameters `classpathDependencyExcludes` and `classpathDependencyScopeExclude`. A list of specific dependencies can be removed from the classpath by specifying the `groupId:artifactId` to be removed. Details of the pattern matching mechanism are outlined in the goal parameter description for `classpathDependencyScopeExcludes`. It is important to note that this filtering is only applied to the effective project dependencies (th [...]
 
-+---+
+```xml
 <project>
   [...]
   <build>
@@ -156,33 +129,29 @@ Removing Dependency Classpath Elements
   </build>
   [...]
 </project>
-+---+
-
-  Dependencies under a certain scope can be removed from the classpath using
-  <<<classpathDependencyScopeExclude>>>.  The valid values for the dependency scope
-  exclude are defined by <<<org.apache.maven.artifact.resolver.filter.ScopeArtifactFilter>>>.
-
-  * <<compile>> - system, provided, compile
-
-  * <<runtime>> - compile, runtime
-
-  * <<test>> - system, provided, compile, runtime, test
-
-+---+
-<project>
-  [...]
-  <build>
-    <plugins>
-      <plugin>
-        <groupId>${project.groupId}</groupId>
-        <artifactId>${project.artifactId}</artifactId>
-        <version>${project.version}</version>
-        <configuration>
-          <classpathDependencyScopeExclude>runtime</classpathDependencyScopeExclude>
-        </configuration>
-      </plugin>
-    </plugins>
-  </build>
-  [...]
-</project>
-+---+
+```
+
+Dependencies under a certain scope can be removed from the classpath using `classpathDependencyScopeExclude`. The valid values for the dependency scope exclude are defined by `org.apache.maven.artifact.resolver.filter.ScopeArtifactFilter`.
+
+- **compile** - system, provided, compile
+- **runtime** - compile, runtime
+- **test** - system, provided, compile, runtime, test
+
+    ```unknown
+    <project>
+      [...]
+      <build>
+        <plugins>
+          <plugin>
+            <groupId>${project.groupId}</groupId>
+            <artifactId>${project.artifactId}</artifactId>
+            <version>${project.version}</version>
+            <configuration>
+              <classpathDependencyScopeExclude>runtime</classpathDependencyScopeExclude>
+            </configuration>
+          </plugin>
+        </plugins>
+      </build>
+      [...]
+    </project>
+    ```
diff --git a/maven-surefire-plugin/src/site/markdown/examples/cucumber.md.vm b/maven-surefire-plugin/src/site/markdown/examples/cucumber.md.vm
index e211be5ee..176ec6c85 100644
--- a/maven-surefire-plugin/src/site/markdown/examples/cucumber.md.vm
+++ b/maven-surefire-plugin/src/site/markdown/examples/cucumber.md.vm
@@ -1,38 +1,37 @@
- ------
- Using Cucumber
- ------
- M.P. Korstanje <ri...@gmail.com>
- ------
- 2010-10-10
- ------
- 
- ~~ 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 
-
-Using Cucumber with JUnit
-
-* Configuring Cucumber JUnit
-
-  To get started with Cucumber, you need to add the required version of Cucumber JUnit to your project:
-
-+---+
+---
+title: Using Cucumber
+author:
+  - M.P. Korstanje rien.korstanje@gmail.com
+date: 2010-10-10
+---
+
+<!--
+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.
+-->
+
+# Using Cucumber with JUnit
+
+Configuring Cucumber JUnit
+--------------------------
+
+To get started with Cucumber, you need to add the required version of Cucumber JUnit to your project:
+
+```xml
  <dependencies>
    [...]
      <dependency>
@@ -43,13 +42,11 @@ Using Cucumber with JUnit
      </dependency>
    [...]
  </dependencies>
-+---+
+```
 
- Then create an empty class that uses the Cucumber JUnit runner.
+Then create an empty class that uses the Cucumber JUnit runner.
 
-#{if}(${project.artifactId}=="maven-surefire-plugin")
-
-+---+
+```java
 package org.sample.cucumber;
 
 import org.junit.runner.RunWith;
@@ -58,58 +55,38 @@ import io.cucumber.junit.CucumberOptions;
 import io.cucumber.junit.Cucumber;
 
 @RunWith( Cucumber.class )
+#{if}(${project.artifactId}=="maven-surefire-plugin")
 public class RunCucumberTest
-{
-  [...]
-}
-+---+
-
 #{else}
-
-+---+
-package org.sample.cucumber;
-
-import org.junit.runner.RunWith;
-
-import io.cucumber.junit.CucumberOptions;
-import io.cucumber.junit.Cucumber;
-
-@RunWith( Cucumber.class )
 public class RunCucumberIT
+#{end}
 {
   [...]
 }
-+---+
-
-#{end}
+```
 
-  This will execute all scenarios in the package of the runner. By default a glue code is assumed to be in the same
-  package. The <<<...@CucumberOptions>>> annotation can be used to provide additional configuration of Cucumber.
+This will execute all scenarios in the package of the runner. By default a glue code is assumed to be in the same package. The `@CucumberOptions` annotation can be used to provide additional configuration of Cucumber.
 
 #{if}(${project.artifactId}=="maven-surefire-plugin")
-  Note that in this example the BDD scenarios are executed by the ${thisPlugin} Plugin in the <<<test>>> phase of the
-  build lifecycle.
+Note that in this example the BDD scenarios are executed by the ${thisPlugin} Plugin in the `test` phase of the build lifecycle.
+#{else}
+Note that in this example the BDD scenarios are executed by the ${thisPlugin} Plugin in the `integration-test` phase of the build lifecycle. The ${thisPlugin} Plugin can be invoked by calling the `verify` phase.
+#{end}
 
-+---+
+```text
+#{if}(${project.artifactId}=="maven-surefire-plugin")
 mvn test
-+---+
-
 #{else}
-  Note that in this example the BDD scenarios are executed by the ${thisPlugin} Plugin in the <<<integration-test>>>
-  phase of the build lifecycle. The ${thisPlugin} Plugin can be invoked by calling the <<<verify>>> phase.
-
-+---+
 mvn verify
-+---+
 #{end}
+```
 
-* Using JUnit Rules
+Using JUnit Rules
+-----------------
 
-  The Cucumber supports JUnit annotations <<<...@ClassRule>>>, <<<...@BeforeClass>>> and <<<...@AfterClass>>>. These are
-  invoked around the suite of features. Using these is not recommended as it limits the portability between different
-  runners. Instead it is recommended to use Cucumbers `Before` and `After` hooks to setup scaffolding.
+The Cucumber supports JUnit annotations `@ClassRule`, `@BeforeClass` and `@AfterClass`. These are invoked around the suite of features. Using these is not recommended as it limits the portability between different runners. Instead it is recommended to use Cucumbers \`Before\` and \`After\` hooks to setup scaffolding.
 
-* Using other JUnit features
+Using other JUnit features
+--------------------------
 
-  The Cucumber runner acts like a suite of a JUnit tests. As such other JUnit features such as Categories, Custom JUnit
-  Listeners and Reporters and re-running failed tests can all be expected to work.
+The Cucumber runner acts like a suite of a JUnit tests. As such other JUnit features such as Categories, Custom JUnit Listeners and Reporters and re-running failed tests can all be expected to work.
diff --git a/maven-surefire-plugin/src/site/markdown/examples/cwd.md b/maven-surefire-plugin/src/site/markdown/examples/cwd.md
index 36248cd44..f656cf749 100644
--- a/maven-surefire-plugin/src/site/markdown/examples/cwd.md
+++ b/maven-surefire-plugin/src/site/markdown/examples/cwd.md
@@ -1,50 +1,41 @@
- ------
- Special characters in directories
- ------
- Tibor Digana
- ------
- 2019-05-10
- ------
-
- ~~ 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
-
-
-Working Directory with special characters
-
- You can use a colon (<<<:>>>) in the cwd on Linux but you have to turn the path separator from colon to
- some other character, see {{{https://issues.apache.org/jira/browse/SUREFIRE-1617}SUREFIRE-1617}}
-
- You should change the classpath separator (we do not guarantee that your application and test would run seamlessly)
- in order to avoid collisions with paths within the forked JVM:
-
-+---+
+---
+title: Special characters in directories
+author:
+  - Tibor Digana
+date: 2019-05-10
+---
+
+<!--
+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.
+-->
+
+# Working Directory with special characters
+
+You can use a colon (`:`) in the cwd on Linux but you have to turn the path separator from colon to some other character, see [SUREFIRE-1617](https://issues.apache.org/jira/browse/SUREFIRE-1617)
+
+You should change the classpath separator (we do not guarantee that your application and test would run seamlessly) in order to avoid collisions with paths within the forked JVM:
+
+```xml
 <argLine>-Dpath.separator=;</argLine>
-+---+
+```
 
- For more information about the configuration parameter <<<workingDirectory>>>
- see the chapter {{{./fork-options-and-parallel-execution.html#Forked_Test_Execution}Forked Test Execution}}.
+For more information about the configuration parameter `workingDirectory` see the chapter [Forked Test Execution](./fork-options-and-parallel-execution.html#Forked_Test_Execution).
 
+# Local Repository with special characters
 
-Local Repository with special characters
-
- The plugin supports special characters (i.e. a colon (<<<:>>>)) in the path of Maven local repository.
- The compiler does not support it and therefore the sources have to be compiled by another command in advance.
-
+The plugin supports special characters (i.e. a colon (`:`)) in the path of Maven local repository. The compiler does not support it and therefore the sources have to be compiled by another command in advance.
diff --git a/maven-surefire-plugin/src/site/markdown/examples/debugging.md.vm b/maven-surefire-plugin/src/site/markdown/examples/debugging.md.vm
index 46abb00c7..c2686c064 100644
--- a/maven-surefire-plugin/src/site/markdown/examples/debugging.md.vm
+++ b/maven-surefire-plugin/src/site/markdown/examples/debugging.md.vm
@@ -1,92 +1,77 @@
-  ------
-  Debugging Tests
-  ------
-  Dan Fabulich
-  ------
-  2010-01-09
-  ------
-  
- ~~ 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
-
-Debugging Tests
-
-  Sometimes you need to debug the tests exactly as Maven ran them.  Here's how!
-
-Forked Tests
-
-  By default, Maven runs your tests in a separate ("forked") process.  You can use the <<<maven.${thisPlugin.toLowerCase()}.debug>>> property
-  to debug your forked tests remotely, like this:
+---
+title: Debugging Tests
+author:
+  - Dan Fabulich
+date: 2010-01-09
+---
 
+<!--
+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.
+-->
+
+# Debugging Tests
+
+Sometimes you need to debug the tests exactly as Maven ran them. Here's how\!
+
+# Forked Tests
+
+By default, Maven runs your tests in a separate ("forked") process. You can use the `maven.${thisPlugin.toLowerCase()}.debug` property to debug your forked tests remotely, like this:
+
+```text
 #{if}(${project.artifactId}=="maven-surefire-plugin")
-+---+
 mvn -Dmaven.${thisPlugin.toLowerCase()}.debug test
-+---+
 #{else}
-+---+
 mvn -Dmaven.${thisPlugin.toLowerCase()}.debug verify
-+---+
 #{end}
+```
 
-  The tests will automatically pause and await a remote debugger on port 5005.  You can then attach to the running tests
-  using Eclipse.  You can setup a "Remote Java Application" launch configuration via the menu
-  command "Run" > "Open Debug Dialog..."
+The tests will automatically pause and await a remote debugger on port 5005. You can then attach to the running tests using Eclipse. You can setup a "Remote Java Application" launch configuration via the menu command "Run" &gt; "Open Debug Dialog..."
 
-  If you need to configure a different port, you may pass a more detailed value.  For example, the command below will use port 8000
-  instead of port 5005.
+If you need to configure a different port, you may pass a more detailed value. For example, the command below will use port 8000 instead of port 5005.
 
+```text
 #{if}(${project.artifactId}=="maven-surefire-plugin")
-+---+
 mvn -Dmaven.${thisPlugin.toLowerCase()}.debug="-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=localhost:8000" test
-+---+
 #{else}
-+---+
 mvn -Dmaven.${thisPlugin.toLowerCase()}.debug="-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=localhost:8000" verify
-+---+
 #{end}
+```
 
-Non-forked Tests
+# Non-forked Tests
 
-  You can force Maven not to fork tests by setting the configuration parameter <<<forkCount>>> to 0.
+You can force Maven not to fork tests by setting the configuration parameter `forkCount` to 0.
 
+```text
 #{if}(${project.artifactId}=="maven-surefire-plugin")
-+---+
 mvn -DforkCount=0 test
-+---+
 #{else}
-+---+
 mvn -DforkCount=0 verify
-+---+
 #{end}
+```
 
-  Then all you need to do is debug Maven itself.  Maven ships with a <<<mvnDebug>>> shell script that you can
-  use to launch Maven with convenient debugging options:
+Then all you need to do is debug Maven itself. Maven ships with a `mvnDebug` shell script that you can use to launch Maven with convenient debugging options:
 
+```text
 #{if}(${project.artifactId}=="maven-surefire-plugin")
-+---+
 mvnDebug -DforkCount=0 test
-+---+
 #{else}
-+---+
 mvnDebug -DforkCount=0 verify
-+---+
 #{end}
+```
 
-  Then you can attach Eclipse to Maven itself, which may be easier/more convenient than debugging the forked executable.
+Then you can attach Eclipse to Maven itself, which may be easier/more convenient than debugging the forked executable.
diff --git a/maven-surefire-plugin/src/site/markdown/examples/fork-options-and-parallel-execution.md.vm b/maven-surefire-plugin/src/site/markdown/examples/fork-options-and-parallel-execution.md.vm
index 7cdbf4a36..197950ee1 100644
--- a/maven-surefire-plugin/src/site/markdown/examples/fork-options-and-parallel-execution.md.vm
+++ b/maven-surefire-plugin/src/site/markdown/examples/fork-options-and-parallel-execution.md.vm
@@ -1,148 +1,78 @@
- ------
- Fork Options and Parallel Test Execution
- ------
- Andreas Gudian
- ------
- 2013-01-03
- ------
-
- ~~ 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
-
-Fork Options and Parallel Test Execution
-
-  Choosing the right forking strategy and parallel execution settings can have
-  substantial impact on the memory requirements and the execution time of your
-  build system.
-
-  The ${thisPlugin.toLowerCase()} offers a variety of options to execute tests
-  in parallel, allowing you to make best use of the hardware at your disposal.
-  But forking in particular can also help keeping the memory requirements low.
-
-  This page shall give you some ideas of how you can configure the test
-  execution in a way best suitable for your environment.
-
-* Parallel Test Execution
-
-  Basically, there are two ways in ${project.artifactId} to achieve parallel test
-  execution.
-  
-  The most obvious one is by using the <<<parallel>>> parameter. The possible
-  values depend on the test provider used. For JUnit 4.7 and onwards, this may
-  be <<<methods>>>, <<<classes>>>, <<<both>>>, <<<suites>>>,
-  <<<suitesAndClasses>>>, <<<suitesAndMethods>>>, <<<classesAndMethods>>> or
-  <<<all>>>. As a prerequisite in JUnit tests, the JUnit runner should extend
-  <<<org.junit.runners.ParentRunner>>>. If no runner is specified through the
-  annotation <<<...@org.junit.runner.RunWith>>>, the prerequisite is accomplished.
-
-  As of ${project.artifactId}:2.16, the value "<<<both>>>" is deprecated but it
-  still can be used and behaves same as <<<classesAndMethods>>>.
-
-  See the example pages for {{{./junit.html#Running_tests_in_parallel}JUnit}}
-  and {{{./testng.html#Running_tests_in_parallel}TestNG}} for details.
-
-  The extension of the parallelism is configured using the following parameters.
-  The parameter <<<useUnlimitedThreads>>> allows for an unlimited number of threads.
-  Unless <<<useUnlimitedThreads=true>>>, the parameter <<<threadCount>>> can be used
-  with the optional parameter <<<perCoreThreadCount=true>>> (true by default).
-  The parameters <<<useUnlimitedThreads>>> and <<<threadCount>>> are to be interpreted
-  in the context of the value specified for the <<<parallel>>> parameter.
-  
-  As of ${project.artifactId}:2.16, one can impose thread-count limitations on
-  suites, classes or methods using one or more of the parameters
-  <<<threadCountSuites>>>, <<<threadCountClasses>>> and <<<threadCountMethods>>>.
-  If only <<<threadCount>>> is specified, ${project.artifactId} attempts to
-  <<optimize>> the thread counts for suites, classes and methods and reuses
-  the threads in favor of a <<leaf>>, e.g. parallel methods (optionally
-  increasing concurrent methods).
-  
-  As an example with an unlimited number of threads, there is maximum of three
-  concurrent threads to execute suites:
-  <<<parallel=all>>>, <<<useUnlimitedThreads=true>>>, <<<threadCountSuites=3>>>.
-  
-  In the second example, the number of concurrent methods is not strictly
-  limited:
-  <<<parallel=classesAndMethods>>>, <<<threadCount=8>>>, <<<threadCountClasses=3>>>.
-  Here the number of parallel methods is varying from 5 to 7.
-  Accordingly <<<parallel=all>>>, but the sum of <<<threadCountSuites>>> and
-  <<<threadCountClasses>>> must not exceed certain (<<<threadCount>>> - 1).
-  Other combinations are possible with unspecified thread-count <<leaf>>.
-  Make sure that the <<leaf>> is last from the order suites-classes-methods
-  in <<<parallel>>>.
-  
-  In the third example the thread-counts represent a ratio, e.g. for
-  <<<parallel=all>>>, <<<threadCount=16>>>, <<<threadCountSuites=2>>>,
-  <<<threadCountClasses=3>>>, <<<threadCountMethods=5>>>. Thus the concurrent
-  suites will be 20%, concurrent classes 30%, and concurrent methods 50%.
-  
-  Finally, the <<<threadCount>>> and <<<useUnlimitedThreads>>> may not be
-  necessarily configured if the equivalent thread-counts are specified for the
-  value in <<<parallel>>>.
-  
-  The ${project.artifactId} is trying to reuse threads, thus <<optimize>>
-  the thread-counts, and prefers thread fairness. The optimization
-  <<<parallelOptimized>>> of the number of Threads is enabled by default in terms
-  of e.g. the number of <Suite> runners do not necessarily have to waste <Suite>'s
-  Thread resources. If <<<threadCount>>> is used, then the <<leaf>> with unlimited
-  thread-count may speed up especially at the end of test phase.
-
-  The parameters <<<parallelTestsTimeoutInSeconds>>> and
-  <<<parallelTestsTimeoutForcedInSeconds>>> are used to specify an optional
-  timeout in parallel execution. If the timeout is elapsed, the plugin prints
-  the summary log with ERROR lines:
-  <"These tests were executed in prior to the shutdown operation">, and
-  <"These tests are incomplete"> if the running Threads were <<interrupted>>.
-
-  <<Note:>> As designed by JUnit runners, the static methods annotated with e.g.
-  <@Parameters>, <@BeforeClass> and <@AfterClass> are called in parent thread.
-  For the sake of memory visibility between threads synchronize the methods.
-  See the keywords: <volatile>, <synchronized>, <<immutable>> and <final> in
-  {{{https://jcp.org/en/jsr/detail?id=133}Java Memory Model - JSR-133}}.
-
-  <<The important thing to remember>> with the <<<parallel>>> option is: the
-  concurrency happens within the same JVM process. That is efficient in terms of
-  memory and execution time, but you may be more vulnerable towards race
-  conditions or other unexpected and hard to reproduce behavior.
-
-  The other possibility for parallel test execution is setting the parameter 
-  <<<forkCount>>> to a value higher than 1. The next section covers the details 
-  about this and the related <<<reuseForks>>> parameter.
-  Using <<<reuseForks=true>>> (by default) and forking the test classes in reusable
-  JVMs may lead to the same problem with shared <static code> across <@BeforeClass>
-  class initializers if using <<<parallel>>> without forking. Therefore setting
-  <<<reuseForks=false>>> may help however it would not guarantee proper
-  functionality of some features, e.g. <<<skipAfterFailureCount>>>.
-
-* Parallel Test Execution and Single Thread Execution
-
-  As mentioned above the <<<parallel>>> test execution is used with specific
-  thread count. Since of ${project.artifactId}:2.18, you can apply the <JCIP>
-  annotation <<<...@net.jcip.annotations.NotThreadSafe>>> on the Java class of JUnit
-  test (pure test class, <Suite>, <Parameterized>, etc.) in order to execute it in
-  single Thread instance. The Thread has name <ma...@NotThreadSafe>
-  and it is executed at the end of the test run.
-
-  Just use project dependency <net.jcip:jcip-annotations:1.0> or another artifact
-  <com.github.stephenc.jcip:jcip-annotations:1.0-1> with Apache License 2.0.
-  
-+---+
+---
+title: Fork Options and Parallel Test Execution
+author:
+  - Andreas Gudian
+date: 2013-01-03
+---
+
+<!--
+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.
+-->
+
+# Fork Options and Parallel Test Execution
+
+Choosing the right forking strategy and parallel execution settings can have substantial impact on the memory requirements and the execution time of your build system.
+
+The ${thisPlugin.toLowerCase()} offers a variety of options to execute tests in parallel, allowing you to make best use of the hardware at your disposal. But forking in particular can also help keeping the memory requirements low.
+
+This page shall give you some ideas of how you can configure the test execution in a way best suitable for your environment.
+
+Parallel Test Execution
+-----------------------
+
+Basically, there are two ways in ${project.artifactId} to achieve parallel test execution.
+
+The most obvious one is by using the `parallel` parameter. The possible values depend on the test provider used. For JUnit 4.7 and onwards, this may be `methods`, `classes`, `both`, `suites`, `suitesAndClasses`, `suitesAndMethods`, `classesAndMethods` or `all`. As a prerequisite in JUnit tests, the JUnit runner should extend `org.junit.runners.ParentRunner`. If no runner is specified through the annotation `@org.junit.runner.RunWith`, the prerequisite is accomplished.
+
+As of ${project.artifactId}:2.16, the value "`both`" is deprecated but it still can be used and behaves same as `classesAndMethods`.
+
+See the example pages for [JUnit](./junit.html#Running_tests_in_parallel) and [TestNG](./testng.html#Running_tests_in_parallel) for details.
+
+The extension of the parallelism is configured using the following parameters. The parameter `useUnlimitedThreads` allows for an unlimited number of threads. Unless `useUnlimitedThreads=true`, the parameter `threadCount` can be used with the optional parameter `perCoreThreadCount=true` (true by default). The parameters `useUnlimitedThreads` and `threadCount` are to be interpreted in the context of the value specified for the `parallel` parameter.
+
+As of ${project.artifactId}:2.16, one can impose thread-count limitations on suites, classes or methods using one or more of the parameters `threadCountSuites`, `threadCountClasses` and `threadCountMethods`. If only `threadCount` is specified, ${project.artifactId} attempts to **optimize** the thread counts for suites, classes and methods and reuses the threads in favor of a **leaf**, e.g. parallel methods (optionally increasing concurrent methods).
+
+As an example with an unlimited number of threads, there is maximum of three concurrent threads to execute suites: `parallel=all`, `useUnlimitedThreads=true`, `threadCountSuites=3`.
+
+In the second example, the number of concurrent methods is not strictly limited: `parallel=classesAndMethods`, `threadCount=8`, `threadCountClasses=3`. Here the number of parallel methods is varying from 5 to 7. Accordingly `parallel=all`, but the sum of `threadCountSuites` and `threadCountClasses` must not exceed certain (`threadCount` - 1). Other combinations are possible with unspecified thread-count **leaf**. Make sure that the **leaf** is last from the order suites-classes-methods i [...]
+
+In the third example the thread-counts represent a ratio, e.g. for `parallel=all`, `threadCount=16`, `threadCountSuites=2`, `threadCountClasses=3`, `threadCountMethods=5`. Thus the concurrent suites will be 20%, concurrent classes 30%, and concurrent methods 50%.
+
+Finally, the `threadCount` and `useUnlimitedThreads` may not be necessarily configured if the equivalent thread-counts are specified for the value in `parallel`.
+
+The ${project.artifactId} is trying to reuse threads, thus **optimize** the thread-counts, and prefers thread fairness. The optimization `parallelOptimized` of the number of Threads is enabled by default in terms of e.g. the number of _Suite_ runners do not necessarily have to waste _Suite_'s Thread resources. If `threadCount` is used, then the **leaf** with unlimited thread-count may speed up especially at the end of test phase.
+
+The parameters `parallelTestsTimeoutInSeconds` and `parallelTestsTimeoutForcedInSeconds` are used to specify an optional timeout in parallel execution. If the timeout is elapsed, the plugin prints the summary log with ERROR lines: _"These tests were executed in prior to the shutdown operation"_, and _"These tests are incomplete"_ if the running Threads were **interrupted**.
+
+**Note:** As designed by JUnit runners, the static methods annotated with e.g. _@Parameters_, _@BeforeClass_ and _@AfterClass_ are called in parent thread. For the sake of memory visibility between threads synchronize the methods. See the keywords: _volatile_, _synchronized_, **immutable** and _final_ in [Java Memory Model - JSR-133](https://jcp.org/en/jsr/detail?id=133).
+
+**The important thing to remember** with the `parallel` option is: the concurrency happens within the same JVM process. That is efficient in terms of memory and execution time, but you may be more vulnerable towards race conditions or other unexpected and hard to reproduce behavior.
+
+The other possibility for parallel test execution is setting the parameter `forkCount` to a value higher than 1. The next section covers the details about this and the related `reuseForks` parameter. Using `reuseForks=true` (by default) and forking the test classes in reusable JVMs may lead to the same problem with shared _static code_ across _@BeforeClass_ class initializers if using `parallel` without forking. Therefore setting `reuseForks=false` may help however it would not guarantee [...]
+
+Parallel Test Execution and Single Thread Execution
+---------------------------------------------------
+
+As mentioned above the `parallel` test execution is used with specific thread count. Since of ${project.artifactId}:2.18, you can apply the _JCIP_ annotation `@net.jcip.annotations.NotThreadSafe` on the Java class of JUnit test (pure test class, _Suite_, _Parameterized_, etc.) in order to execute it in single Thread instance. The Thread has name _maven-surefire-plugin@NotThreadSafe_ and it is executed at the end of the test run.
+
+Just use project dependency _net.jcip:jcip-annotations:1.0_ or another artifact _com.github.stephenc.jcip:jcip-annotations:1.0-1_ with Apache License 2.0.
+
+```xml
 <dependencies>
   [...]
   <dependency>
@@ -160,35 +90,22 @@ Fork Options and Parallel Test Execution
   </dependency>
   [...]
 </dependencies>
-+---+
+```
 
-  This way the parallel execution of tests classes annotated with
-  <<<...@NotThreadSafe>>> are forked in single thread instance (don't mean
-  forked JVM process).
+This way the parallel execution of tests classes annotated with `@NotThreadSafe` are forked in single thread instance (don't mean forked JVM process).
 
-  If the <Suite> or <Parameterized> is annotated with <<<...@NotThreadSafe>>>, the
-  suite classes are executed in single thread.
-  You can also annotate individual test class referenced by <Suite>, and the other
-  unannotated test classes in the <Suite> can be subject to run in parallel.
-  This way you can isolate conflicting groups of tests and still run their
-  individual tests in parallel.
+If the _Suite_ or _Parameterized_ is annotated with `@NotThreadSafe`, the suite classes are executed in single thread. You can also annotate individual test class referenced by _Suite_, and the other unannotated test classes in the _Suite_ can be subject to run in parallel. This way you can isolate conflicting groups of tests and still run their individual tests in parallel.
 
-  <<Note:>> As designed by JUnit runners, the static methods annotated with e.g.
-  <@Parameters>, <@BeforeClass> and <@AfterClass> are called in parent thread.
-  Assign classes to <<<@NotThreadSafe Suite>>> to prevent from this trouble. If you
-  do not want to change the hierarchy of your test classes, you may synchronize such
-  methods for the sake of improving memory visibility as a simplistic treatment.
-  See the keywords: <volatile>, <synchronized>, <<immutable>> and <final> in
-  {{{https://jcp.org/en/jsr/detail?id=133}Java Memory Model - JSR-133}}.
+**Note:** As designed by JUnit runners, the static methods annotated with e.g. _@Parameters_, _@BeforeClass_ and _@AfterClass_ are called in parent thread. Assign classes to `@NotThreadSafe Suite` to prevent from this trouble. If you do not want to change the hierarchy of your test classes, you may synchronize such methods for the sake of improving memory visibility as a simplistic treatment. See the keywords: _volatile_, _synchronized_, **immutable** and _final_ in [Java Memory Model -  [...]
 
-* Parallel Test-Suite Execution
+Parallel Test-Suite Execution
+-----------------------------
 
-  ${project.artifactId}'s notion of "suite" is related to
-  {{{https://github.com/junit-team/junit4/wiki/Aggregating-tests-in-suites}junit4 Suite}}. 
+${project.artifactId}'s notion of "suite" is related to [junit4 Suite](https://github.com/junit-team/junit4/wiki/Aggregating-tests-in-suites).
 
-  For example, say your tests are laid out like this:
+For example, say your tests are laid out like this:
 
-+---+
+```text
 src/test/java
 +-features.areaA
 | +-SomeTest.java
@@ -196,11 +113,11 @@ src/test/java
 +-features.areaB
 | +-DifferentTest.java
 | +-OtherTest.java
-+---+
+```
 
-  You would add a TestSuite.java for each package, that would look something like:
+You would add a TestSuite.java for each package, that would look something like:
 
-+---+
+```java
 package features.areaA;
 
 import org.junit.runner.RunWith;
@@ -213,12 +130,11 @@ import org.junit.runners.Suite;
 })
 public class TestSuite {
 }
-+---+
+```
 
-  and similarly for <<<package features.areaB>>>. You would then configure
-  ${project.artifactId} as follows:
+and similarly for `package features.areaB`. You would then configure ${project.artifactId} as follows:
 
-+---+
+```xml
 <plugin>
   <groupId>${project.groupId}</groupId>
   <artifactId>${project.artifactId}</artifactId>
@@ -232,77 +148,39 @@ public class TestSuite {
     <perCoreThreadCount>false</perCoreThreadCount>
   </configuration>
 </plugin>
-+---+
-
-  This would then run up to 2 threads, and each thread would be fed a TestSuite.class,
-  one at a time. The test classes within that Suite would be executed sequentially
-  in the order specified the Suite class.
-
-  Note that the <<<perCoreThreadCount>>> is a "multiplier" of a sorts. With this
-  parameter set to true (the default value), you will get the specified number of
-  threads <<per CPU core>>.
-
-  Also note that in this specific case <<<threadCountSuites=2>>> has the same effect
-  as <<<threadCount=2>>>, since we are using <<<parallel=suites>>>.
-
-* Parallel ${project.artifactId} Execution in Multi-Module Maven Parallel Build
-
-  Maven core allows building modules of multi-module projects in parallel with
-  the command line option <<<-T>>>. This <multiplies> the extent of concurrency
-  configured directly in ${project.artifactId}.
-
-* Forked Test Execution
-
-  The parameter <<<forkCount>>> defines the maximum number of JVM processes that
-  ${project.artifactId} will spawn <concurrently> to execute the tests. It supports
-  the same syntax as <<<-T>>> in maven-core: if you terminate the value with a 'C',
-  that value will be multiplied with the number of available CPU cores in your
-  system. For example <<<forkCount=2.5C>>> on a Quad-Core system will result
-  in forking up to ten concurrent JVM processes that execute tests.
-
-  The parameter <<<reuseForks>>> is used to define whether to terminate the 
-  spawned process after one test class and to create a new process for the next 
-  test in line (<<<reuseForks=false>>>), or whether to reuse the processes to 
-  execute the next tests (<<<reuseForks=true>>>).
-
-  The <default setting> is <<<forkCount=1>>>/<<<reuseForks=true>>>, which means
-  that ${project.artifactId} creates one new JVM process to execute all tests
-  in one Maven module.
-
-  <<<forkCount=1>>>/<<<reuseForks=false>>> executes each test class in its own 
-  JVM process, one after another. It creates the highest level of separation for 
-  the test execution, but it would probably also give you the longest execution 
-  time of all the available options. Consider it as a last resort.
-
-  With the <<<argLine>>> property, you can specify additional parameters to be
-  passed to the forked JVM process, such as memory settings. System property
-  variables from the main maven process are passed to the forked process as
-  well. Additionally, you can use the element <<<systemPropertyVariables>>> to
-  specify variables and values to be added to the system properties during the
-  test execution.
-
-  You can use the placeholder <<<$\{surefire.forkNumber\}>>> within <<<argLine>>>,
-  <<<environmentVariables>>> (since ${project.artifactId}:3.2.0),
-  or within the system properties (both those specified via
-  <<<mvn test -D...>>> and via <<<systemPropertyVariables>>>). Before executing 
-  the tests, the ${thisPlugin.toLowerCase()} plugin replaces that placeholder
-  by the number of the actually executing process, counting from 1 to the
-  effective value of <<<forkCount>>> times the maximum number of parallel
-  executions in Maven parallel builds, i.e. the effective value of the <<<-T>>>
-  command line argument of Maven core.
-
-  In case of disabled forking (<<<forkCount=0>>>), the placeholder will be
-  replaced with <1>.
-
-  The following is an example configuration that makes use of up to three forked
-  processes that execute the tests and then terminate. A system property
-  <databaseSchema> is passed to the processes, that shall specify the database
-  schema to use during the tests. The values for that will be
-  <MY_TEST_SCHEMA_1>, <MY_TEST_SCHEMA_2>, and <MY_TEST_SCHEMA_3> for the three
-  processes. Additionaly by specifying custom <workingDirectory> each of processes
-  will be executed in a separate working directory to ensure isolation on file system level.
-
-+---+
+```
+
+This would then run up to 2 threads, and each thread would be fed a TestSuite.class, one at a time. The test classes within that Suite would be executed sequentially in the order specified the Suite class.
+
+Note that the `perCoreThreadCount` is a "multiplier" of a sorts. With this parameter set to true (the default value), you will get the specified number of threads **per CPU core**.
+
+Also note that in this specific case `threadCountSuites=2` has the same effect as `threadCount=2`, since we are using `parallel=suites`.
+
+Parallel ${project.artifactId} Execution in Multi-Module Maven Parallel Build
+-----------------------------------------------------------------------------
+
+Maven core allows building modules of multi-module projects in parallel with the command line option `-T`. This _multiplies_ the extent of concurrency configured directly in ${project.artifactId}.
+
+Forked Test Execution
+---------------------
+
+The parameter `forkCount` defines the maximum number of JVM processes that ${project.artifactId} will spawn _concurrently_ to execute the tests. It supports the same syntax as `-T` in maven-core: if you terminate the value with a 'C', that value will be multiplied with the number of available CPU cores in your system. For example `forkCount=2.5C` on a Quad-Core system will result in forking up to ten concurrent JVM processes that execute tests.
+
+The parameter `reuseForks` is used to define whether to terminate the spawned process after one test class and to create a new process for the next test in line (`reuseForks=false`), or whether to reuse the processes to execute the next tests (`reuseForks=true`).
+
+The _default setting_ is `forkCount=1`/`reuseForks=true`, which means that ${project.artifactId} creates one new JVM process to execute all tests in one Maven module.
+
+`forkCount=1`/`reuseForks=false` executes each test class in its own JVM process, one after another. It creates the highest level of separation for the test execution, but it would probably also give you the longest execution time of all the available options. Consider it as a last resort.
+
+With the `argLine` property, you can specify additional parameters to be passed to the forked JVM process, such as memory settings. System property variables from the main maven process are passed to the forked process as well. Additionally, you can use the element `systemPropertyVariables` to specify variables and values to be added to the system properties during the test execution.
+
+You can use the placeholder `${esc.d}{surefire.forkNumber}` within `argLine`, `environmentVariables` (since ${project.artifactId}:3.2.0), or within the system properties (both those specified via `mvn test -D...` and via `systemPropertyVariables`). Before executing the tests, the ${thisPlugin.toLowerCase()} plugin replaces that placeholder by the number of the actually executing process, counting from 1 to the effective value of `forkCount` times the maximum number of parallel executions [...]
+
+In case of disabled forking (`forkCount=0`), the placeholder will be replaced with _1_.
+
+The following is an example configuration that makes use of up to three forked processes that execute the tests and then terminate. A system property _databaseSchema_ is passed to the processes, that shall specify the database schema to use during the tests. The values for that will be _MY\_TEST\_SCHEMA\_1_, _MY\_TEST\_SCHEMA\_2_, and _MY\_TEST\_SCHEMA\_3_ for the three processes. Additionaly by specifying custom _workingDirectory_ each of processes will be executed in a separate working [...]
+
+```xml
 <plugins>
 [...]
   <plugin>
@@ -314,37 +192,27 @@ public class TestSuite {
         <reuseForks>true</reuseForks>
         <argLine>-Xmx1024m -XX:MaxPermSize=256m</argLine>
         <systemPropertyVariables>
-            <databaseSchema>MY_TEST_SCHEMA_${surefire.forkNumber}</databaseSchema>
+            <databaseSchema>MY_TEST_SCHEMA_${esc.d}{surefire.forkNumber}</databaseSchema>
         </systemPropertyVariables>
-        <workingDirectory>FORK_DIRECTORY_${surefire.forkNumber}</workingDirectory>
+        <workingDirectory>FORK_DIRECTORY_${esc.d}{surefire.forkNumber}</workingDirectory>
     </configuration>
   </plugin>
 [...]
 </plugins>
-+---+
-
-  In case of a multi module project with tests in different modules, you could 
-  also use, say, <<<mvn -T 2 ...>>> to start the build, yielding values for 
-  <<<$\{surefire.forkNumber\}>>> ranging from 1 to 6.
-
-  Imagine you execute some tests that use a JPA context, which has a notable
-  initial startup time. By setting <<<reuseForks=true>>>, you can reuse that
-  context for consecutive tests. And as many tests tend to use and access the
-  same test data, you can avoid database locks during the concurrent execution
-  by using distinct but uniform database schemas.
-
-  Port numbers and file names are other examples of resources for which it may
-  be hard or undesired to be shared among concurrent test executions.
-  
-* Isolating report directories across forks
-  
-  You may run multiple TestNG suites in parallel fork JVM processes. In that case
-  one can see that each process has created XML report file with same name
-  overriding one each other. In order to prevent from this, you may want to change
-  report directory for each Suite XML. Since of Version 2.22.1 you can parameterize
-  <<<reportsDirectory>>> with placeholder <<<$\{surefire.forkNumber\}>>>.
-  
-+---+
+```
+
+In case of a multi module project with tests in different modules, you could also use, say, `mvn -T 2 ...` to start the build, yielding values for `${esc.d}{surefire.forkNumber}` ranging from 1 to 6.
+
+Imagine you execute some tests that use a JPA context, which has a notable initial startup time. By setting `reuseForks=true`, you can reuse that context for consecutive tests. And as many tests tend to use and access the same test data, you can avoid database locks during the concurrent execution by using distinct but uniform database schemas.
+
+Port numbers and file names are other examples of resources for which it may be hard or undesired to be shared among concurrent test executions.
+
+Isolating report directories across forks
+-----------------------------------------
+
+You may run multiple TestNG suites in parallel fork JVM processes. In that case one can see that each process has created XML report file with same name overriding one each other. In order to prevent from this, you may want to change report directory for each Suite XML. Since of Version 2.22.1 you can parameterize `reportsDirectory` with placeholder `${esc.d}{surefire.forkNumber}`.
+
+```xml
 [...]
 <dependencies>
     [...]
@@ -367,7 +235,7 @@ public class TestSuite {
 		    <configuration>
 			    <forkCount>2</forkCount>
 			    <reuseForks>false</reuseForks>
-			    <reportsDirectory>target/surefire-reports-${surefire.forkNumber}</reportsDirectory>
+			    <reportsDirectory>target/surefire-reports-${esc.d}{surefire.forkNumber}</reportsDirectory>
 			    <suiteXmlFiles>
 				    <suiteXmlFile>src/test/resources/Suite1.xml</suiteXmlFile>
 				    <suiteXmlFile>src/test/resources/Suite2.xml</suiteXmlFile>
@@ -377,30 +245,17 @@ public class TestSuite {
         [...]
     </plugins>
 </build>
-+---+
+```
 
-* Combining forkCount and parallel
+Combining forkCount and parallel
+--------------------------------
 
-  The modes <<<forkCount=0>>> and <<<forkCount=1>>>/<<<reuseForks=true>>> can
-  be combined freely with the available settings for <<<parallel>>>.
+The modes `forkCount=0` and `forkCount=1`/`reuseForks=true` can be combined freely with the available settings for `parallel`.
 
-  As <<<reuseForks=false>>> creates a new JVM process for each test class,
-  using <<<parallel=classes>>> would have no effect. You can still use
-  <<<parallel=methods>>>, though.
+As `reuseForks=false` creates a new JVM process for each test class, using `parallel=classes` would have no effect. You can still use `parallel=methods`, though.
 
-  When using <<<reuseForks=true>>> and a <<<forkCount>>> value larger than one,
-  test classes are handed over to the forked process one-by-one. Thus,
-  <<<parallel=classes>>> would not change anything. However, you can use
-  <<<parallel=methods>>>: classes are executed in <<<forkCount>>> concurrent
-  processes, each of the processes can then use <<<threadCount>>> threads to
-  execute the methods of one class in parallel.
+When using `reuseForks=true` and a `forkCount` value larger than one, test classes are handed over to the forked process one-by-one. Thus, `parallel=classes` would not change anything. However, you can use `parallel=methods`: classes are executed in `forkCount` concurrent processes, each of the processes can then use `threadCount` threads to execute the methods of one class in parallel.
 
-  Regarding the compatibility with multi-module parallel maven builds via 
-  <<<-T>>>, the only limitation is that you can not use it together with
-  <<<forkCount=0>>>.
+Regarding the compatibility with multi-module parallel maven builds via `-T`, the only limitation is that you can not use it together with `forkCount=0`.
 
-  When running parallel maven builds without forks, all system properties
-  are shared among the builder threads and ${thisPlugin.toLowerCase()} executions,
-  therefore the threads will encounter race conditions when setting
-  properties, e.g. <<<baseDir>>>, which may lead to changing system properties
-  and unexpected runtime behaviour.
+When running parallel maven builds without forks, all system properties are shared among the builder threads and ${thisPlugin.toLowerCase()} executions, therefore the threads will encounter race conditions when setting properties, e.g. `baseDir`, which may lead to changing system properties and unexpected runtime behaviour.
diff --git a/maven-surefire-plugin/src/site/markdown/examples/inclusion-exclusion.md.vm b/maven-surefire-plugin/src/site/markdown/examples/inclusion-exclusion.md.vm
index a66b7b385..8007b11a1 100644
--- a/maven-surefire-plugin/src/site/markdown/examples/inclusion-exclusion.md.vm
+++ b/maven-surefire-plugin/src/site/markdown/examples/inclusion-exclusion.md.vm
@@ -1,69 +1,50 @@
-  ------
-  Inclusions and Exclusions of Tests
-  ------
-  Allan Ramirez
-  ------
-  2010-01-09
-  ------
-
- ~~ 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
-
-Inclusions and Exclusions of Tests
-
-* Inclusions
-
-  By default, the ${thisPlugin} Plugin will automatically include all test classes
-  with the following wildcard patterns:
+---
+title: Inclusions and Exclusions of Tests
+author:
+  - Allan Ramirez
+date: 2010-01-09
+---
+
+<!--
+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.
+-->
+
+# Inclusions and Exclusions of Tests
+
+Inclusions
+----------
+
+By default, the ${thisPlugin} Plugin will automatically include all test classes with the following wildcard patterns:
 
 #{if}(${project.artifactId}=="maven-surefire-plugin")
-   * <<<"**/Test*.java">>> - includes all of its subdirectories and all Java
-   filenames that start with "Test".
-
-   * <<<"**/*Test.java">>> - includes all of its subdirectories and all Java
-   filenames that end with "Test".
-
-   * <<<"**/*Tests.java">>> - includes all of its subdirectories and all Java
-   filenames that end with "Tests".
-
-   * <<<"**/*TestCase.java">>> - includes all of its subdirectories and all Java
-   filenames that end with "TestCase".
-
+- `"**/Test*.java"` - includes all of its subdirectories and all Java filenames that start with "Test".
+- `"**/*Test.java"` - includes all of its subdirectories and all Java filenames that end with "Test".
+- `"**/*Tests.java"` - includes all of its subdirectories and all Java filenames that end with "Tests".
+- `"**/*TestCase.java"` - includes all of its subdirectories and all Java filenames that end with "TestCase".
 #{else}
-   * <<<"**/IT*.java">>> - includes all of its subdirectories and all Java
-   filenames that start with "IT".
-
-   * <<<"**/*IT.java">>> - includes all of its subdirectories and all Java
-   filenames that end with "IT".
-
-   * <<<"**/*ITCase.java">>> - includes all of its subdirectories and all Java
-   filenames that end with "ITCase".
-
+- `"**/IT*.java"` - includes all of its subdirectories and all Java filenames that start with "IT".
+- `"**/*IT.java"` - includes all of its subdirectories and all Java filenames that end with "IT".
+- `"**/*ITCase.java"` - includes all of its subdirectories and all Java filenames that end with "ITCase".
 #{end}
 
-   []
-
-  If the test classes do not follow the default wildcard patterns, then override them by configuring the ${thisPlugin}
-  Plugin and specify the tests you want to include (or exclude) or another patterns.
+If the test classes do not follow the default wildcard patterns, then override them by configuring the ${thisPlugin} Plugin and specify the tests you want to include (or exclude) or another patterns.
 
-+---+
+```xml
 <project>
   [...]
   <build>
@@ -82,17 +63,14 @@ Inclusions and Exclusions of Tests
   </build>
   [...]
 </project>
-+---+
+```
 
-* Exclusions
+Exclusions
+----------
 
-  There are certain times when some tests are causing the build to fail.
-  Excluding them is one of the best workarounds to continue the build.
-  Exclusions can be done by configuring the <<<excludes>>> property of the
-  plugin.
+There are certain times when some tests are causing the build to fail. Excluding them is one of the best workarounds to continue the build. Exclusions can be done by configuring the `excludes` property of the plugin.
 
-#{if}(${project.artifactId}=="maven-surefire-plugin")
-+---+
+```xml
 <project>
   [...]
   <build>
@@ -103,30 +81,13 @@ Inclusions and Exclusions of Tests
         <version>${project.version}</version>
         <configuration>
           <excludes>
+#{if}(${project.artifactId}=="maven-surefire-plugin")
             <exclude>**/TestCircle.java</exclude>
             <exclude>**/TestSquare.java</exclude>
-          </excludes>
-        </configuration>
-      </plugin>
-    </plugins>
-  </build>
-  [...]
-</project>
-+---+
 #{else}
-+---+
-<project>
-  [...]
-  <build>
-    <plugins>
-      <plugin>
-        <groupId>${project.groupId}</groupId>
-        <artifactId>${project.artifactId}</artifactId>
-        <version>${project.version}</version>
-        <configuration>
-          <excludes>
             <exclude>**/CircleIT.java</exclude>
             <exclude>**/SquareIT.java</exclude>
+#{end}
           </excludes>
         </configuration>
       </plugin>
@@ -134,15 +95,14 @@ Inclusions and Exclusions of Tests
   </build>
   [...]
 </project>
-+---+
-#{end}
+```
 
-* Regular Expression Support
+Regular Expression Support
+--------------------------
 
-  An include/exclude pattern can be an ant-style path expression, but
-  regular expressions are also supported through this syntax:
+An include/exclude pattern can be an ant-style path expression, but regular expressions are also supported through this syntax:
 
-+---+
+```xml
 <project>
   [...]
   <build>
@@ -161,65 +121,52 @@ Inclusions and Exclusions of Tests
   </build>
   [...]
 </project>
-+---+
-
-  Note the syntax <<<%regex[expr]>>>, where <<<expr>>> is the actual expression and the rest is just wrapping. Also
-  note the following about the use of regular expressions:
+```
 
-   * Regex matches are done over <<<*.class>>> files and not <<<*.java>>> files
+Note the syntax `%regex[expr]`, where `expr` is the actual expression and the rest is just wrapping. Also note the following about the use of regular expressions:
 
-   * Regex matches are done over paths using slashes ("<<</>>>") and not package names using dots ("<<<.>>>"), so the
-      "<<<.>>>" in <<<pkg.*Slow.*.class>>> is a regex metacharacter, which happens to match any character, notably
-      the (forward) slashes ("<<</>>>") that make up the path. Slashes here are <forward>, even on Windows
+- Regex matches are done over `*.class` files and not `*.java` files
+- Regex matches are done over paths using slashes ("`/`") and not package names using dots ("`.`"), so the "`.`" in `pkg.*Slow.*.class` is a regex metacharacter, which happens to match any character, notably the (forward) slashes ("`/`") that make up the path. Slashes here are _forward_, even on Windows
+- The trailing `.class` is interpreted literally, and not as a regular expression ("`\.class`" does not work here)
 
-   * The trailing <<<.class>>> is interpreted literally, and not as a regular expression ("<<<\.class>>>" does not
-      work here)
+Multiple Formats in One
+-----------------------
 
-* Multiple Formats in One
+As of ${thisPlugin} Plugin 2.19, a complex syntax is supported in one parameter (JUnit 4, JUnit 4.7+, TestNG):
 
-  As of ${thisPlugin} Plugin 2.19, a complex syntax is supported in one parameter (JUnit 4, JUnit 4.7+, TestNG):
-
-+---+
+```xml
   [...]
           <include>%regex[.*(Cat|Dog).*], !%regex[pkg.*Slow.*.class], pkg/**/*Fast*.java, Basic????, !Unstable*</include>
   [...]
           <exclude>%regex[pkg.*Slow.*.class], Unstable*</exclude>
   [...]
-+---+
+```
 
-  This syntax can be used in parameters: <<<test>>>, <<<includes>>>, <<<excludes>>>, <<<includesFile>>>, <<<excludesFile>>>.
-  Exclamation mark (!) excludes tests. The syntax in parameter <<<excludes>>> and <<<excludesFile>>> should not use (!).
-  The character (?) within non-regex pattern replaces one character in file name or path. The file extensions are not
-  mandatory in non-regex patterns, and packages with slash can be used. The regex validates fully qualified class file.
-  The regex supports '.class' file extension only. Note the regex comments, marked by (#) character, are unsupported.
+This syntax can be used in parameters: `test`, `includes`, `excludes`, `includesFile`, `excludesFile`. Exclamation mark (\!) excludes tests. The syntax in parameter `excludes` and `excludesFile` should not use (\!). The character (?) within non-regex pattern replaces one character in file name or path. The file extensions are not mandatory in non-regex patterns, and packages with slash can be used. The regex validates fully qualified class file. The regex supports '.class' file extension [...]
 
-* Fully qualified class name
+Fully qualified class name
+--------------------------
 
-  As of ${thisPlugin} Plugin 2.19.1, the syntax with fully qualified class names or packages can be used, e.g.:
+As of ${thisPlugin} Plugin 2.19.1, the syntax with fully qualified class names or packages can be used, e.g.:
 
-+---+
+```xml
   [...]
           <include>my.package.*, another.package.*</include>
   [...]
           <exclude>my.package.???ExcludedTest, another.package.*ExcludedTest</exclude>
   [...]
-+---+
-
-  The character (?) replaces single character and (*) represents zero or more characters.
-  Multiple formats can be additionally combined.
-  This syntax can be used in parameters: <<<test>>>, <<<includes>>>, <<<excludes>>>, <<<includesFile>>>, <<<excludesFile>>>.
-
-* Tests from dependencies
-
-  In order to scan dependencies by the ${thisPlugin} plugin and find the test classes to execute in the dependencies,
-  use the MOJO parameter <<<dependenciesToScan>>> and configure it as necessary.
-  Dependencies can be specified using the <<<groupId[:artifactId[:type[:classifier][:version]]]>>> format, and must
-  already be <<<dependency>>> elements in scope.
-  
-  <Note:> Support for version, type and classifier was introduced in version <<<3.0.0-M4>>>. When using earlier versions,
-  ${thisPlugin} will fail with an <<<IllegalArgumentException>>> if more than groupId and artifactId are specified.
-  
-+---+
+```
+
+The character (?) replaces single character and (*) represents zero or more characters. Multiple formats can be additionally combined. This syntax can be used in parameters: `test`, `includes`, `excludes`, `includesFile`, `excludesFile`.
+
+Tests from dependencies
+-----------------------
+
+In order to scan dependencies by the ${thisPlugin} plugin and find the test classes to execute in the dependencies, use the MOJO parameter `dependenciesToScan` and configure it as necessary. Dependencies can be specified using the `groupId[:artifactId[:type[:classifier][:version]]]` format, and must already be `dependency` elements in scope.
+
+_Note:_ Support for version, type and classifier was introduced in version `3.0.0-M4`. When using earlier versions, ${thisPlugin} will fail with an `IllegalArgumentException` if more than groupId and artifactId are specified.
+
+```xml
 <project>
   [...]
   <build>
@@ -240,13 +187,10 @@ Inclusions and Exclusions of Tests
   </build>
   [...]
 </project>
-+---+
-
-  The configuration above will search for test classes in:
-
-    * All dependencies with the groupId <<<org.acme>>> and artifactId <<<project-a>>>
-
-    * All dependencies with the groupId <<<org.acme>>> and artifactId <<<project-b>>> and type <<<test-jar>>>
+```
 
-    * All dependencies with the groupId <<<org.acme>>> and artifactId <<<project-c>>> and classifier <<<tests-jdk15>>>
+The configuration above will search for test classes in:
 
+- All dependencies with the groupId `org.acme` and artifactId `project-a`
+- All dependencies with the groupId `org.acme` and artifactId `project-b` and type `test-jar`
+- All dependencies with the groupId `org.acme` and artifactId `project-c` and classifier `tests-jdk15`
diff --git a/maven-surefire-plugin/src/site/markdown/examples/jpms.md.vm b/maven-surefire-plugin/src/site/markdown/examples/jpms.md.vm
index f3727a3a6..5e89c380c 100644
--- a/maven-surefire-plugin/src/site/markdown/examples/jpms.md.vm
+++ b/maven-surefire-plugin/src/site/markdown/examples/jpms.md.vm
@@ -1,45 +1,39 @@
- ------
- Java Modularity (JPMS) in Tests
- ------
- dev@maven.apache.org
- ------
- 2020-05-29
- ------
-
- ~~ 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
-
-Using Java Modularity (JPMS) in Tests
-
-* Examples using TestNG
-
-  The Surefire project provides the integration tests with
-  {{{https://github.com/apache/maven-surefire/tree/master/surefire-its/src/test/resources/surefire-1733-testng}TestNG}}
-  demonstrating the Java Modularity (JPMS).
-
-  The JDK version must be 9 or higher. The POM contains the dependency <<<org.testng:testng:7.1.0>>> which is
-  an automatic module. It activates the internal provider <<<surefire-testng>>> in the plugin. The frameworks with
-  assertions API are used, i.e. <<<org.hamcrest:hamcrest:2.2>>> (automatic module)
-  and <<<org.assertj:assertj-core:3.16.1>>> (named module).
-
-+---+
+---
+title: Java Modularity (JPMS) in Tests
+author:
+  - dev@maven.apache.org
+date: 2020-05-29
+---
+
+<!--
+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.
+-->
+
+# Using Java Modularity (JPMS) in Tests
+
+Examples using TestNG
+---------------------
+
+The Surefire project provides the integration tests with [TestNG](https://github.com/apache/maven-surefire/tree/master/surefire-its/src/test/resources/surefire-1733-testng) demonstrating the Java Modularity (JPMS).
+
+The JDK version must be 9 or higher. The POM contains the dependency `org.testng:testng:7.1.0` which is an automatic module. It activates the internal provider `surefire-testng` in the plugin. The frameworks with assertions API are used, i.e. `org.hamcrest:hamcrest:2.2` (automatic module) and `org.assertj:assertj-core:3.16.1` (named module).
+
+```xml
 <properties>
     <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
     <maven.compiler.release>${java.specification.version}</maven.compiler.release>
@@ -65,20 +59,20 @@ Using Java Modularity (JPMS) in Tests
         <scope>test</scope>
     </dependency>
 </dependencies>
-+---+
+```
 
-  The most important parts are the module descriptors. This is the module descriptor located in <<<src/main/java>>>:
+The most important parts are the module descriptors. This is the module descriptor located in `src/main/java`:
 
-+---+
+```java
 module main
 {
     exports main;
 }
-+---+
+```
 
-  This is the module descriptor in <<<src/test/java>>>:
+This is the module descriptor in `src/test/java`:
 
-+---+
+```java
 module test
 {
     requires main;
@@ -87,18 +81,16 @@ module test
     requires org.assertj.core;
     exports test to org.testng;
 }
-+---+
+```
 
-* Examples using JUnit4
+Examples using JUnit4
+---------------------
 
-  The Surefire project provides the integration tests with
-  {{{https://github.com/apache/maven-surefire/tree/master/surefire-its/src/test/resources/surefire-1733-junit4}JUnit4}}
-  demonstrating the Java Modularity (JPMS).
+The Surefire project provides the integration tests with [JUnit4](https://github.com/apache/maven-surefire/tree/master/surefire-its/src/test/resources/surefire-1733-junit4) demonstrating the Java Modularity (JPMS).
 
-  The JDK version must be 9 or higher. The POM contains the dependency <<<junit:junit:4.13>>> which is
-  an automatic module. It activates the internal provider <<<surefire-junit4>>> or <<<surefire-junit47>>> in the plugin.
+The JDK version must be 9 or higher. The POM contains the dependency `junit:junit:4.13` which is an automatic module. It activates the internal provider `surefire-junit4` or `surefire-junit47` in the plugin.
 
-+---+
+```xml
 <properties>
     <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
     <maven.compiler.release>${java.specification.version}</maven.compiler.release>
@@ -124,20 +116,20 @@ module test
         <scope>test</scope>
     </dependency>
 </dependencies>
-+---+
+```
 
-  The most important parts are the module descriptors. This is the module descriptor located in <<<src/main/java>>>:
+The most important parts are the module descriptors. This is the module descriptor located in `src/main/java`:
 
-+---+
+```java
 module main
 {
     exports main;
 }
-+---+
+```
 
-  This is the module descriptor in <<<src/test/java>>>:
+This is the module descriptor in `src/test/java`:
 
-+---+
+```java
 module test
 {
     requires main;
@@ -145,19 +137,16 @@ module test
     requires org.hamcrest;
     exports test to junit;
 }
-+---+
+```
 
-* Examples using JUnit5
+Examples using JUnit5
+---------------------
 
-  The Surefire project provides the integration tests with
-  {{{https://github.com/apache/maven-surefire/tree/master/surefire-its/src/test/resources/maven-multimodule-project-with-jpms}JUnit5}}
-  demonstrating the Java Modularity (JPMS) in Maven multi-module project.
+The Surefire project provides the integration tests with [JUnit5](https://github.com/apache/maven-surefire/tree/master/surefire-its/src/test/resources/maven-multimodule-project-with-jpms) demonstrating the Java Modularity (JPMS) in Maven multi-module project.
 
-  The JDK version must be 9 or higher. The POM contains the dependency
-  <<<org.junit.jupiter:junit-jupiter-engine:5.9.1>>> which is named module. It activates the internal provider
-  <<<surefire-junit-platform>>> in the plugin.
+The JDK version must be 9 or higher. The POM contains the dependency `org.junit.jupiter:junit-jupiter-engine:5.9.1` which is named module. It activates the internal provider `surefire-junit-platform` in the plugin.
 
-+---+
+```xml
 <artifactId>com.foo.impl</artifactId>
 
 <dependencies>
@@ -176,11 +165,11 @@ module test
         <scope>test</scope>
     </dependency>
 </dependencies>
-+---+
+```
 
-  The most important parts are the module descriptors. This is the module descriptor located in <<<src/main/java>>>:
+The most important parts are the module descriptors. This is the module descriptor located in `src/main/java`:
 
-+---+
+```java
 module com.foo.impl
 {
     exports com.foo.impl;
@@ -188,11 +177,11 @@ module com.foo.impl
     requires org.slf4j;
     requires org.slf4j.simple;
 }
-+---+
+```
 
-  This is the module descriptor in <<<src/test/java>>>:
+This is the module descriptor in `src/test/java`:
 
-+---+
+```text
 open module com.foo.test
 {
     exports com.foo.implt;
@@ -202,4 +191,4 @@ open module com.foo.test
     requires transitive org.junit.jupiter.engine;
     requires transitive org.junit.jupiter.api;
 }
-+---+
+```
diff --git a/maven-surefire-plugin/src/site/markdown/examples/junit-platform.md.vm b/maven-surefire-plugin/src/site/markdown/examples/junit-platform.md.vm
index deb8582f5..45663fdd0 100644
--- a/maven-surefire-plugin/src/site/markdown/examples/junit-platform.md.vm
+++ b/maven-surefire-plugin/src/site/markdown/examples/junit-platform.md.vm
@@ -1,40 +1,37 @@
- ------
- Using JUnit 5 Platform
- ------
- JUnit Lambda Team <ju...@googlegroups.com>
- ------
- 2018-05-14
- ------
-
- ~~ 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
-
-Using JUnit 5 Platform
-
-* Configuring JUnit Platform
-
-  To get started with JUnit Platform, you need to add at least a single <<<TestEngine>>> implementation
-  to your project. For example, if you want to write tests with Jupiter, add the test artifact
-  <<<junit-jupiter-engine>>> to the dependencies in POM:
-
-+---+
+---
+title: Using JUnit 5 Platform
+author:
+  - JUnit Lambda Team junit-lambda-team@googlegroups.com
+date: 2018-05-14
+---
+
+<!--
+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.
+-->
+
+# Using JUnit 5 Platform
+
+Configuring JUnit Platform
+--------------------------
+
+To get started with JUnit Platform, you need to add at least a single `TestEngine` implementation to your project. For example, if you want to write tests with Jupiter, add the test artifact `junit-jupiter-engine` to the dependencies in POM:
+
+```xml
 <dependencies>
     [...]
     <dependency>
@@ -45,19 +42,15 @@ Using JUnit 5 Platform
     </dependency>
     [...]
 </dependencies>
-+---+
+```
 
-  This will pull in all required dependencies. Among those dependencies is <<<junit-jupiter-api>>> which contains
-  the classes and interfaces your test source requires to compile. <<<junit-platform-engine>>> is also resolved and
-  added.
+This will pull in all required dependencies. Among those dependencies is `junit-jupiter-api` which contains the classes and interfaces your test source requires to compile. `junit-platform-engine` is also resolved and added.
 
-  This is the only step that is required to get started - you can now create tests in your test source directory
-  (e.g., <<<src/test/java>>>).
+This is the only step that is required to get started - you can now create tests in your test source directory (e.g., `src/test/java`).
 
-  If you want to write and execute JUnit 3 or 4 tests via the JUnit Platform add the Vintage Engine to the
-  dependencies, which transitively pulls in (and requires) <<<junit:junit:4.13.2>>>:
+If you want to write and execute JUnit 3 or 4 tests via the JUnit Platform add the Vintage Engine to the dependencies, which transitively pulls in (and requires) `junit:junit:4.13.2`:
 
-+---+
+```xml
 <dependencies>
     [...]
     <dependency>
@@ -68,33 +61,24 @@ Using JUnit 5 Platform
     </dependency>
     [...]
 </dependencies>
-+---+
+```
 
-  For more information on using JUnit 5, that is the JUnit Platform, JUnit Jupiter, and JUnit Vintage,
-  see the {{{https://junit.org/junit5/}JUnit 5 web site}}
-  and the {{{https://junit.org/junit5/docs/current/user-guide/}JUnit 5 User Guide}}.
+For more information on using JUnit 5, that is the JUnit Platform, JUnit Jupiter, and JUnit Vintage, see the [JUnit 5 web site](https://junit.org/junit5/) and the [JUnit 5 User Guide](https://junit.org/junit5/docs/current/user-guide/).
 
-* Smart Resolution of Jupiter Engine and Vintage Engine for JUnit4
+Smart Resolution of Jupiter Engine and Vintage Engine for JUnit4
+----------------------------------------------------------------
 
-  JUnit5 API artifact and your test sources become isolated from engine. In these chapters you will see how you can
-  segregate, combine, select the APIs and Engines miscellaneous way. You can find integration tests
-  {{{https://github.com/apache/maven-surefire/tree/master/surefire-its/src/test/resources/junit-4-5}with JUnit4/5}},
-  {{{https://github.com/apache/maven-surefire/tree/master/surefire-its/src/test/resources/junit5-testng}with JUnit5/TestNG}}
-  and {{{https://github.com/apache/maven-surefire/tree/master/surefire-its/src/test/resources/junit5-runner}with the JUnit4 Runner for Jupiter tests}}.
-  (See the Maven profiles.)
+JUnit5 API artifact and your test sources become isolated from engine. In these chapters you will see how you can segregate, combine, select the APIs and Engines miscellaneous way. You can find integration tests [with JUnit4/5](https://github.com/apache/maven-surefire/tree/master/surefire-its/src/test/resources/junit-4-5), [with JUnit5/TestNG](https://github.com/apache/maven-surefire/tree/master/surefire-its/src/test/resources/junit5-testng) and [with the JUnit4 Runner for Jupiter tests] [...]
 
-** How to run only one API
+#[[### How to run only one API]]#
 
-  Normally, the developer does not want to access internal classes of JUnit5 engine (e.g. <<<5.9.1>>>).
-  In the next chapters you can find your way to use the Jupiter or JUnit5 API where the plugin would resolve the engine.
+Normally, the developer does not want to access internal classes of JUnit5 engine (e.g. `5.9.1`). In the next chapters you can find your way to use the Jupiter or JUnit5 API where the plugin would resolve the engine.
 
-*** Jupiter API in test dependencies
+#[[#### Jupiter API in test dependencies]]#
 
-  In this example the POM has only Jupiter API dependency in test classpath. The plugin will resolve and download
-  the <<<junit-jupiter-engine>>> with the version related to the version of <<<junit-jupiter-api>>>. Similar principles
-  can be found in the following chapters as well.
+In this example the POM has only Jupiter API dependency in test classpath. The plugin will resolve and download the `junit-jupiter-engine` with the version related to the version of `junit-jupiter-api`. Similar principles can be found in the following chapters as well.
 
-+---+
+```xml
 <dependencies>
     [...]
     <dependency>
@@ -119,15 +103,13 @@ Using JUnit 5 Platform
     </plugins>
 </build>
 ...
-+---+
+```
 
-*** API-Engine versions segregation
+#[[#### API-Engine versions segregation]]#
 
-  In the following example the engine artifact appears in plugin dependencies and the engine is resolved by the plugin
-  and downloaded from a remote repository for plugins. You may want to update the version of engine with fixed bugs in
-  <<<5.9.1>>> but the API version <<<5.9.0>>> stays intact!
+In the following example the engine artifact appears in plugin dependencies and the engine is resolved by the plugin and downloaded from a remote repository for plugins. You may want to update the version of engine with fixed bugs in `5.9.1` but the API version `5.9.0` stays intact\!
 
-+---+
+```xml
 <dependencies>
     [...]
     <dependency>
@@ -158,15 +140,13 @@ Using JUnit 5 Platform
     </plugins>
 </build>
 ...
-+---+
+```
 
-*** JUnit4 API in test dependencies
+#[[#### JUnit4 API in test dependencies]]#
 
-  This is similar example with JUnit4 in test dependencies of your project POM.
-  The Vintage engine artifact has to be in the plugin dependencies; otherwise the plugin would use
-  <<<surefire-junit4>>> provider instead of the <<<surefire-junit-platform>>> provider.
+This is similar example with JUnit4 in test dependencies of your project POM. The Vintage engine artifact has to be in the plugin dependencies; otherwise the plugin would use `surefire-junit4` provider instead of the `surefire-junit-platform` provider.
 
-+---+
+```xml
 <dependencies>
     [...]
     <dependency>
@@ -196,18 +176,17 @@ Using JUnit 5 Platform
     </plugins>
 </build>
 ...
-+---+
+```
 
-** How to run multiple APIs or Engines
+#[[### How to run multiple APIs or Engines]]#
 
-  In the following example you can use both JUnit4 and JUnit5 tests.
+In the following example you can use both JUnit4 and JUnit5 tests.
 
-*** Jupiter API and JUnit4
+#[[#### Jupiter API and JUnit4]]#
 
-  Once you define any JUnit5 API in the dependencies, the provider <<<surefire-junit-platform>>> is selected and
-  you can always add the JUnit4 dependency.
+Once you define any JUnit5 API in the dependencies, the provider `surefire-junit-platform` is selected and you can always add the JUnit4 dependency.
 
-+---+
+```xml
 <dependencies>
     <dependency>
         <groupId>org.junit.jupiter</groupId>
@@ -222,11 +201,11 @@ Using JUnit 5 Platform
         <scope>test</scope>
     </dependency>
 </dependencies>
-+---+
+```
 
-*** Jupiter API and Vintage Engine
+#[[#### Jupiter API and Vintage Engine]]#
 
-+---+
+```xml
 <dependencies>
     <dependency>
         <groupId>org.junit.jupiter</groupId>
@@ -241,11 +220,11 @@ Using JUnit 5 Platform
         <scope>test</scope>
     </dependency>
 </dependencies>
-+---+
+```
 
-*** Jupiter and Vintage Engine
+#[[#### Jupiter and Vintage Engine]]#
 
-+---+
+```xml
 <dependencies>
     <dependency>
         <groupId>org.junit.jupiter</groupId>
@@ -260,19 +239,17 @@ Using JUnit 5 Platform
         <scope>test</scope>
     </dependency>
 </dependencies>
-+---+
+```
 
-** Select engine and use multiple APIs
+#[[### Select engine and use multiple APIs]]#
 
-  In these examples you use both API, i.e. Jupiter and JUnit4, in the test dependencies but you want to select
-  the engine via plugin dependencies.
+In these examples you use both API, i.e. Jupiter and JUnit4, in the test dependencies but you want to select the engine via plugin dependencies.
 
-*** Select Jupiter
+#[[#### Select Jupiter]]#
 
-    Here your tests import the packages from JUnit4 and Jupiter but you want to select only one Maven profile
-    with JUnit4 tests.
+Here your tests import the packages from JUnit4 and Jupiter but you want to select only one Maven profile with JUnit4 tests.
 
-+---+
+```xml
 <dependencies>
     <dependency>
         <groupId>org.junit.jupiter</groupId>
@@ -306,14 +283,13 @@ Using JUnit 5 Platform
         </plugins>
     </build>
 </profile>
-+---+
+```
 
-*** Select JUnit4
+#[[#### Select JUnit4]]#
 
-  Here your tests import the packages from JUnit4 and Jupiter but you want to select only one Maven profile
-  with Jupiter tests.
+Here your tests import the packages from JUnit4 and Jupiter but you want to select only one Maven profile with Jupiter tests.
 
-+---+
+```xml
 <dependencies>
     <dependency>
         <groupId>org.junit.jupiter</groupId>
@@ -347,17 +323,15 @@ Using JUnit 5 Platform
         </plugins>
     </build>
 </profile>
-+---+
+```
 
-** How to run TestNG tests within the JUnit Platform
+#[[### How to run TestNG tests within the JUnit Platform]]#
 
-  You can run TestNG tests combined with JUnit5 tests.
+You can run TestNG tests combined with JUnit5 tests.
 
-  For more information see this
-  {{{https://github.com/apache/maven-surefire/tree/master/surefire-its/src/test/resources/junit5-testng}example}}
-  and {{{https://github.com/junit-team/testng-engine}TestNG Engine for the JUnit Platform}}.
+For more information see this [example](https://github.com/apache/maven-surefire/tree/master/surefire-its/src/test/resources/junit5-testng) and [TestNG Engine for the JUnit Platform](https://github.com/junit-team/testng-engine).
 
-+---+
+```xml
 <dependencies>
     <dependency>
         <groupId>org.testng</groupId>
@@ -372,20 +346,17 @@ Using JUnit 5 Platform
         <scope>test</scope>
     </dependency>
 </dependencies>
-+---+
+```
 
-  The Maven does not take any responsibility for broken compatibilities in this case and the responsibility for
-  the dependency <<<org.junit.support:testng-engine>>>.
+The Maven does not take any responsibility for broken compatibilities in this case and the responsibility for the dependency `org.junit.support:testng-engine`.
 
-** JUnit Runner
+#[[### JUnit Runner]]#
 
-  The JUnit4 library has the {{{https://junit.org/junit4/javadoc/latest/src-html/org/junit/runner/Runner.html}Runner}}
-  implemented in the JUnit5's artifact <<<junit-platform-runner>>>.
+The JUnit4 library has the [Runner](https://junit.org/junit4/javadoc/latest/src-html/org/junit/runner/Runner.html) implemented in the JUnit5's artifact `junit-platform-runner`.
 
-  For more information see this
-  {{{https://github.com/apache/maven-surefire/tree/master/surefire-its/src/test/resources/junit5-runner}example}}.
+For more information see this [example](https://github.com/apache/maven-surefire/tree/master/surefire-its/src/test/resources/junit5-runner).
 
-+---+
+```xml
 <dependencies>
     <dependency>
         <groupId>org.junit.jupiter</groupId>
@@ -400,15 +371,13 @@ Using JUnit 5 Platform
         <scope>test</scope>
     </dependency>
 </dependencies>
-+---+
+```
 
-** JUnit5 Suite
+#[[### JUnit5 Suite]]#
 
-  For more information see this
-  {{{https://github.com/apache/maven-surefire/tree/master/surefire-its/src/test/resources/junit5-suite}example with surefire integration test}}
-  and the {{{https://junit.org/junit5/docs/current/user-guide/#junit-platform-suite-engine}tutorial}}.
+For more information see this [example with surefire integration test](https://github.com/apache/maven-surefire/tree/master/surefire-its/src/test/resources/junit5-suite) and the [tutorial](https://junit.org/junit5/docs/current/user-guide/#junit-platform-suite-engine).
 
-+---+
+```xml
 <dependencies>
     <dependency>
         <groupId>org.junit.jupiter</groupId>
@@ -435,13 +404,14 @@ Using JUnit 5 Platform
         </plugin>
     </plugins>
 </build>
-+---+
+```
 
-* Provider Selection
+Provider Selection
+------------------
 
-   If nothing is configured, Surefire detects which JUnit version to use by the following algorithm:
+If nothing is configured, Surefire detects which JUnit version to use by the following algorithm:
 
-+---+
+```text
 if the JUnit 5 Platform Engine is present in the project
     use junit-platform
 if the JUnit version in the project >= 4.7 and the <<<parallel>>> configuration parameter has ANY value
@@ -450,52 +420,44 @@ if JUnit >= 4.0 is present
     use junit4 provider
 else
     use junit3.8.1
-+---+
+```
 
-  When using this technique there is no check that the proper test-frameworks are present on your project's
-  classpath. Failing to add the proper test-frameworks will result in a build failure.
+When using this technique there is no check that the proper test-frameworks are present on your project's classpath. Failing to add the proper test-frameworks will result in a build failure.
 
-* Running Tests in Parallel
+Running Tests in Parallel
+-------------------------
 
-  From JUnit Platform does not support running tests in parallel.
+From JUnit Platform does not support running tests in parallel.
 
-* Running a Single Test Class
+Running a Single Test Class
+---------------------------
 
-   The JUnit Platform Provider supports the <<<test>>> JVM system property supported by
-   the Maven Surefire Plugin. For example, to run only test methods in the <<<org.example.MyTest>>> test class
-   you can execute <<<mvn -Dtest=org.example.MyTest test>>> from the command line.
+The JUnit Platform Provider supports the `test` JVM system property supported by the Maven Surefire Plugin. For example, to run only test methods in the `org.example.MyTest` test class you can execute `mvn -Dtest=org.example.MyTest test` from the command line.
 
+Filtering by Test Class Names for Maven ${thisPlugin}
+-----------------------------------------------------
 
-* Filtering by Test Class Names for Maven ${thisPlugin}
-
-   The Maven ${thisPlugin} Plugin will scan for test classes whose fully qualified names match
-   the following patterns.
+The Maven ${thisPlugin} Plugin will scan for test classes whose fully qualified names match the following patterns.
 
 #{if}(${project.artifactId}=="maven-surefire-plugin")
-   * <<<**/Test*.java>>>
-
-   * <<<**/*Test.java>>>
-
-   * <<<**/*Tests.java>>>
-
-   * <<<**/*TestCase.java>>>
+- `**/Test*.java`
+- `**/*Test.java`
+- `**/*Tests.java`
+- `**/*TestCase.java`
 #{else}
-   * <<<**/IT*.java>>>
-
-   * <<<**/*IT.java>>>
-
-   * <<<**/*ITCase.java>>>
+- `**/IT*.java`
+- `**/*IT.java`
+- `**/*ITCase.java`
 #{end}
 
-   Moreover, it will exclude all nested classes (including static member classes) by default.
+    Moreover, it will exclude all nested classes (including static member classes) by default.
 
-   Note, however, that you can override this default behavior by configuring explicit
-   `include` and `exclude` rules in your `pom.xml` file. For example, to keep Maven ${thisPlugin}
-   from excluding static member classes, you can override its exclude rules.
+    Note, however, that you can override this default behavior by configuring explicit \`include\` and \`exclude\` rules in your \`pom.xml\` file. For example, to keep Maven ${thisPlugin} from excluding static member classes, you can override its exclude rules.
 
-* Overriding exclude rules of Maven ${thisPlugin}
+Overriding exclude rules of Maven ${thisPlugin}
+-----------------------------------------------
 
-+---+
+```text
 ...
 <build>
     <plugins>
@@ -513,49 +475,46 @@ else
     </plugins>
 </build>
 ...
-+---+
-
+```
 
-* Filtering by Tags
+Filtering by Tags
+-----------------
 
-   You can use JUnit5 Tags and filter tests by tags or tag expressions.
+You can use JUnit5 Tags and filter tests by tags or tag expressions.
 
-    * To include <<<tags>>> or <<<tag expressions>>>, use <<<groups>>>.
+- To include `tags` or `tag expressions`, use `groups`.
+- To exclude `tags` or `tag expressions`, use `excludedGroups`.
 
-    * To exclude <<<tags>>> or <<<tag expressions>>>, use <<<excludedGroups>>>.
-
-+---+
-...
-<build>
-    <plugins>
-        ...
-        <plugin>
-            <groupId>${project.groupId}</groupId>
-            <artifactId>${project.artifactId}</artifactId>
-            <version>${project.version}</version>
-            <configuration>
-                <groups>acceptance | !feature-a</groups>
-                <excludedGroups>integration, regression</excludedGroups>
-            </configuration>
-        </plugin>
-    </plugins>
-</build>
-...
-+---+
-
-
-* Filtering JUnit5 Engines
+    ```unknown
+    ...
+    <build>
+        <plugins>
+            ...
+            <plugin>
+                <groupId>${project.groupId}</groupId>
+                <artifactId>${project.artifactId}</artifactId>
+                <version>${project.version}</version>
+                <configuration>
+                    <groups>acceptance | !feature-a</groups>
+                    <excludedGroups>integration, regression</excludedGroups>
+                </configuration>
+            </plugin>
+        </plugins>
+    </build>
+    ...
+    ```
 
-   You can filter engines by the ID/s of an engine to be included or excluded in the test run.
+Filtering JUnit5 Engines
+------------------------
 
-    * To include <<<engines>>>, use <<<includeJUnit5Engines>>>.
+You can filter engines by the ID/s of an engine to be included or excluded in the test run.
 
-    * To exclude <<<engines>>>, use <<<excludeJUnit5Engines>>>.
+- To include `engines`, use `includeJUnit5Engines`.
+- To exclude `engines`, use `excludeJUnit5Engines`.
 
-   Be aware that this feature reserves system properties <<<includejunit5engines>>> and <<<excludejunit5engines>>>
-   for internal usage.
+Be aware that this feature reserves system properties `includejunit5engines` and `excludejunit5engines` for internal usage.
 
-+---+
+```text
 ...
 <build>
     <plugins>
@@ -578,16 +537,14 @@ else
     </plugins>
 </build>
 ...
-+---+
+```
 
+Configuration Parameters
+------------------------
 
-* Configuration Parameters
+You can set JUnit Platform configuration parameters to influence test discovery and execution by declaring the `configurationParameters` property and providing key-value pairs using the Java `Properties` file syntax (as shown below) or via the `junit-platform.properties` file.
 
-   You can set JUnit Platform configuration parameters to influence test discovery and execution by
-   declaring the <<<configurationParameters>>> property and providing key-value pairs using the Java
-   <<<Properties>>> file syntax (as shown below) or via the <<<junit-platform.properties>>> file.
-
-+---+
+```text
 ...
 <build>
     <plugins>
@@ -610,17 +567,14 @@ else
     </plugins>
 </build>
 ...
-+---+
-
+```
 
-* Surefire Extensions and Reports Configuration for @DisplayName
+Surefire Extensions and Reports Configuration for @DisplayName
+--------------------------------------------------------------
 
-   Since plugin version 3.0.0-M4 you can use fine grained configuration of reports and enable phrased names together
-   with <<<...@DisplayName>>> in you tests.
-   This is the complete list of attributes of particular objects. You do not have to specify e.g. <<<disable>>>,
-   <<<version>>> and <<<encoding>>>. The boolean values reach default values <<<false>>> if not specified otherwise.
+Since plugin version 3.0.0-M4 you can use fine grained configuration of reports and enable phrased names together with `@DisplayName` in you tests. This is the complete list of attributes of particular objects. You do not have to specify e.g. `disable`, `version` and `encoding`. The boolean values reach default values `false` if not specified otherwise.
 
-+---+
+```text
 ...
 <build>
     <plugins>
@@ -654,27 +608,22 @@ else
     </plugins>
 </build>
 ...
-+---+
+```
 
-   Default implementations of these extensions are
-   <<<org.apache.maven.plugin.surefire.extensions.SurefireStatelessReporter>>>,
-   <<<org.apache.maven.plugin.surefire.extensions.SurefireConsoleOutputReporter>>>, and
-   <<<org.apache.maven.plugin.surefire.extensions.SurefireStatelessTestsetInfoReporter>>>.
+Default implementations of these extensions are `org.apache.maven.plugin.surefire.extensions.SurefireStatelessReporter`, `org.apache.maven.plugin.surefire.extensions.SurefireConsoleOutputReporter`, and `org.apache.maven.plugin.surefire.extensions.SurefireStatelessTestsetInfoReporter`.
 
-   The aim of extensions is to let the users customizing the default behavior. We are keen on listing useful
-   extensions on Apache Maven Surefire site if you propagate your extensions on GitHub.
+The aim of extensions is to let the users customizing the default behavior. We are keen on listing useful extensions on Apache Maven Surefire site if you propagate your extensions on GitHub.
 
+External extensions for the plugin
+----------------------------------
 
-* External extensions for the plugin
+This extension prints a tree view for the unit tests on the console. This is related to JUnit5 tests.
 
-   This extension prints a tree view for the unit tests on the console.
-   This is related to JUnit5 tests.
+<figure><img src="extension1.png" /><figcaption>The console with this extension.</figcaption></figure>
 
-[extension1.png] The console with this extension.
+Follow the example with the configuration and the dependency in the plugin.
 
-   Follow the example with the configuration and the dependency in the plugin.
-
-+---+
+```text
 ...
 <plugin>
     <groupId>${project.groupId}</groupId>
@@ -696,5 +645,4 @@ else
     </configuration>
 </plugin>
 ...
-+---+
-
+```
diff --git a/maven-surefire-plugin/src/site/markdown/examples/junit.md.vm b/maven-surefire-plugin/src/site/markdown/examples/junit.md.vm
index e6788074f..bcf505f5b 100644
--- a/maven-surefire-plugin/src/site/markdown/examples/junit.md.vm
+++ b/maven-surefire-plugin/src/site/markdown/examples/junit.md.vm
@@ -1,38 +1,37 @@
- ------
- Using JUnit
- ------
- Kristian Rosenvold <kr...@apache.org>
- ------
- 2010-10-10
- ------
- 
- ~~ 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 
-
-Using JUnit
-
-* Configuring JUnit
-
-  To get started with JUnit, you need to add the required version of JUnit to your project:
-
-+---+
+---
+title: Using JUnit
+author:
+  - Kristian Rosenvold krosenvold@apache.org
+date: 2010-10-10
+---
+
+<!--
+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.
+-->
+
+# Using JUnit
+
+Configuring JUnit
+-----------------
+
+To get started with JUnit, you need to add the required version of JUnit to your project:
+
+```xml
 <dependencies>
   [...]
     <dependency>
@@ -43,34 +42,28 @@ Using JUnit
     </dependency>
   [...]
 </dependencies>
-+---+
+```
 
+This is the only step that is required to get started - you can now create tests in your test source directory (e.g., `src/test/java`).
 
-  This is the only step that is required to get started - you can now create tests in your test source directory
-  (e.g., <<<src/test/java>>>).
+Different Generations of JUnit support
+--------------------------------------
 
-* Different Generations of JUnit support
+Surefire supports three different generations of JUnit: JUnit 3.8.x, JUnit 4.x (serial provider) and JUnit 4.7 (junit-core provider with parallel support). The provider is selected based on the JUnit version in your project and the configuration parameters (for parallel).
 
-  Surefire supports three different generations of JUnit: JUnit 3.8.x, JUnit 4.x (serial provider) and JUnit 4.7 (junit-core provider
-  with parallel support). The provider is selected based on the JUnit version in your project and the configuration parameters (for parallel).
+Upgrade Check for JUnit 4.x
+---------------------------
 
-* Upgrade Check for JUnit 4.x
+As of Surefire version 2.7, the algorithm for choosing which tests to run has changed. From 2.7 and on, only valid JUnit tests are run for all versions of JUnit, where older versions of the plugin would also run invalid tests that satisfied the naming convention.
 
-  As of Surefire version 2.7, the algorithm for choosing which tests to run
-  has changed. From 2.7 and on, only valid JUnit tests are run for all versions of JUnit, where older versions
-  of the plugin would also run invalid tests that satisfied the naming convention.
+When upgrading from a Surefire version prior to 2.7, the build can be run with the flag `-Dsurefire.junit4.upgradecheck`. This will perform a check and notify you of any invalid tests that will not be run with this version of Surefire (and the build fails). This is only meant to be used as a tool when upgrading to check that all expected tests will be run. It is a transitional feature that will be removed in a future version of surefire.
 
-  When upgrading from a Surefire version prior to 2.7, the build can be run with
-  the flag <<<-Dsurefire.junit4.upgradecheck>>>. This will perform a check and notify you of any invalid tests that
-  will not be run with this version of Surefire (and the build fails). This is only meant to be used as a tool
-  when upgrading to check that all expected tests will be run. It is a transitional
-  feature that will be removed in a future version of surefire.
+Provider Selection
+------------------
 
-* Provider Selection
+If nothing is configured, Surefire detects which JUnit version to use by the following algorithm:
 
-   If nothing is configured, Surefire detects which JUnit version to use by the following algorithm:
-
-+---+
+```text
 if the JUnit 5 Platform Engine is present in the project
     use junit-platform
 if the JUnit version in the project >= 4.7 and the <<<parallel>>> configuration parameter has ANY value
@@ -79,21 +72,19 @@ if JUnit >= 4.0 is present
     use junit4 provider
 else
     use junit3.8.1
-+---+
+```
 
-    Please note that the "else" part of this algorithm is also a FAQ response:
+Please note that the "else" part of this algorithm is also a FAQ response:
 
-    You depend on the appropriate version of JUnit being present in the project dependencies, or Surefire may choose the wrong
-    provider. If, for instance, one of your dependencies pulls in JUnit 3.8.1 you risk that surefire chooses the
-    3.8.1 provider, which will not support annotations or any of the 4.x features.
+You depend on the appropriate version of JUnit being present in the project dependencies, or Surefire may choose the wrong provider. If, for instance, one of your dependencies pulls in JUnit 3.8.1 you risk that surefire chooses the 3.8.1 provider, which will not support annotations or any of the 4.x features.
 
-    Use <<<mvn dependency:tree>>>, POM dependency ordering and/or exclusion of transitive dependencies to fix this problem.
+Use `mvn dependency:tree`, POM dependency ordering and/or exclusion of transitive dependencies to fix this problem.
 
-** Manually Specifying a Provider
+#[[### Manually Specifying a Provider]]#
 
-   You can also manually force a specific provider by adding it as a dependency to ${thisPlugin} itself:
+You can also manually force a specific provider by adding it as a dependency to ${thisPlugin} itself:
 
-+---+
+```xml
 <plugins>
 [...]
   <plugin>
@@ -110,18 +101,16 @@ else
   </plugin>
 [...]
 </plugins>
-+---+
+```
 
-  When using this technique there  is no check that the proper test-frameworks are present on your project's
-  classpath. Failing to add the proper test-frameworks will result in a build failure.
+When using this technique there is no check that the proper test-frameworks are present on your project's classpath. Failing to add the proper test-frameworks will result in a build failure.
 
-* Running Tests in Parallel
+Running Tests in Parallel
+-------------------------
 
-  From JUnit 4.7 onwards you can run your tests in parallel. To do this, you must set the
-  <<<parallel>>> parameter, and may change the <<<threadCount>>> or <<<useUnlimitedThreads>>> attribute.
-  For example:
+From JUnit 4.7 onwards you can run your tests in parallel. To do this, you must set the `parallel` parameter, and may change the `threadCount` or `useUnlimitedThreads` attribute. For example:
 
-+---+
+```xml
 <plugins>
     [...]
       <plugin>
@@ -135,29 +124,24 @@ else
       </plugin>
     [...]
 </plugins>
-+---+
+```
 
+If your tests specify any value for the `parallel` attribute and your project uses JUnit 4.7+, your request will be routed to the concurrent JUnit provider, which uses the JUnit JUnitCore test runner.
 
-  If your tests specify any value for the <<<parallel>>> attribute and your project uses JUnit 4.7+, your request will be routed to
-  the concurrent JUnit provider, which uses the JUnit JUnitCore test runner.
+This is particularly useful for slow tests that can have high concurrency.
 
-  This is particularly useful for slow tests that can have high concurrency.
+As of Surefire 2.7, no additional dependencies are needed to use the full set of options with parallel. As of Surefire 2.16, new thread-count attributes are introduced, namely `threadCountSuites`, `threadCountClasses` and `threadCountMethods`. Additionally, the new attributes `parallelTestsTimeoutInSeconds` and `parallelTestsTimeoutForcedInSeconds` are used to shut down the parallel execution after an elapsed timeout, and the attribute `parallel` specifies new values.
 
-  As of Surefire 2.7, no additional dependencies are needed to use the full set of options with parallel.
-  As of Surefire 2.16, new thread-count attributes are introduced, namely <<<threadCountSuites>>>, <<<threadCountClasses>>> and
-  <<<threadCountMethods>>>. Additionally, the new attributes <<<parallelTestsTimeoutInSeconds>>> and
-  <<<parallelTestsTimeoutForcedInSeconds>>> are used to shut down the parallel execution after an elapsed timeout, and
-  the attribute <<<parallel>>> specifies new values.
-  
-  See also {{{./fork-options-and-parallel-execution.html}Fork Options and Parallel Test Execution}}.
+See also [Fork Options and Parallel Test Execution](./fork-options-and-parallel-execution.html).
 
-* Using Custom Listeners and Reporters
+Using Custom Listeners and Reporters
+------------------------------------
 
-  The junit4 and junit47 providers provide support for attaching custom <<<RunListeners>>> to your tests.
+The junit4 and junit47 providers provide support for attaching custom `RunListeners` to your tests.
 
-  You can configure multiple custom listeners like this:
+You can configure multiple custom listeners like this:
 
-+---+
+```xml
 <dependencies>
 [...]
   <dependency>
@@ -186,32 +170,24 @@ else
   </plugin>
 [...]
 </plugins>
-+---+
-
-  For more information on JUnit, see the {{{http://www.junit.org}JUnit web site}}.
+```
 
-  You can implement JUnit listener interface <<<org.junit.runner.notification.RunListener>>> in
-  a separate test artifact <<<your-junit-listener-artifact>>> with scope=test, or in project test source code
-  <<<src/test/java>>>. You can filter test artifacts by the parameter <<<dependenciesToScan>>> to load its classes
-  in current ClassLoader of surefire-junit* providers.
+For more information on JUnit, see the [JUnit web site](http://www.junit.org).
 
-  Since JUnit 4.12 thread safe listener class should be annotated by
-  <<<org.junit.runner.notification.RunListener.ThreadSafe>>> which avoids unnecessary locks in JUnit.
+You can implement JUnit listener interface `org.junit.runner.notification.RunListener` in a separate test artifact `your-junit-listener-artifact` with scope=test, or in project test source code `src/test/java`. You can filter test artifacts by the parameter `dependenciesToScan` to load its classes in current ClassLoader of surefire-junit* providers.
 
+Since JUnit 4.12 thread safe listener class should be annotated by `org.junit.runner.notification.RunListener.ThreadSafe` which avoids unnecessary locks in JUnit.
 
-* Using a Security Manager (JUnit3 only)
+Using a Security Manager (JUnit3 only)
+--------------------------------------
 
-   As long as <<<forkCount>>> is not 0 and you use JUnit3, you can run your tests with a Java security manager enabled.
-   The class name of the security manager must be sent as a system property variable to the JUnit3 provider.
+As long as `forkCount` is not 0 and you use JUnit3, you can run your tests with a Java security manager enabled. The class name of the security manager must be sent as a system property variable to the JUnit3 provider.
 
-   The JDK 17 deprecated the class <<<java.lang.SecurityManager>>> and the security manager is not fully supported
-   since JDK 18. The JUnit3 provider fails with enabled system property <<surefire.security.manager>>> in JDK 18+.
+The JDK 17 deprecated the class `java.lang.SecurityManager` and the security manager is not fully supported since JDK 18. The JUnit3 provider fails with enabled system property **surefire.security.manager**> in JDK 18+.
 
-   JUnit4 uses mechanisms internally that are not compatible with the tested
-   security managers and thus this means of configuring a security manager with JUnit4 is not supported
-   by Surefire.
+JUnit4 uses mechanisms internally that are not compatible with the tested security managers and thus this means of configuring a security manager with JUnit4 is not supported by Surefire.
 
-+---+
+```xml
 <plugins>
 [...]
       <plugin>
@@ -226,14 +202,14 @@ else
       </plugin>
 [...]
 </plugins>
-+---+
+```
 
-* Using a Security Manager (All providers)
+Using a Security Manager (All providers)
+----------------------------------------
 
-    Alternatively you can define a policy file that allows all providers to run with Surefire
-    and configure it using the <<<argLine>>> parameter and two system properties:
+Alternatively you can define a policy file that allows all providers to run with Surefire and configure it using the `argLine` parameter and two system properties:
 
-+---+
+```xml
 <plugins>
 [...]
       <plugin>
@@ -241,23 +217,21 @@ else
         <artifactId>${project.artifactId}</artifactId>
         <version>${project.version}</version>
         <configuration>
-          <argLine>-Djava.security.manager -Djava.security.policy=${basedir}/src/test/resources/java.policy</argLine>
+          <argLine>-Djava.security.manager -Djava.security.policy=${esc.d}{basedir}/src/test/resources/java.policy</argLine>
         </configuration>
       </plugin>
 [...]
 </plugins>
-+---+
+```
 
-  The disadvantage of this solution is that the policy changes will affect the tests too, which make the
-  security environment less realistic.
+The disadvantage of this solution is that the policy changes will affect the tests too, which make the security environment less realistic.
 
-* Using JUnit Categories
+Using JUnit Categories
+----------------------
 
-    JUnit 4.8 introduced the notion of Categories. You can use JUnit categories by using the <<<groups>>> parameter. As long as 
-    the JUnit version in the project is 4.8 or higher, the presence of the "groups" parameter will automatically make Surefire select
-    the junit47 provider, which supports groups.
+JUnit 4.8 introduced the notion of Categories. You can use JUnit categories by using the `groups` parameter. As long as the JUnit version in the project is 4.8 or higher, the presence of the "groups" parameter will automatically make Surefire select the junit47 provider, which supports groups.
 
-+---+
+```xml
 <plugins>
 [...]
     <plugin>
@@ -270,17 +244,16 @@ else
     </plugin>
 [...]
 </plugins>
-+---+
+```
 
-  This will execute only those tests annotated with the <<<@Category(com.mycompany.SlowTests.class)>>> annotation and those tests
-  annotated with <<<@Category(com.mycompany.SlowerTests.class)>>> if class/interface <<<SlowerTests>>> is subclass of <<<SlowTests>>>:
+This will execute only those tests annotated with the `@Category(com.mycompany.SlowTests.class)` annotation and those tests annotated with `@Category(com.mycompany.SlowerTests.class)` if class/interface `SlowerTests` is subclass of `SlowTests`:
 
-+---+
+```java
     public interface SlowTests{}
     public interface SlowerTests extends SlowTests{}
-+---+
+```
 
-+---+
+```java
     public class AppTest {
       @Test
       @Category(com.mycompany.SlowTests.class)
@@ -300,15 +273,12 @@ else
         System.out.println("fast");
       }
     }
-+---+
-
-  The <<<...@Category>>> annotation can also be applied at class-level.
-  
-  Multiple categories can be specified by comma-delimiting them in the <<<groups>>> parameter in which case tests annotated with
-  any of the categories will be executed.
-	
-  For more information on JUnit, see the {{{http://www.junit.org}JUnit web site}}.
-
-  Since version 2.18.1 and JUnit 4.12, the <<<...@Category>>> annotation type is automatically inherited from
-  superclasses, see <<<...@java.lang.annotation.Inherited>>>. Make sure that test class inheritance still makes sense
-  together with <<<...@Category>>> annotation of the JUnit 4.12 or higher appeared in superclass.
+```
+
+The `@Category` annotation can also be applied at class-level.
+
+Multiple categories can be specified by comma-delimiting them in the `groups` parameter in which case tests annotated with any of the categories will be executed.
+
+For more information on JUnit, see the [JUnit web site](http://www.junit.org).
+
+Since version 2.18.1 and JUnit 4.12, the `@Category` annotation type is automatically inherited from superclasses, see `@java.lang.annotation.Inherited`. Make sure that test class inheritance still makes sense together with `@Category` annotation of the JUnit 4.12 or higher appeared in superclass.
diff --git a/maven-surefire-plugin/src/site/markdown/examples/logging.md.vm b/maven-surefire-plugin/src/site/markdown/examples/logging.md.vm
index c6280d162..e42dea43b 100644
--- a/maven-surefire-plugin/src/site/markdown/examples/logging.md.vm
+++ b/maven-surefire-plugin/src/site/markdown/examples/logging.md.vm
@@ -1,56 +1,46 @@
-  ------
-  Using Console Logs
-  ------
-  Tibor Digana <ti...@apache.org>
-  ------
-  2015-06-04
-  ------
-
- ~~ 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
-
-Using Console Logs
-
-* Suppressed logs
-
-  Since version 2.19 few lines are suppressed by surefire and failsafe plugin in std/out, namely
-
-  * report directory,
-
-  * Java class of provider,
-
-  * configuration of parallel execution and
-
-  * Java class of TestNG configurator.
-
-  []
-
-  In order to enable detailed logs, use any of CLI Maven option, i.e. -X,--debug,-e,--errors.
-  The result would be e.g.:
-
-
-+---+
+---
+title: Using Console Logs
+author:
+  - Tibor Digana tibordigana@apache.org
+date: 2015-06-04
+---
+
+<!--
+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.
+-->
+
+# Using Console Logs
+
+Suppressed logs
+---------------
+
+Since version 2.19 few lines are suppressed by surefire and failsafe plugin in std/out, namely
+
+- report directory,
+- Java class of provider,
+- configuration of parallel execution and
+- Java class of TestNG configurator.
+
+In order to enable detailed logs, use any of CLI Maven option, i.e. -X,\-\-debug,-e,\-\-errors. The result would be e.g.:
+
+```text
 [INFO] Surefire report directory: /path/to/project/target/surefire-reports
 [INFO] Using configured provider org.apache.maven.surefire.junitcore.JUnitCoreProvider
 [INFO] parallel='none', perCoreThreadCount=true, threadCount=0, useUnlimitedThreads=false, threadCountSuites=0, threadCountClasses=0, threadCountMethods=0, parallelOptimized=true
 Configuring TestNG with: TestNGMapConfigurator
-+---+
-
-
+```
diff --git a/maven-surefire-plugin/src/site/markdown/examples/pojo-test.md b/maven-surefire-plugin/src/site/markdown/examples/pojo-test.md
index 7daf0124f..ec4fce094 100644
--- a/maven-surefire-plugin/src/site/markdown/examples/pojo-test.md
+++ b/maven-surefire-plugin/src/site/markdown/examples/pojo-test.md
@@ -1,49 +1,40 @@
-  ------
-  Using POJO Tests
-  ------
-  Christian Gruber
-  ------
-  May 2008
-  ------
-  
- ~~ 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: Using POJO Tests
+author: 
+  - Christian Gruber
+date: May 2008
+---
 
- ~~ 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-->
+<!---->
+<!--   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  -->
+# Using POJO Tests
 
-Using POJO Tests
+POJO tests look very much like JUnit or TestNG tests, though they do not require dependencies on these artifacts. A test class should be named `**/*Test` and should contain `test*` methods which will each be executed by Surefire.
 
-  POJO tests look very much like JUnit or TestNG tests, though they do not
-  require dependencies on these artifacts.  A test class should be named
-  <<<**/*Test>>> and should contain <<<test*>>> methods which will each be 
-  executed by Surefire.
-  
-  Validating assertions can be done using the JDK 1.4 <<<assert>>> keyword.
-  Simultaneous test execution is not possible with POJO tests.
-  
-  Fixtures can be setup before and after each <<<test*>>> method by implementing
-  a set-up and a tear-down methods.  These methods must match the following signatures
-  to be recognized and executed before and after each test method:
-     
-+---+
+Validating assertions can be done using the JDK 1\.4 `assert` keyword. Simultaneous test execution is not possible with POJO tests.
+
+Fixtures can be setup before and after each `test*` method by implementing a set-up and a tear-down methods. These methods must match the following signatures to be recognized and executed before and after each test method:
+
+```java
 public void setUp();
 public void tearDown();
-+---+
+```
 
-  These fixture methods can also throw any exception and will still be valid.
+These fixture methods can also throw any exception and will still be valid.
 
diff --git a/maven-surefire-plugin/src/site/markdown/examples/process-communication.md.vm b/maven-surefire-plugin/src/site/markdown/examples/process-communication.md.vm
index eaba32c5b..95fba389d 100644
--- a/maven-surefire-plugin/src/site/markdown/examples/process-communication.md.vm
+++ b/maven-surefire-plugin/src/site/markdown/examples/process-communication.md.vm
@@ -1,50 +1,44 @@
-  ------
-  Using JUnit 5 Platform
-  ------
-  Communication Channels in Surefire <us...@maven.apache.org>
-  ------
-  2020-03-15
-  ------
-
-~~ 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
-
-Communication Channels used between the Maven Process and Surefire Process
-
-  There is one way to change the communication channel and two types of connection in the ${thisPlugin}.
-  The communication channel can be changed even by the user in the user's POM.
-  The physical layer of the channel can be switched from Process Pipes to TCP/IP.
-  The user select the default implementations in the POM or the user can implement his own channel without asking
-  the Apache Maven development team for providing a new support. Let's show you how this can be accomplished.
-
-* forkNode
-
-  The configuration is done by using only one configuration parameter <<<forkNode>>>.
-
-* The TCP/IP communication channel
-
-  The ${thisPlugin} plugin uses process pipes by default. The implementation class for default configuration
-  is <<<org.apache.maven.plugin.surefire.extensions.LegacyForkNodeFactory>>> and it does not have to be specified.
-  The TCP/IP channel can be selected as follows and the implementation class has to be specified:
-
-+---+
+---
+title: Using JUnit 5 Platform
+author:
+  - Communication Channels in Surefire users@maven.apache.org
+date: 2020-03-15
+---
+
+<!--
+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.
+-->
+
+# Communication Channels used between the Maven Process and Surefire Process
+
+There is one way to change the communication channel and two types of connection in the ${thisPlugin}. The communication channel can be changed even by the user in the user's POM. The physical layer of the channel can be switched from Process Pipes to TCP/IP. The user select the default implementations in the POM or the user can implement his own channel without asking the Apache Maven development team for providing a new support. Let's show you how this can be accomplished.
+
+forkNode
+--------
+
+The configuration is done by using only one configuration parameter `forkNode`.
+
+The TCP/IP communication channel
+--------------------------------
+
+The ${thisPlugin} plugin uses process pipes by default. The implementation class for default configuration is `org.apache.maven.plugin.surefire.extensions.LegacyForkNodeFactory` and it does not have to be specified. The TCP/IP channel can be selected as follows and the implementation class has to be specified:
+
+```xml
 <project>
     [...]
     <build>
@@ -63,21 +57,16 @@ Communication Channels used between the Maven Process and Surefire Process
     </build>
     [...]
 </project>
-+---+
-
-* Custom implementation
+```
 
-  The custom implementation involves two implementations. The first is used by the Maven process and there you
-  should implement the interface <<<org.apache.maven.surefire.extensions.ForkNodeFactory>>>, use the implementation
-  in a dependency <<<your-extension-api-impl-artifactid>>> declared below the plugin and configuration should
-  specify fully qualified class name of your custom <<<ForkNodeFactory>>> in the attribute <<<implementation>>>.
+Custom implementation
+---------------------
 
-  The second implementation is SPI which is utilized by the forked JVM. Implement the Java SPI interface
-  <<<org.apache.maven.surefire.spi.MasterProcessChannelProcessorFactory>>> in the artifact
-  <<<your-extension-spi-impl-artifactid>>>.
+The custom implementation involves two implementations. The first is used by the Maven process and there you should implement the interface `org.apache.maven.surefire.extensions.ForkNodeFactory`, use the implementation in a dependency `your-extension-api-impl-artifactid` declared below the plugin and configuration should specify fully qualified class name of your custom `ForkNodeFactory` in the attribute `implementation`.
 
+The second implementation is SPI which is utilized by the forked JVM. Implement the Java SPI interface `org.apache.maven.surefire.spi.MasterProcessChannelProcessorFactory` in the artifact `your-extension-spi-impl-artifactid`.
 
-+---+
+```xml
 <project>
     [...]
     <dependencies>
@@ -111,11 +100,11 @@ Communication Channels used between the Maven Process and Surefire Process
     </build>
     [...]
 </project>
-+---+
+```
 
-  The project <<<your-extension-api-impl-artifactid>>> should have the following dependency as mandatory:
+The project `your-extension-api-impl-artifactid` should have the following dependency as mandatory:
 
-+---+
+```xml
 <project>
     [...]
     <dependencies>
@@ -128,11 +117,11 @@ Communication Channels used between the Maven Process and Surefire Process
     </dependencies>
     [...]
 </project>
-+---+
+```
 
-  The project <<<your-extension-spi-impl-artifactid>>> should have the following dependency as mandatory:
+The project `your-extension-spi-impl-artifactid` should have the following dependency as mandatory:
 
-+---+
+```xml
 <project>
     [...]
     <dependencies>
@@ -145,9 +134,6 @@ Communication Channels used between the Maven Process and Surefire Process
     </dependencies>
     [...]
 </project>
-+---+
+```
 
-  Your SPI implementation appears in
-  <<<src/main/resources/META-INF/services/org.apache.maven.surefire.spi.MasterProcessChannelProcessorFactory>>>
-  and contains one implementation class. Your POM already specified it, see
-  <<<your.extention.api.impl.CustomForkNodeFactory>>>.
+Your SPI implementation appears in `src/main/resources/META-INF/services/org.apache.maven.surefire.spi.MasterProcessChannelProcessorFactory` and contains one implementation class. Your POM already specified it, see `your.extention.api.impl.CustomForkNodeFactory`.
diff --git a/maven-surefire-plugin/src/site/markdown/examples/providers.md.vm b/maven-surefire-plugin/src/site/markdown/examples/providers.md.vm
index 5ed478efc..12aa5151f 100644
--- a/maven-surefire-plugin/src/site/markdown/examples/providers.md.vm
+++ b/maven-surefire-plugin/src/site/markdown/examples/providers.md.vm
@@ -1,43 +1,39 @@
- ------
- Selecting Providers
- ------
- Kristian Rosenvold <kr...@apache.org>
- ------
- 2010-12-04
- ------
- 
- ~~ 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 
-
-Selecting Providers
-
-* Selecting a Provider
-
-  Surefire normally automatically selects which test-framework provider to use based on the version of
-  TestNG/JUnit present in your project's classpath. In some cases it may be desirable to manually
-  override such a selection. This can be done by adding the required provider as a dependency to
-  the surefire-plugin.
-
-  The following example shows how to force usage of the JUnit 4.7 provider:
-
-+---+
+---
+title: Selecting Providers
+author:
+  - Kristian Rosenvold krosenvold@apache.org
+date: 2010-12-04
+---
+
+<!--
+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.
+-->
+
+# Selecting Providers
+
+Selecting a Provider
+--------------------
+
+Surefire normally automatically selects which test-framework provider to use based on the version of TestNG/JUnit present in your project's classpath. In some cases it may be desirable to manually override such a selection. This can be done by adding the required provider as a dependency to the surefire-plugin.
+
+The following example shows how to force usage of the JUnit 4.7 provider:
+
+```xml
 <plugins>
   [...]
   <plugin>
@@ -54,12 +50,8 @@ Selecting Providers
   </plugin>
   [...]
 </plugins>
-+---+
-
-  The providers supplied with Surefire are <<<surefire-junit3>>>, <<<surefire-junit4>>>, <<<surefire-junit47>>>,
-  <<<surefire-junit-platform>>> and <<<surefire-testng>>>.
-  Please note that forcing a provider still requires that the test framework is properly set up on your project classpath.
+```
 
-  You can also specify multiple providers as dependencies, and they will all be run and produce a common report.
-  This may be especially handy with external providers, since there are few use cases for combining the included providers.
+The providers supplied with Surefire are `surefire-junit3`, `surefire-junit4`, `surefire-junit47`, `surefire-junit-platform` and `surefire-testng`. Please note that forcing a provider still requires that the test framework is properly set up on your project classpath.
 
+You can also specify multiple providers as dependencies, and they will all be run and produce a common report. This may be especially handy with external providers, since there are few use cases for combining the included providers.
diff --git a/maven-surefire-plugin/src/site/markdown/examples/rerun-failing-tests.md.vm b/maven-surefire-plugin/src/site/markdown/examples/rerun-failing-tests.md.vm
index 8214f8431..91f139813 100644
--- a/maven-surefire-plugin/src/site/markdown/examples/rerun-failing-tests.md.vm
+++ b/maven-surefire-plugin/src/site/markdown/examples/rerun-failing-tests.md.vm
@@ -1,106 +1,93 @@
-  ------
-  Rerun failing tests
-  ------
-  Qingzhou Luo
-  ------
-  2014-06-27
-  ------
-
- ~~ 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
-
-Rerun Failing Tests
-
-  During development, you may re-run failing tests because they are flaky.
-  To use this feature through Maven surefire, set the <<<rerunFailingTestsCount>>> property to be a value larger than 0.
-  Tests will be run until they pass or the number of reruns has been exhausted.
-
-  << NOTE : This feature is supported for JUnit 4.x, and (since 3.0.0-M4) JUnit 5.x. >>
-
-
-+---+
+---
+title: Rerun failing tests
+author:
+  - Qingzhou Luo
+date: 2014-06-27
+---
+
+<!--
+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.
+-->
+
+# Rerun Failing Tests
+
+During development, you may re-run failing tests because they are flaky. To use this feature through Maven surefire, set the `rerunFailingTestsCount` property to be a value larger than 0. Tests will be run until they pass or the number of reruns has been exhausted.
+
+**NOTE : This feature is supported for JUnit 4.x, and (since 3.0.0-M4) JUnit 5.x.**
+
+```bash
 mvn -D${thisPlugin.toLowerCase()}.rerunFailingTestsCount=2 test
-+---+
+```
 
-  If <<<rerunFailingTestsCount>>> is set to a value smaller than or equal to 0, then it will be ignored.
+If `rerunFailingTestsCount` is set to a value smaller than or equal to 0, then it will be ignored.
 
-* Output flaky re-run information on the screen
+Output flaky re-run information on the screen
+---------------------------------------------
 
-  When <<<rerunFailingTestsCount>>> is set to a value larger than 0 and the test fails,
-  then it will be re-run and each run information will also be output. Each run with its number and trimmed stack trace
-  will be output.
+When `rerunFailingTestsCount` is set to a value larger than 0 and the test fails, then it will be re-run and each run information will also be output. Each run with its number and trimmed stack trace will be output.
 
-  If the test passes in its first run, then the output on the screen will be identical to the case where
-  <<<rerunFailingTestsCount>>> is not used.
+If the test passes in its first run, then the output on the screen will be identical to the case where `rerunFailingTestsCount` is not used.
 
-  It the test fails in the first run, then there are two possible cases:
+It the test fails in the first run, then there are two possible cases:
 
-  1) The test passes in one of its re-runs: the last run will be marked as PASS
+1\) The test passes in one of its re-runs: the last run will be marked as PASS
 
-  For example, a test passed in its second run will output on the screen:
+For example, a test passed in its second run will output on the screen:
 
-+---+
+```text
   Run 1: ...
   Run 2: PASS
-+---+
+```
 
-  Then this test will be counted as a flaky test. The build will be successful, but in the end of the summary of all
-  tests run, the number of flaky tests will be output on the screen, for example:
+Then this test will be counted as a flaky test. The build will be successful, but in the end of the summary of all tests run, the number of flaky tests will be output on the screen, for example:
 
-+---+
+```text
   Tests run: 2, Failures: 0, Errors: 0, Skipped: 0, Flakes: 1
-+---+
+```
 
-  2) The test fails in all of the re-runs:
+2\) The test fails in all of the re-runs:
 
-  For example, a test failed in all the three runs, then all the runs will be output on the screen:
+For example, a test failed in all the three runs, then all the runs will be output on the screen:
 
-+---+
+```text
   Run 1: ...
   Run 2: ...
   Run 3: ...
-+---+
+```
 
-  Then this build will be marked as failure. The type of the failure (failed test or test in error) of this test
-  depends on its first failure.
+Then this build will be marked as failure. The type of the failure (failed test or test in error) of this test depends on its first failure.
 
-* Output flaky re-run information in test report xml
+Output flaky re-run information in test report xml
+--------------------------------------------------
 
-  When <<<rerunFailingTestsCount>>> is set to a value larger than 0, the output xml of test report will also be extended
-  to include information of each re-run.
+When `rerunFailingTestsCount` is set to a value larger than 0, the output xml of test report will also be extended to include information of each re-run.
 
-  If the test passes in its first run, then the output xml report will be identical to the case where
-  <<<rerunFailingTestsCount>>> is not used.
+If the test passes in its first run, then the output xml report will be identical to the case where `rerunFailingTestsCount` is not used.
 
-  It the test fails in the first run, then there are also two possible cases.
+It the test fails in the first run, then there are also two possible cases.
 
-  1) The test passes in one of its re-runs:
+1\) The test passes in one of its re-runs:
 
-  <<<flakyFailure>>> and <<<flakyError>>> elements will be used in the generated xml report to include information
-  of each failing re-runs. <<<system-out>>> and <<<system-err>>> will also be used inside each <<<flakyFailure>>>
-  or <<<flakyError>>> to include information of System.out and System.err output. The original <<<system-out>>>
-  and <<<system-err>>> elements will be retained on the top level under <<<testcase>>> for the last successful run.
+`flakyFailure` and `flakyError` elements will be used in the generated xml report to include information of each failing re-runs. `system-out` and `system-err` will also be used inside each `flakyFailure` or `flakyError` to include information of System.out and System.err output. The original `system-out` and `system-err` elements will be retained on the top level under `testcase` for the last successful run.
 
-  For example:
+For example:
 
-+---+
+```xml
 <testcase name=".." classname=".." time="0.1">
   <flakyFailure message="exception message" type="assertion exception">
     <stackTrace>flaky failure stack trace</stackTrace>
@@ -108,22 +95,17 @@ mvn -D${thisPlugin.toLowerCase()}.rerunFailingTestsCount=2 test
   </flakyFailure>
   <system-out> success </system-out>
 </testcase>
-+---+
+```
 
-  In the xml report, the running time of a flaky test will be the running time of the <<last successful run>>.
+In the xml report, the running time of a flaky test will be the running time of the **last successful run**.
 
-  2) The test fails in all of the re-runs:
+2\) The test fails in all of the re-runs:
 
-  <<<failure>>> and <<<error>>> elements will still be used in the generated xml report to include information
-  for the first failing run, the same as without using <<<rerunFailingTestsCount>>>. <<<rerunFailure>>> and <<<rerunError>>>
-  elements will be used in the generated xml report to include information of each <<subsequent>> failing re-runs.
-  <<<system-out>>> and <<<system-err>>> will also be used inside each <<<flakyFailure>>> or <<<flakyError>>> to include
-  information of System.out and System.err output. The original <<<system-out>>> and <<<system-err>>> elements will be
-  retained on the top level under <<<testcase>>> for the first original failing run.
+`failure` and `error` elements will still be used in the generated xml report to include information for the first failing run, the same as without using `rerunFailingTestsCount`. `rerunFailure` and `rerunError` elements will be used in the generated xml report to include information of each **subsequent** failing re-runs. `system-out` and `system-err` will also be used inside each `flakyFailure` or `flakyError` to include information of System.out and System.err output. The original `sy [...]
 
-  For example:
+For example:
 
-+---+
+```xml
 <testcase name=".." classname=".." time="0.1">
   <failure message="" type=""> first failure stack trace </failure>
   <system-out> first failure </system-out>
@@ -132,31 +114,26 @@ mvn -D${thisPlugin.toLowerCase()}.rerunFailingTestsCount=2 test
     <system-out> rerun failure </system-out>
   </rerunFailure>
 </testcase>
-+---+
+```
 
-  In the xml report, the running time of a failing test with re-runs will be the running time of the
-  <<first failing run>>.
+In the xml report, the running time of a failing test with re-runs will be the running time of the **first failing run**.
 
-* Re-run execution in JUnit Providers
+Re-run execution in JUnit Providers
+-----------------------------------
 
-  The provider <<<surefire-junit4>>> executes individual test class and consequently re-runs failed tests.
-  The provider <<<surefire-junit47>>> executes all test classes and re-runs failed tests afterwards.
+The provider `surefire-junit4` executes individual test class and consequently re-runs failed tests. The provider `surefire-junit47` executes all test classes and re-runs failed tests afterwards.
 
-* Re-run execution in Cucumber JVM
+Re-run execution in Cucumber JVM
+--------------------------------
 
-  Since of 2.21.0 the provider <<<surefire-junit47>>> can rerun scenarios created by <<cucumber-jvm>>
-  2.0.0 and higher.
+Since of 2.21.0 the provider `surefire-junit47` can rerun scenarios created by **cucumber-jvm** 2.0.0 and higher.
 
-* Re-run and skip execution
+Re-run and skip execution
+-------------------------
 
-  Since of 2.19.1 you can use parameters <<<skipAfterFailureCount>>> and <<<rerunFailingTestsCount>>> together.
-  This is enabled by providers <<<surefire-junit4>>> and <<<surefire-junit47>>>. You can run again failed tests
-  and skip the rest of the test-set if errors or failures reached <<<skipAfterFailureCount>>>.
-  Notice that failed tests within re-run phase are not included in <<<skipAfterFailureCount>>>.
+Since of 2.19.1 you can use parameters `skipAfterFailureCount` and `rerunFailingTestsCount` together. This is enabled by providers `surefire-junit4` and `surefire-junit47`. You can run again failed tests and skip the rest of the test-set if errors or failures reached `skipAfterFailureCount`. Notice that failed tests within re-run phase are not included in `skipAfterFailureCount`.
 
+Re-run and fail the build upon flaky test count
+-----------------------------------------------
 
-* Re-run and fail the build upon flaky test count
-
-  Since 3.0.0-M6 you can use <<<rerunFailingTestsCount>>> together with <<<failOnFlakeCount>>>.
-  This will fail the build if more than the specified number of tests are flaky, i.e. if they
-  had a successful run after previously failing.
+Since 3.0.0-M6 you can use `rerunFailingTestsCount` together with `failOnFlakeCount`. This will fail the build if more than the specified number of tests are flaky, i.e. if they had a successful run after previously failing.
diff --git a/maven-surefire-plugin/src/site/markdown/examples/shutdown.md.vm b/maven-surefire-plugin/src/site/markdown/examples/shutdown.md.vm
index 93083858d..8443ce5e5 100644
--- a/maven-surefire-plugin/src/site/markdown/examples/shutdown.md.vm
+++ b/maven-surefire-plugin/src/site/markdown/examples/shutdown.md.vm
@@ -1,98 +1,67 @@
- ------
- Forked JVM Shutdown
- ------
- Tibor Digana <ti...@apache.org>
- ------
- September 2015
- ------
- 
- ~~ 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: Forked JVM Shutdown
+author:
+  - Tibor Digana tibordigana@apache.org
+date: September 2015
+---
 
- ~~ 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
 
-Shutdown of Forked JVM
+  http://www.apache.org/licenses/LICENSE-2.0
 
-* Embedded shutdown
-  
-  After the test-set has completed, the process executes
-  <<<java.lang.System.exit(0)>>> which starts shutdown hooks. At this point
-  the process may run next 30 seconds until all non daemon Threads die.
-  After the period of time has elapsed, the process kills itself by
-  <<<java.lang.Runtime.halt(0)>>>. The timeout of 30 seconds can be
-  customized by configuration parameter <<<forkedProcessExitTimeoutInSeconds>>>.
+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.
+-->
 
-* Pinging forked JVM
+# Shutdown of Forked JVM
 
-  << Since ${thisPlugin} Plugin 2.20.1 ping is platform dependent and fallbacks to old mechanism if PID of Maven
-  process or platform is not recognized, native commands fail in Java. >>
+Embedded shutdown
+-----------------
 
-  Simply the mechanism checks the <<< Maven PID >>> is still alive and it is not reused by OS in another application.
-  If Maven process has died, the forked JVM is killed.
+After the test-set has completed, the process executes `java.lang.System.exit(0)` which starts shutdown hooks. At this point the process may run next 30 seconds until all non daemon Threads die. After the period of time has elapsed, the process kills itself by `java.lang.Runtime.halt(0)`. The timeout of 30 seconds can be customized by configuration parameter `forkedProcessExitTimeoutInSeconds`.
 
-  << Implementation: >> The <<< Maven PID >>> is determined by:
+Pinging forked JVM
+------------------
 
-   * Java 9 call <<< ProcessHandle.current().pid() >>>, or
+**Since ${thisPlugin} Plugin 2.20.1 ping is platform dependent and fallbacks to old mechanism if PID of Maven process or platform is not recognized, native commands fail in Java.**
 
-   * resolving PID from <<< /proc/self/stat >>> on Linux and <<< /proc/curproc/status >>> on BSD, or
+Simply the mechanism checks the ` Maven PID ` is still alive and it is not reused by OS in another application. If Maven process has died, the forked JVM is killed.
 
-   * the JMX call <<< ManagementFactory.getRuntimeMXBean().getName() >>>.
+**Implementation:** The ` Maven PID ` is determined by:
 
-   []
+- Java 9 call ` ProcessHandle.current().pid() `, or
+- resolving PID from ` /proc/self/stat ` on Linux and ` /proc/curproc/status ` on BSD, or
+- the JMX call ` ManagementFactory.getRuntimeMXBean().getName() `.
 
-   If Java9 is available, the start time of the process is determined by <<< ProcessHandle.current().info().startInstant() >>>.
+If Java9 is available, the start time of the process is determined by ` ProcessHandle.current().info().startInstant() `.
 
-   On Unix like systems the process' uptime is determined by native command <<< (/usr)/bin/ps -o etime= -p [PID] >>>.
+On Unix like systems the process' uptime is determined by native command ` (/usr)/bin/ps -o etime= -p [PID] `.
 
-   On Windows the start time is determined using <<< powershell -command "... Get-CimInstance Win32_Process ..." >>>.
+On Windows the start time is determined using ` powershell -command "... Get-CimInstance Win32_Process ..." `.
 
-   []
-   in the forked JVM.
+**Since ${thisPlugin} Plugin 2.19 the old mechanism is significantly slower:**
 
+The master process sends NOOP command to a forked JVM every 10 seconds. Forked JVM is waiting for the command every 20 seconds (changed to 30 seconds since version 2.20.1, see [SUREFIRE-1302](https://issues.apache.org/jira/browse/SUREFIRE-1302)). If the master process is killed (received SIGKILL signal) or shutdown (pressed CTRL+C, received SIGTERM signal), forked JVM is killed after timing out waiting period.
 
-  << Since ${thisPlugin} Plugin 2.19 the old mechanism is significantly slower: >>
+NOTICE: After version `3.0.0-M4` this feature has to be enabled by setting the configuration parameter `enableProcessChecker` to `ping` or `all`.
 
-  The master process sends NOOP command to a forked JVM every 10 seconds.
-  Forked JVM is waiting for the command every 20 seconds (changed to 30 seconds since version 2.20.1, see
-  {{{https://issues.apache.org/jira/browse/SUREFIRE-1302}SUREFIRE-1302}}).
-  If the master process is killed (received SIGKILL signal) or shutdown 
-  (pressed CTRL+C, received SIGTERM signal), forked JVM is killed after
-  timing out waiting period.
+Shutdown of forked JVM by stopping the build
+--------------------------------------------
 
+After the master process of the build is shutdown by sending SIGTERM signal or pressing CTRL+C, the master process immediately sends SHUTDOWN command to every forked JVM. By default (configuration parameter `shutdown=testset`) forked JVM would not pick up a new test which means that the current test may still continue to run. The SIGTERM signal triggers Java shutdownhook which executes `java.lang.Process.destroy()` in the forked JVM (not always reliable depending on VM and OS). The param [...]
 
-  NOTICE: After version <<<3.0.0-M4>>> this feature has to be enabled by setting the configuration
-  parameter <<<enableProcessChecker>>> to <<<ping>>> or <<<all>>>.
-
-* Shutdown of forked JVM by stopping the build
-
-  After the master process of the build is shutdown by sending SIGTERM signal
-  or pressing CTRL+C, the master process immediately sends SHUTDOWN command to
-  every forked JVM. By default (configuration parameter <<<shutdown=testset>>>)
-  forked JVM would not pick up a new test which means that the current
-  test may still continue to run. The SIGTERM signal triggers Java shutdownhook
-  which executes <<<java.lang.Process.destroy()>>> in the forked JVM (not always
-  reliable depending on VM and OS).
-  The parameter <<<shutdown>>> can be configured with other two values
-  <<<exit>>> and <<<kill>>>. Using <<<exit>>> forked JVM executes
-  <<<java.lang.System.exit(1)>>> after the master process has received SIGTERM.
-  Using <<<kill>>> the JVM executes <<<java.lang.Runtime.halt(1)>>>, example:
-
-+---+
+```xml
 <project>
   [...]
   <build>
@@ -109,24 +78,18 @@ Shutdown of Forked JVM
   </build>
   [...]
 </project>
-+---+
-
-
-  NOTICE: After version <<<3.0.0-M4>>> this feature has to be enabled by setting the configuration
-  parameter <<<enableProcessChecker>>> to <<<ping>>> or <<<native>>> or <<<all>>>.
-
-* Shutdown of forked JVM after certain timeout
+```
 
-  Using parameter <<<forkedProcessTimeoutInSeconds>>> forked JVMs
-  are killed separately after every individual process elapsed certain
-  amount of time and the whole plugin fails with the error message:
+NOTICE: After version `3.0.0-M4` this feature has to be enabled by setting the configuration parameter `enableProcessChecker` to `ping` or `native` or `all`.
 
-  <<<There was a timeout in the fork>>>
+Shutdown of forked JVM after certain timeout
+--------------------------------------------
 
+Using parameter `forkedProcessTimeoutInSeconds` forked JVMs are killed separately after every individual process elapsed certain amount of time and the whole plugin fails with the error message:
 
-* Crashed forked JVM caused listing the crashed test(s)
+`There was a timeout in the fork`
 
-  After the JVM exited abruptly, the console lists the message <<<Crashed tests:>>> with a list of crashed tests if the
-  entire test-set has not been yet completed. This happens if a test exited, killed JVM or a segmentation fault crashed
-  JVM. In such cases you may be interested in dump files generated in reports directory, see {{{../faq.html#dumpfiles}FAQ}}.
+Crashed forked JVM caused listing the crashed test(s)
+-----------------------------------------------------
 
+After the JVM exited abruptly, the console lists the message `Crashed tests:` with a list of crashed tests if the entire test-set has not been yet completed. This happens if a test exited, killed JVM or a segmentation fault crashed JVM. In such cases you may be interested in dump files generated in reports directory, see [FAQ](../faq.html#dumpfiles).
diff --git a/maven-surefire-plugin/src/site/markdown/examples/single-test.md.vm b/maven-surefire-plugin/src/site/markdown/examples/single-test.md.vm
index 7c45dbc8a..9d49b3740 100644
--- a/maven-surefire-plugin/src/site/markdown/examples/single-test.md.vm
+++ b/maven-surefire-plugin/src/site/markdown/examples/single-test.md.vm
@@ -1,165 +1,139 @@
-  ------
-  Running a Single Test
-  ------
-  Allan Ramirez
-  Olivier Lamy
-  ------
- 2012-02-28
-  ------
-  
- ~~ 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
-
-Running a Single Test
+---
+title: Running a Single Test
+author:
+  - Allan Ramirez
+  - Olivier Lamy
+date: 2012-02-28
+---
+
+<!--
+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.
+-->
+
+# Running a Single Test
 
 #{if}(${project.artifactId}=="maven-surefire-plugin")
-  During development, you may run a single test class repeatedly. To run this
-  through Maven, set the <<<test>>> property to a specific test case.
+During development, you may run a single test class repeatedly. To run this through Maven, set the `test` property to a specific test case.
+#{else}
+During development, you may run a single test class repeatedly. To run this through Maven, set the `it.test` property to a specific test case.
+#{end}
 
-+---+
+```text
+#{if}(${project.artifactId}=="maven-surefire-plugin")
 mvn -Dtest=TestCircle test
-+---+
+#{else}
+mvn -Dit.test=ITCircle verify
+#{end}
+```
 
-If you have multiple executions configured in surefire plugin within your POM, you may want to execute the only default test phase:
+#{if}(${project.artifactId}=="maven-surefire-plugin")
+# If you have multiple executions configured in surefire plugin within your POM, you may want to execute the only default test phase:
 
-+---+
+```bash
 mvn surefire:test -Dtest=TestCircle
-+---+
+```
 
-  The value for the <<<test>>> parameter is the name of the test class (without the extension; we'll strip off the extension if you accidentally provide one).
+The value for the `test` parameter is the name of the test class (without the extension; we'll strip off the extension if you accidentally provide one).
 #{else}
-  During development, you may run a single test class repeatedly. To run this
-  through Maven, set the <<<it.test>>> property to a specific test case.
-
-+---+
-mvn -Dit.test=ITCircle verify
-+---+
-
-  The value for the <<<it.test>>> parameter is the name of the test class (without the extension; we'll strip off the extension if you accidentally provide one).
+The value for the `it.test` parameter is the name of the test class (without the extension; we'll strip off the extension if you accidentally provide one).
 #{end}
 
-  You may also use patterns to run a number of tests:
+You may also use patterns to run a number of tests:
 
+```text
 #{if}(${project.artifactId}=="maven-surefire-plugin")
-+---+
 mvn -Dtest=TestCi*le test
-+---+
 #{else}
-+---+
 mvn -Dit.test=ITCi*le verify
-+---+
 #{end}
+```
 
-  And you may use multiple names/patterns, separated by commas:
+And you may use multiple names/patterns, separated by commas:
 
+```text
 #{if}(${project.artifactId}=="maven-surefire-plugin")
-+---+
 mvn -Dtest=TestSquare,TestCi*le test
-+---+
 #{else}
-+---+
 mvn -Dit.test=ITSquare,ITCi*le verify
-+---+
 #{end}
+```
+
+**NOTE: Use syntax e.g. "foo/MyTest.java", "\*\*/MyTest.java", "MyTest" for "test" parameter (see includes/excludes).**
+
+# Running a Set of Methods in a Single Test Class
 
-  << NOTE: Use syntax e.g. "foo/MyTest.java", "**/MyTest.java", "MyTest" for "test" parameter (see includes/excludes). >>
+You can also run only a subset of the tests in a test class.
 
-Running a Set of Methods in a Single Test Class
+**NOTE : This feature is supported only for Junit 4.x and TestNG. Use syntax e.g. "foo/MyTest.java", "\*\*/MyTest.java", "MyTest" for "test" parameter (see includes/excludes).**
 
-  You can also run only a subset of the tests in a test class.
-  
-  << NOTE : This feature is supported only for Junit 4.x and TestNG. Use syntax e.g. "foo/MyTest.java",
-  "**/MyTest.java", "MyTest" for "test" parameter (see includes/excludes). >>
-  
-  You should use the following syntax:
-  
+You should use the following syntax:
+
+```text
 #{if}(${project.artifactId}=="maven-surefire-plugin")
-+---+
 mvn -Dtest=TestCircle#mytest test
-+---+
 #{else}
-+---+
 mvn -Dit.test=ITCircle#mytest verify
-+---+
 #{end}
+```
+
+You can use patterns too:
 
-  You can use patterns too:
-  
+```text
 #{if}(${project.artifactId}=="maven-surefire-plugin")
-+---+
 mvn -Dtest=TestCircle#test* test
-+---+
 #{else}
-+---+
 mvn -Dit.test=ITCircle#test* verify
-+---+
 #{end}
+```
 
-  You can select multiple methods (JUnit 4, JUnit 4.7+ and TestNG):
+You can select multiple methods (JUnit 4, JUnit 4.7+ and TestNG):
 
+```text
 #{if}(${project.artifactId}=="maven-surefire-plugin")
-+---+
 mvn -Dtest=TestCircle#testOne+testTwo test
-+---+
 #{else}
-+---+
 mvn -Dit.test=ITCircle#testOne+testTwo verify
-+---+
 #{end}
+```
 
+# Multiple Formats in One
 
-Multiple Formats in One
-
-  Multiple formats are supported in one pattern (JUnit 4, JUnit 4.7+, TestNG):
+Multiple formats are supported in one pattern (JUnit 4, JUnit 4.7+, TestNG):
 
+```text
 #{if}(${project.artifactId}=="maven-surefire-plugin")
-+---+
 mvn "-Dtest=???Test, !Unstable*, pkg/**/Ci*leTest.java, *Test#test*One+testTwo?????, #fast*+slowTest" test
 mvn "-Dtest=Basic*, !%regex[.*.Unstable.*], !%regex[.*.MyTest.class#one.*|two.*], %regex[#fast.*|slow.*]" test
-+---+
 #{else}
-+---+
 mvn "-Dit.test=???IT, !Unstable*, pkg/**/Ci*leIT.java, *IT#test*One+testTwo?????, #fast*+slowTest" verify
 mvn "-Dit.test=Basic*, !%regex[.*.Unstable.*], !%regex[.*.MyIT.class#one.*|two.*], %regex[#fast.*|slow.*]" verify
-+---+
 #{end}
+```
 
-  The exclamation mark (!) excludes tests. The character (?) within non-regex pattern replaces one character in file
-  name or path. The file extensions are not mandatory in non-regex patterns, and packages with slash can be used.
-  The regex validates fully qualified class file, and validates test methods separately after (#) however class
-  is optional. The regex supports '.class' file extension only. Note the regex comments, marked by (#)
-  character, are unsupported. The Parameterized JUnit runner describes test methods using an index in brackets, so the
-  non-regex method pattern would become <<<#testMethod[*]>>>. If using the JUnit annotation
-  <<<@Parameters(name="\{index\}: fib(\{0\})=\{1\}")>>> and selecting the index e.g. 5 in pattern, the non-regex
-  method pattern would become <<<#testMethod[5:*]>>>.
+The exclamation mark (\!) excludes tests. The character (?) within non-regex pattern replaces one character in file name or path. The file extensions are not mandatory in non-regex patterns, and packages with slash can be used. The regex validates fully qualified class file, and validates test methods separately after (#) however class is optional. The regex supports '.class' file extension only. Note the regex comments, marked by (#) character, are unsupported. The Parameterized JUnit r [...]
 
-* Fully qualified class name
+Fully qualified class name
+--------------------------
 
-  The syntax with fully qualified class names or packages can be used. For example:
+The syntax with fully qualified class names or packages can be used. For example:
 
-+---+
+```xml
 <test>my.package.???Test#testMethod, another.package.*</test>
-+---+
-
-  The character (?) replaces single character and (*) represents zero or more characters.
-  Multiple formats can be combined.
-
-
+```
 
+The character (?) replaces single character and (*) represents zero or more characters. Multiple formats can be combined.
diff --git a/maven-surefire-plugin/src/site/markdown/examples/skip-after-failure.md.vm b/maven-surefire-plugin/src/site/markdown/examples/skip-after-failure.md.vm
index 88576d717..0663ad19c 100644
--- a/maven-surefire-plugin/src/site/markdown/examples/skip-after-failure.md.vm
+++ b/maven-surefire-plugin/src/site/markdown/examples/skip-after-failure.md.vm
@@ -1,85 +1,60 @@
-  ------
-  Skipping Tests After Failure
-  ------
-  Tibor Digana
-  ------
-  July 2015
-  ------
-  
- ~~ 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
-
-Skipping Tests After First Failure
-
- To skip remaining tests after first failure or error has happened
- set configuration parameter <<<skipAfterFailureCount>>> to <<<1>>>.
- 
- 
-Skipping Tests After the Nth Failure or Error
-
- To skip remaining tests after the Nth failure or error has happened
- set configuration parameter <<<skipAfterFailureCount>>> to N, where
- N is number greater than zero.
- 
- 
-Prerequisite
- 
- Use ${project.artifactId} 2.19 or higher, JUnit 4.0 or higher, TestNG 5.10 or
- higher, or JUnit Platform 6.0 or higher.
- 
- If version of TestNG is lower than 5.10 while the parameter 
- <<<skipAfterFailureCount>>> is set, the plugin fails with error:
- 
- <<<[ERROR] Failed to execute goal ...: Parameter "skipAfterFailureCount"
- expects TestNG Version 5.10 or higher. java.lang.NoClassDefFoundError:
- org/testng/IInvokedMethodListener>>>
-
- 
- 
- If version of JUnit is lower than 4.0 while the parameter 
- <<<skipAfterFailureCount>>> is set, the plugin fails with error:
- 
- <<<[ERROR] Failed to execute goal ...: Parameter "skipAfterFailureCount"
- expects JUnit Version 4.0 or higher. java.lang.NoSuchMethodError:
- org.junit.runner.notification.RunNotifier.pleaseStop()V>>>
- 
- 
-Notices
- 
- TestNG reports skipped methods however JUnit reports skipped classes.
- Preferably use JUnit 4.12 or higher version which fixed thread safety issues.
- 
- 
-Limitations
- 
- Although this feature works in forking modes as well, the functionality
- cannot be fully guaranteed (real first failure) in concurrent mode
- due to race conditions.
- The parameter <<<reuseForks>>> should be always set to <<<true>>> (which is
- default value), otherwise this feature won't work properly in most cases.
-
-Other features
-
-* Re-run and skip execution
-
-  Since of 2.19.1 you can use parameters <<<skipAfterFailureCount>>> and <<<rerunFailingTestsCount>>> together.
-  This is enabled by providers <<<surefire-junit4>>> and <<<surefire-junit47>>>. You can run again failed tests
-  and skip the rest of the test-set if errors or failures reached <<<skipAfterFailureCount>>>.
-  Notice that failed tests within re-run phase are not included in <<<skipAfterFailureCount>>>.
+---
+title: Skipping Tests After Failure
+author:
+  - Tibor Digana
+date: July 2015
+---
+
+<!--
+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.
+-->
+
+# Skipping Tests After First Failure
+
+To skip remaining tests after first failure or error has happened set configuration parameter `skipAfterFailureCount` to `1`.
+
+# Skipping Tests After the Nth Failure or Error
+
+To skip remaining tests after the Nth failure or error has happened set configuration parameter `skipAfterFailureCount` to N, where N is number greater than zero.
+
+# Prerequisite
+
+Use ${project.artifactId} 2.19 or higher, JUnit 4.0 or higher, TestNG 5.10 or higher, or JUnit Platform 6.0 or higher.
+
+If version of TestNG is lower than 5.10 while the parameter `skipAfterFailureCount` is set, the plugin fails with error:
+
+`[ERROR] Failed to execute goal ...: Parameter "skipAfterFailureCount" expects TestNG Version 5.10 or higher. java.lang.NoClassDefFoundError: org/testng/IInvokedMethodListener`
+
+If version of JUnit is lower than 4.0 while the parameter `skipAfterFailureCount` is set, the plugin fails with error:
+
+`[ERROR] Failed to execute goal ...: Parameter "skipAfterFailureCount" expects JUnit Version 4.0 or higher. java.lang.NoSuchMethodError: org.junit.runner.notification.RunNotifier.pleaseStop()V`
+
+# Notices
+
+TestNG reports skipped methods however JUnit reports skipped classes. Preferably use JUnit 4.12 or higher version which fixed thread safety issues.
+
+# Limitations
+
+Although this feature works in forking modes as well, the functionality cannot be fully guaranteed (real first failure) in concurrent mode due to race conditions. The parameter `reuseForks` should be always set to `true` (which is default value), otherwise this feature won't work properly in most cases.
+
+# Other features
+
+Re-run and skip execution
+-------------------------
+
+Since of 2.19.1 you can use parameters `skipAfterFailureCount` and `rerunFailingTestsCount` together. This is enabled by providers `surefire-junit4` and `surefire-junit47`. You can run again failed tests and skip the rest of the test-set if errors or failures reached `skipAfterFailureCount`. Notice that failed tests within re-run phase are not included in `skipAfterFailureCount`.
diff --git a/maven-surefire-plugin/src/site/markdown/examples/skipping-tests.md.vm b/maven-surefire-plugin/src/site/markdown/examples/skipping-tests.md.vm
index 7b8e3a8f1..9562845de 100644
--- a/maven-surefire-plugin/src/site/markdown/examples/skipping-tests.md.vm
+++ b/maven-surefire-plugin/src/site/markdown/examples/skipping-tests.md.vm
@@ -1,41 +1,42 @@
-  ------
-  Skipping Tests
-  ------
-  Johnny Ruiz
-  Brett Porter
-  Allan Ramirez
-  ------
-  July 2006
-  ------
-
- ~~ 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
-
-Skipping Tests
+---
+title: Skipping Tests
+author:
+  - Johnny Ruiz
+  - Brett Porter
+  - Allan Ramirez
+date: July 2006
+---
+
+<!--
+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.
+-->
+
+# Skipping Tests
 
 #{if}(${project.artifactId}=="maven-surefire-plugin")
+To skip running the tests for a particular project, set the **skipTests** property to **true**.
+#{else}
+To skip running the tests for a particular project, set the **skipITs** property to **true**.
+#{end}
 
- To skip running the tests for a particular project, set the <<skipTests>> property to <<true>>.
-
-+---+
+```xml
 <project>
+#{if}(${project.artifactId}=="maven-surefire-plugin")
   [...]
   <build>
     <plugins>
@@ -50,21 +51,7 @@ Skipping Tests
     </plugins>
   </build>
   [...]
-</project>
-+---+
-
- You can also skip the tests via the command line by executing the following command:
-
-+---+
-mvn install -DskipTests
-+---+
-
 #{else}
-
- To skip running the tests for a particular project, set the <<skipITs>> property to <<true>>.
-
-+---+
-<project>
     [...]
     <build>
         <plugins>
@@ -79,43 +66,37 @@ mvn install -DskipTests
         </plugins>
     </build>
     [...]
+#{end}
 </project>
-+---+
+```
 
- You can also skip the tests via the command line by executing the following command:
+You can also skip the tests via the command line by executing the following command:
 
-+---+
+```bash
 mvn install -DskipTests
-+---+
+#{if}(${project.artifactId}=="maven-failsafe-plugin")
+```
 
- Since <<<skipTests>>> is also supported by the ${thatPlugin} Plugin, this will have the effect
- of not running any tests.  If, instead, you want to skip only the integration tests
- being run by the ${thisPlugin} Plugin, you would use the <<<skipITs>>> property instead:
+Since `skipTests` is also supported by the ${thatPlugin} Plugin, this will have the effect of not running any tests. If, instead, you want to skip only the integration tests being run by the ${thisPlugin} Plugin, you would use the `skipITs` property instead:
 
-+---+
+```bash
 mvn install -DskipITs
-+---+
-
 #{end}
+```
 
+If you absolutely must, you can also use the `maven.test.skip` property to skip compiling the tests. `maven.test.skip` is honored by Surefire, Failsafe and the Compiler Plugin.
 
-
- If you absolutely must, you can also use the <<<maven.test.skip>>> property to skip compiling the tests.
- <<<maven.test.skip>>> is honored by Surefire, Failsafe and the Compiler Plugin.
-
-+---+
+```bash
 mvn install -Dmaven.test.skip=true
-+---+
+```
 
-Skipping by Default
+# Skipping by Default
 
-   If you want to skip tests by default but want the ability to re-enable tests from the
-   command line, you need to go via a properties section in the pom:
+If you want to skip tests by default but want the ability to re-enable tests from the command line, you need to go via a properties section in the pom:
 
-#{if}(${project.artifactId}=="maven-surefire-plugin")
-
-+---+
+```xml
 <project>
+#{if}(${project.artifactId}=="maven-surefire-plugin")
   [...]
   <properties>
     <skipTests>true</skipTests>
@@ -134,13 +115,7 @@ Skipping by Default
     </plugins>
   </build>
   [...]
-</project>
-+---+
-
 #{else}
-
-+---+
-<project>
     [...]
     <properties>
         <skipTests>true</skipTests>
@@ -159,15 +134,14 @@ Skipping by Default
         </plugins>
     </build>
     [...]
-</project>
-+---+
-
 #{end}
+</project>
+```
 
-   This will allow you to run with all tests disabled by default and to run them with this command:
+This will allow you to run with all tests disabled by default and to run them with this command:
 
-+---+
+```bash
 mvn install -DskipTests=false
-+---+
+```
 
-   The same can be done with the <<<skip>>> parameter and other boolean properties of the plugin.
+The same can be done with the `skip` parameter and other boolean properties of the plugin.
diff --git a/maven-surefire-plugin/src/site/markdown/examples/spock.md.vm b/maven-surefire-plugin/src/site/markdown/examples/spock.md.vm
index dca2ca156..f433dbde6 100644
--- a/maven-surefire-plugin/src/site/markdown/examples/spock.md.vm
+++ b/maven-surefire-plugin/src/site/markdown/examples/spock.md.vm
@@ -1,44 +1,39 @@
- ------
- Using Spock
- ------
- Tibor Digana <ti...@apache.org>
- ------
- 2020-05-05
- ------
-
- ~~ 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
-
-Using the Spock based on JUnit5 engine
-
-* Sample project with Spock/Groovy and JUnit5
-
-  This {{{https://github.com/apache/maven-surefire/tree/master/surefire-its/src/test/resources/junit5-spock}sample code}}
-  shows you how the ${thisPlugin} plugin works with Spock/Groovy and JUnit5. The project contains two dependencies
-  <<<spock-core>>> and <<<junit-jupiter-engine>>>, and Groovy compiler <<<gmavenplus-plugin>>>.
-
-  You can create tests in test source directory for Groovy (i.e., <<<src/test/groovy>>>). This is an example with
-  parameterized test which is executed twice.
-
-
-+---+
+---
+title: Using Spock
+author:
+  - Tibor Digana tibordigana@apache.org
+date: 2020-05-05
+---
+
+<!--
+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.
+-->
+
+# Using the Spock based on JUnit5 engine
+
+Sample project with Spock/Groovy and JUnit5
+-------------------------------------------
+
+This [sample code](https://github.com/apache/maven-surefire/tree/master/surefire-its/src/test/resources/junit5-spock) shows you how the ${thisPlugin} plugin works with Spock/Groovy and JUnit5. The project contains two dependencies `spock-core` and `junit-jupiter-engine`, and Groovy compiler `gmavenplus-plugin`.
+
+You can create tests in test source directory for Groovy (i.e., `src/test/groovy`). This is an example with parameterized test which is executed twice.
+
+```java
 import pkg.Calculator
 import spock.lang.Specification
 
@@ -62,15 +57,11 @@ class CalculatorTest extends Specification
         -5 | 2 | -3
     }
 }
-+---+
-
+```
 
-  If you want to additionally mix Spock tests with the JUnit4, you should add the JUnit Vintage Engine
-  in the test dependencies.
+If you want to additionally mix Spock tests with the JUnit4, you should add the JUnit Vintage Engine in the test dependencies.
 
-
-#{if}(${project.artifactId}=="maven-failsafe-plugin")
-+---+
+```xml
 <dependencies>
     [...]
     <dependency>
@@ -107,6 +98,7 @@ class CalculatorTest extends Specification
             <groupId>${project.groupId}</groupId>
             <artifactId>${project.artifactId}</artifactId>
             <version>${project.version}</version>
+#{if}(${project.artifactId}=="maven-failsafe-plugin")
             <executions>
                 <execution>
                     <id>integration-test</id>
@@ -121,54 +113,10 @@ class CalculatorTest extends Specification
                     </goals>
                 </execution>
             </executions>
+#{end}
         </plugin>
         [...]
     </plugins>
 </build>
 ...
-+---+
-#{else}
-+---+
-<dependencies>
-    [...]
-    <dependency>
-        <groupId>org.spockframework</groupId>
-        <artifactId>spock-core</artifactId>
-        <version>2.0-M2-groovy-3.0</version>
-        <scope>test</scope>
-    </dependency>
-    <dependency>
-        <groupId>org.junit.jupiter</groupId>
-        <artifactId>junit-jupiter-engine</artifactId>
-        <version>5.9.1</version>
-        <scope>test</scope>
-    </dependency>
-    [...]
-</dependencies>
-...
-<build>
-    <plugins>
-        [...]
-        <plugin>
-            <groupId>org.codehaus.gmavenplus</groupId>
-            <artifactId>gmavenplus-plugin</artifactId>
-            <version>1.9.0</version>
-            <executions>
-                <execution>
-                    <goals>
-                        <goal>compileTests</goal>
-                    </goals>
-                </execution>
-            </executions>
-        </plugin>
-        <plugin>
-            <groupId>${project.groupId}</groupId>
-            <artifactId>${project.artifactId}</artifactId>
-            <version>${project.version}</version>
-        </plugin>
-        [...]
-    </plugins>
-</build>
-...
-+---+
-#{end}
+```
diff --git a/maven-surefire-plugin/src/site/markdown/examples/system-properties.md.vm b/maven-surefire-plugin/src/site/markdown/examples/system-properties.md.vm
index aceded1ac..5b320b6d6 100644
--- a/maven-surefire-plugin/src/site/markdown/examples/system-properties.md.vm
+++ b/maven-surefire-plugin/src/site/markdown/examples/system-properties.md.vm
@@ -1,46 +1,43 @@
-  ------
-  Using System Properties
-  ------
-  Allan Ramirez
-  Dan Tran
-  Konrad Windszus
-  ------
-  2010-01-09
-  ------
-  
- ~~ 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
-
-Using System Properties
-
-%{toc|section=0|fromDepth=2}
-
-
-  There are different parameters which affect the system properties passed to ${thisPlugin} providers:
-
-* systemPropertyVariables
-
-  This configuration is the replacement of the deprecated <<<systemProperties>>>. It can accept any {{{https://maven.apache.org/ref/3-LATEST/maven-model-builder/#model-interpolation}expression value}}
-  referencing Maven's properties that can be converted <<to a String value>> or arbitrary literals.
-
-+---+
+---
+title: Using System Properties
+author:
+  - Allan Ramirez
+  - Dan Tran
+  - Konrad Windszus
+date: 2010-01-09
+---
+
+<!--
+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.
+-->
+
+# Using System Properties
+
+<!-- MACRO{toc|section=0|fromDepth=2} -->
+
+There are different parameters which affect the system properties passed to ${thisPlugin} providers:
+
+systemPropertyVariables
+-----------------------
+
+This configuration is the replacement of the deprecated `systemProperties`. It can accept any [expression value](https://maven.apache.org/ref/3-LATEST/maven-model-builder/#model-interpolation) referencing Maven's properties that can be converted **to a String value** or arbitrary literals.
+
+```xml
 <project>
   [...]
   <build>
@@ -61,15 +58,17 @@ Using System Properties
   </build>
   [...]
 </project>
-+---+
+```
 
-* systemPropertiesFile
+systemPropertiesFile
+--------------------
 
-  This configuration allows to add system properties through an external properties file whose path is given via this plugin parameter.
+This configuration allows to add system properties through an external properties file whose path is given via this plugin parameter.
 
-* systemProperties (Deprecated)
+systemProperties (Deprecated)
+-----------------------------
 
-+---+
+```xml
 <project>
   [...]
   <build>
@@ -92,14 +91,11 @@ Using System Properties
   </build>
   [...]
 </project>
-+---+
+```
 
-  Take note that only <<String typed>> properties can be passed as system
-  properties. Any attempt to pass any other Maven variable type (e.g. a <<<List>>>
-  or a <<<URL>>> variable) will cause the variable expression to be passed
-  literally (unevaluated). So given the example below:
+Take note that only **String typed** properties can be passed as system properties. Any attempt to pass any other Maven variable type (e.g. a `List` or a `URL` variable) will cause the variable expression to be passed literally (unevaluated). So given the example below:
 
-+---+
+```xml
 <project>
   [...]
   <build>
@@ -112,7 +108,7 @@ Using System Properties
           <systemProperties>
             <property>
               <name>buildDir</name>
-              <value>\${project.build.outputDirectory}</value>
+              <value>${esc.d}{project.build.outputDirectory}</value>
             </property>
           </systemProperties>
         </configuration>
@@ -121,44 +117,37 @@ Using System Properties
   </build>
   [...]
 </project>
-+---+
+```
 
-  The string <<$\{project.build.outputDirectory\}>> will be passed on literally because the type
-  of that expression is a <<<File>>>, not a <<<String>>>.
+The string **${esc.d}{project.build.outputDirectory}** will be passed on literally because the type of that expression is a `File`, not a `String`.
 
-  To inherit the <<<systemProperties>>> collection from the parent configuration,
-  you will need to specify <<<combine.children="append">>> on the <<<systemProperties>>> node in the child pom:
+To inherit the `systemProperties` collection from the parent configuration, you will need to specify `combine.children="append"` on the `systemProperties` node in the child pom:
 
-+---+
+```xml
   <systemProperties combine.children="append">
       <property>
          [...]
       </property>
    </systemProperties>
-+---+
+```
 
-* Effective System Properties
+Effective System Properties
+---------------------------
 
-  The effective system properties are merged from the following sources:
+The effective system properties are merged from the following sources:
 
-  [[1]] <<<systemProperties>>>
+1. `systemProperties`
+1. `systemPropertiesFile`
+1. `systemPropertyVariables`
+1. [User properties from the current Maven session](https://maven.apache.org/ref/3-LATEST/maven-core/apidocs/org/apache/maven/execution/MavenSession.html#getUserProperties()) (if `promoteUserPropertiesToSystemProperties` is not set to `false`)
 
-  [[2]] <<<systemPropertiesFile>>>
+where latter items may overwrite properties with the same name of former items.
 
-  [[3]] <<<systemPropertyVariables>>>
+Special VM Properties
+---------------------
 
-  [[4]] {{{https://maven.apache.org/ref/3-LATEST/maven-core/apidocs/org/apache/maven/execution/MavenSession.html#getUserProperties()}User properties from the current Maven session}} (if <<<promoteUserPropertiesToSystemProperties>>> is not set to <<<false>>>)
+Some system properties must be set on the command line of the forked VM, and cannot be set after the VM has been started. These properties must be added to the `argLine` parameter of the Surefire plugin. E.g.,
 
-  []
-
-  where latter items may overwrite properties with the same name of former items.
-
-
-* Special VM Properties
-
-  Some system properties must be set on the command line of the forked VM, and cannot be set after the
-  VM has been started. These properties must be added to the <<<argLine>>> parameter of the Surefire plugin. E.g.,
-
-+---+
+```xml
   <argLine>-Djava.endorsed.dirs=...</argLine>
-+---+
+```
diff --git a/maven-surefire-plugin/src/site/markdown/examples/testng.md.vm b/maven-surefire-plugin/src/site/markdown/examples/testng.md.vm
index 5704d8d2d..4501fd2cc 100644
--- a/maven-surefire-plugin/src/site/markdown/examples/testng.md.vm
+++ b/maven-surefire-plugin/src/site/markdown/examples/testng.md.vm
@@ -1,38 +1,37 @@
- ------
- Using TestNG
- ------
- Brett Porter <br...@apache.org>
- ------
- 2010-01-09
- ------
- 
- ~~ 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
-
-Using TestNG
-
-* Configuring TestNG
-
-  To get started with TestNG, include the following dependency in your project (replacing the version with the one you wish to use):
-
-+---+
+---
+title: Using TestNG
+author:
+  - Brett Porter brett@apache.org
+date: 2010-01-09
+---
+
+<!--
+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.
+-->
+
+# Using TestNG
+
+Configuring TestNG
+------------------
+
+To get started with TestNG, include the following dependency in your project (replacing the version with the one you wish to use):
+
+```xml
 <dependencies>
   [...]
     <dependency>
@@ -43,28 +42,22 @@ Using TestNG
     </dependency>
   [...]
 </dependencies>
-+---+
-
+```
 
 #{if}(${project.artifactId}=="maven-surefire-plugin")
-  This is the only step that is required to get started - you can now create tests in your test source directory
-  (e.g., <<<src/test/java>>>). As long as they are named in accordance with the defaults such as <<<*Test.java>>> they will be run
-  by ${thisPlugin} as TestNG tests.
+This is the only step that is required to get started - you can now create tests in your test source directory (e.g., `src/test/java`). As long as they are named in accordance with the defaults such as `*Test.java` they will be run by ${thisPlugin} as TestNG tests.
 #{else}
-  This is the only step that is required to get started - you can now create tests in your test source directory
-  (e,g., <<<src/test/java>>>). As long as they are named in accordance with the defaults such as <<<*IT.java>>> they will be run
-  by ${thisPlugin} as TestNG tests.
+This is the only step that is required to get started - you can now create tests in your test source directory (e,g., `src/test/java`). As long as they are named in accordance with the defaults such as `*IT.java` they will be run by ${thisPlugin} as TestNG tests.
 #{end}
 
-  If you'd like to use a different naming scheme, you can change the <<<includes>>> parameter, as discussed in the
-  {{{./inclusion-exclusion.html}Inclusions and Exclusions of Tests}} example.
+If you'd like to use a different naming scheme, you can change the `includes` parameter, as discussed in the [Inclusions and Exclusions of Tests](./inclusion-exclusion.html) example.
 
-* Using Suite XML Files
+Using Suite XML Files
+---------------------
 
-  Another alternative is to use TestNG suite XML files. This allows flexible configuration of the tests to be run.
-  These files are created in the normal way, and then added to the ${thisPlugin} Plugin configuration:
+Another alternative is to use TestNG suite XML files. This allows flexible configuration of the tests to be run. These files are created in the normal way, and then added to the ${thisPlugin} Plugin configuration:
 
-+---+
+```xml
 <plugins>
     [...]
       <plugin>
@@ -79,16 +72,16 @@ Using TestNG
       </plugin>
     [...]
 </plugins>
-+---+
+```
 
-  This configuration will override the includes and excludes patterns and run all tests in the suite files.
+This configuration will override the includes and excludes patterns and run all tests in the suite files.
 
-* Specifying Test Parameters
+Specifying Test Parameters
+--------------------------
 
-  Your TestNG test can accept parameters with the <<<...@Parameters>>> annotation.  You can also pass parameters from Maven
-  into your TestNG test, by specifying them as system properties, like this:
+Your TestNG test can accept parameters with the `@Parameters` annotation. You can also pass parameters from Maven into your TestNG test, by specifying them as system properties, like this:
 
-+---+
+```xml
 <plugins>
     [...]
       <plugin>
@@ -103,16 +96,16 @@ Using TestNG
       </plugin>
     [...]
 </plugins>
-+---+
+```
 
-  For more information about setting system properties in ${thisPlugin} tests, see {{{./system-properties.html}System Properties}}.
+For more information about setting system properties in ${thisPlugin} tests, see [System Properties](./system-properties.html).
 
-* Using Groups
+Using Groups
+------------
 
-  TestNG allows you to group your tests. You can then execute one or more specific groups. To do this with ${thisPlugin},
-  use the <<<groups>>> parameter, for example:
+TestNG allows you to group your tests. You can then execute one or more specific groups. To do this with ${thisPlugin}, use the `groups` parameter, for example:
 
-+---+
+```xml
 <plugins>
     [...]
       <plugin>
@@ -125,17 +118,16 @@ Using TestNG
       </plugin>
     [...]
 </plugins>
-+---+
+```
 
-  Likewise, the <<<excludedGroups>>> parameter can be used to run all but a certain set of groups.
+Likewise, the `excludedGroups` parameter can be used to run all but a certain set of groups.
 
-* Running Tests in Parallel
+Running Tests in Parallel
+-------------------------
 
-  TestNG allows you to run your tests in parallel, including JUnit tests. To do this, you must set the
-  <<<parallel>>> parameter, and may change the <<<threadCount>>> parameter if the default of 5 is not sufficient.
-  For example:
+TestNG allows you to run your tests in parallel, including JUnit tests. To do this, you must set the `parallel` parameter, and may change the `threadCount` parameter if the default of 5 is not sufficient. For example:
 
-+---+
+```xml
 <plugins>
     [...]
       <plugin>
@@ -149,12 +141,11 @@ Using TestNG
       </plugin>
     [...]
 </plugins>
-+---+
+```
+
+This is particularly useful for slow tests that can have high concurrency, or to quickly and roughly assess the independence and thread safety of your tests and code.
 
-  This is particularly useful for slow tests that can have high concurrency, or to quickly and roughly assess the independence
-  and thread safety of your tests and code.
-    
-+---+
+```xml
 <plugins>
     [...]
       <plugin>
@@ -176,11 +167,11 @@ Using TestNG
       </plugin>
     [...]
 </plugins>
-+---+
-  
-  You can run suites in parallel.
-  
-+---+
+```
+
+You can run suites in parallel.
+
+```xml
 <plugins>
     [...]
       <plugin>
@@ -202,17 +193,16 @@ Using TestNG
       </plugin>
     [...]
 </plugins>
-+---+
+```
 
-  See also {{{./fork-options-and-parallel-execution.html}Fork Options and Parallel Test Execution}}.
+See also [Fork Options and Parallel Test Execution](./fork-options-and-parallel-execution.html).
 
-* Using Custom Listeners and Reporters
+Using Custom Listeners and Reporters
+------------------------------------
 
-  TestNG provides support for attaching custom listeners, reporters, annotation transformers and method interceptors to your tests.
-  By default, TestNG attaches a few basic listeners to generate HTML and XML reports.
-  You can configure multiple custom listeners like this:
+TestNG provides support for attaching custom listeners, reporters, annotation transformers and method interceptors to your tests. By default, TestNG attaches a few basic listeners to generate HTML and XML reports. You can configure multiple custom listeners like this:
 
-+---+
+```xml
 <dependencies>
 [...]
   <dependency>
@@ -249,23 +239,18 @@ Using TestNG
       </plugin>
     [...]
 </plugins>
-+---+
+```
+
+For more information on TestNG, see the [TestNG web site](https://testng.org).
 
-  For more information on TestNG, see the {{{https://testng.org}TestNG web site}}.
+You can implement TestNG listener interface `org.testng.ITestListener` in a separate test artifact `your-testng-listener-artifact` with scope=test, or in project test source code `src/test/java`. You can filter test artifacts by the parameter `dependenciesToScan` to load its classes in current ClassLoader of surefire-testng provider. The TestNG reporter class should implement `org.testng.IReporter`.
 
-  You can implement TestNG listener interface <<<org.testng.ITestListener>>> in
-  a separate test artifact <<<your-testng-listener-artifact>>> with scope=test, or in project test source code
-  <<<src/test/java>>>. You can filter test artifacts by the parameter <<<dependenciesToScan>>> to load its classes
-  in current ClassLoader of surefire-testng provider. The TestNG reporter class should implement <<<org.testng.IReporter>>>.
+The level of verbosity
+----------------------
 
-* The level of verbosity
+The verbosity level can be configured in provider property `surefire.testng.verbose`. The verbosity level is between 0 and 10 where 10 is the most detailed. You can specify -1 and this will put TestNG in debug mode (no longer slicing off stack traces and all). The default level is 0.
 
-  The verbosity level can be configured in provider property
-  <<<surefire.testng.verbose>>>. The verbosity level is between 0 and 10 where 10 is the most detailed.
-  You can specify -1 and this will put TestNG in debug mode (no longer slicing off stack traces and all).
-  The default level is 0.
-  
-+---+
+```xml
 <plugins>
     [...]
       <plugin>
@@ -285,15 +270,14 @@ Using TestNG
       </plugin>
     [...]
 </plugins>
-+---+
+```
+
+Customizing TestNG Object Factory
+---------------------------------
 
-* Customizing TestNG Object Factory
+Since the plugin version 2.19 and TestNG 5.7 or higher you can customize TestNG object factory by implementing `org.testng.IObjectFactory` and binding the class name to the key `objectfactory` in provider properties:
 
-  Since the plugin version 2.19 and TestNG 5.7 or higher you can customize
-  TestNG object factory by implementing <<<org.testng.IObjectFactory>>> and
-  binding the class name to the key <<<objectfactory>>> in provider properties:
-  
-+---+
+```xml
 <plugins>
     [...]
       <plugin>
@@ -313,15 +297,14 @@ Using TestNG
       </plugin>
     [...]
 </plugins>
-+---+
+```
 
-* Customizing TestNG Test Runner Factory
+Customizing TestNG Test Runner Factory
+--------------------------------------
 
-  You can customize the
-  TestNG runner factory by implementing <<<org.testng.ITestRunnerFactory>>> and
-  binding the class name to the key <<<testrunfactory>>> in provider properties:
-  
-+---+
+You can customize the TestNG runner factory by implementing `org.testng.ITestRunnerFactory` and binding the class name to the key `testrunfactory` in provider properties:
+
+```xml
 <plugins>
     [...]
       <plugin>
@@ -341,15 +324,14 @@ Using TestNG
       </plugin>
     [...]
 </plugins>
-+---+
+```
+
+Running &#39;testnames&#39; in test tag
+-------------------------------------
 
-* Running 'testnames' in test tag
+Only tests defined in a `test` tag matching one of these names will be run. In this example two tests run out of 7; namely _InstallTest_ and _ATest_. The test _a-t3_ does not match any test in _suite.xml_.
 
-  Only tests defined in a <<<test>>> tag matching one of these names will be run.
-  In this example two tests run out of 7; namely <InstallTest> and <ATest>.
-  The test <a-t3> does not match any test in <suite.xml>.
-  
-+---+
+```xml
 <plugins>
     [...]
       <plugin>
@@ -372,12 +354,11 @@ Using TestNG
       </plugin>
     [...]
 </plugins>
-+---+
-
+```
 
-  The test suite 'suite.xml' :
+The test suite 'suite.xml' :
 
-+---+
+```xml
 <!DOCTYPE suite SYSTEM "http://testng.org/testng-1.0.dtd" >
 <suite name="Component Tests" verbose="2" annotations="JDK">
   <test name="a-t1" preserve-order="true" >
@@ -396,15 +377,14 @@ Using TestNG
     </classes>
   </test>
 </suite>
-+---+
+```
 
+Running TestNG and JUnit Tests
+------------------------------
 
-* Running TestNG and JUnit Tests
+To run TestNG and JUnit 4.x in the current Maven project, you need both TestNG and JUnit dependencies in the POM:
 
-  To run TestNG and JUnit 4.x in the current Maven project, you need
-  both TestNG and JUnit dependencies in the POM:
-
-+---+
+```xml
 <dependencies>
   [...]
   <dependency>
@@ -421,12 +401,11 @@ Using TestNG
   </dependency>
   [...]
 </dependencies>
-+---+
+```
 
-  You may want to run two providers, e.g. <<<surefire-junit47>>> and <<<surefire-testng>>>, and avoid running JUnit
-  tests within <<<surefire-testng>>> provider by setting property <<<junit=false>>> (note that this property is not applicable if you configure the <<<suiteXmlFiles>>> parameter).
+You may want to run two providers, e.g. `surefire-junit47` and `surefire-testng`, and avoid running JUnit tests within `surefire-testng` provider by setting property `junit=false` (note that this property is not applicable if you configure the `suiteXmlFiles` parameter).
 
-+---+
+```xml
 <plugins>
     [...]
       <plugin>
@@ -459,6 +438,4 @@ Using TestNG
       </plugin>
     [...]
 </plugins>
-+---+
-
-
+```
diff --git a/maven-surefire-plugin/src/site/markdown/examples/toolchains.md.vm b/maven-surefire-plugin/src/site/markdown/examples/toolchains.md.vm
index 592bf503a..55467105a 100644
--- a/maven-surefire-plugin/src/site/markdown/examples/toolchains.md.vm
+++ b/maven-surefire-plugin/src/site/markdown/examples/toolchains.md.vm
@@ -1,48 +1,41 @@
- ------
- Using Maven Toolchains
- ------
- Akom <akom>
- ------
- 2020-04-17
- ------
+---
+title: Using Maven Toolchains
+author:
+  - Akom akom
+date: 2020-04-17
+---
 
-~~ 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
 
-    For general information about Maven Toolchains, see
-    {{{https://maven.apache.org/guides/mini/guide-using-toolchains.html}Guide to Using Toolchains}}
+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.
+-->
 
+For general information about Maven Toolchains, see [Guide to Using Toolchains](https://maven.apache.org/guides/mini/guide-using-toolchains.html)
 
-Using Maven Toolchains with ${thisPlugin}
+# Using Maven Toolchains with ${thisPlugin}
 
-    By default, if the pom configures the toolchains plugin as specified in the aforementioned
-    guide, ${thisPlugin} will launch the test jvm using the main toolchain
-    configured in Maven.
+By default, if the pom configures the toolchains plugin as specified in the aforementioned guide, ${thisPlugin} will launch the test jvm using the main toolchain configured in Maven.
 
-    In some cases, it may be desirable to compile and test using different jvms.
-    While the <<<jvm>>> option can achieve this, it requires hardcoding system-specific paths.
-    Configuration option <<<jdkToolchain>>> can be used to supply an alternate toolchain specification.
+In some cases, it may be desirable to compile and test using different jvms. While the `jvm` option can achieve this, it requires hardcoding system-specific paths. Configuration option `jdkToolchain` can be used to supply an alternate toolchain specification.
 
-* Configuring a different jvm for running tests using toolchains
+Configuring a different jvm for running tests using toolchains
+--------------------------------------------------------------
 
-+---+
+```xml
 <configuration>
     [...]
     <jdkToolchain>
@@ -51,39 +44,37 @@ Using Maven Toolchains with ${thisPlugin}
     </jdkToolchain>
     [...]
 </configuration>
-+---+
+```
 
-     The above example assumes that your `toolchains.xml` contains a valid entry with these values.
+The above example assumes that your \`toolchains.xml\` contains a valid entry with these values.
 
-* Minimum Java Version for Toolchains
+Minimum Java Version for Toolchains
+-----------------------------------
 
-    The minimum version of Java that can be used as a toolchain is limited by the Surefire Booter requirement.
+The minimum version of Java that can be used as a toolchain is limited by the Surefire Booter requirement.
 
-*---------------------+-----------------------+---------------------+
-|| Surefire Version   || Minimum Java Version || Class File Version |
-*---------------------+-----------------------+---------------------+
-| 3.0.0-M6 or higher  |    Java 8             |    52               |
-*---------------------+-----------------------+---------------------+
-| 3.0.0-M5 and lower  |    Java 7             |    51               |
-*---------------------+-----------------------+---------------------+
-| lower than 3.0.0-M1 |    Java 6             |    50               |
-*---------------------+-----------------------+---------------------+
+<table class="table table-bordered table-striped">
+<tr><th>Surefire Version</th><th>Minimum Java Version</th><th>Class File Version</th></tr>
+<tr><td style="text-align: left;">3.0.0-M6 or higher</td><td style="text-align: left;">Java 8</td><td style="text-align: left;">52</td></tr>
+<tr><td style="text-align: left;">3.0.0-M5 and lower</td><td style="text-align: left;">Java 7</td><td style="text-align: left;">51</td></tr>
+<tr><td style="text-align: left;">lower than 3.0.0-M1</td><td style="text-align: left;">Java 6</td><td style="text-align: left;">50</td></tr>
+</table>
 
-    If you try to use a version older than the minimum supported version, you should face something like:
+If you try to use a version older than the minimum supported version, you should face something like:
 
----
+```
 Exception in thread "main" java.lang.UnsupportedClassVersionError: org/apache/maven/surefire/booter/ForkedBooter: Unsupported major.minor version 52.0
-	at java.lang.ClassLoader.defineClass1(Native Method)
-	at java.lang.ClassLoader.defineClass(ClassLoader.java:800)
-	at java.security.SecureClassLoader.defineClass(SecureClassLoader.java:142)
-	at java.net.URLClassLoader.defineClass(URLClassLoader.java:449)
-	at java.net.URLClassLoader.access${esc.d}100(URLClassLoader.java:71)
-	at java.net.URLClassLoader${esc.d}1.run(URLClassLoader.java:361)
-	at java.net.URLClassLoader${esc.d}1.run(URLClassLoader.java:355)
-	at java.security.AccessController.doPrivileged(Native Method)
-	at java.net.URLClassLoader.findClass(URLClassLoader.java:354)
-	at java.lang.ClassLoader.loadClass(ClassLoader.java:425)
-	at sun.misc.Launcher${esc.d}AppClassLoader.loadClass(Launcher.java:308)
-	at java.lang.ClassLoader.loadClass(ClassLoader.java:358)
-	at sun.launcher.LauncherHelper.checkAndLoadMain(LauncherHelper.java:482)
----
\ No newline at end of file
+        at java.lang.ClassLoader.defineClass1(Native Method)
+        at java.lang.ClassLoader.defineClass(ClassLoader.java:800)
+        at java.security.SecureClassLoader.defineClass(SecureClassLoader.java:142)
+        at java.net.URLClassLoader.defineClass(URLClassLoader.java:449)
+        at java.net.URLClassLoader.access${esc.d}100(URLClassLoader.java:71)
+        at java.net.URLClassLoader${esc.d}1.run(URLClassLoader.java:361)
+        at java.net.URLClassLoader${esc.d}1.run(URLClassLoader.java:355)
+        at java.security.AccessController.doPrivileged(Native Method)
+        at java.net.URLClassLoader.findClass(URLClassLoader.java:354)
+        at java.lang.ClassLoader.loadClass(ClassLoader.java:425)
+        at sun.misc.Launcher${esc.d}AppClassLoader.loadClass(Launcher.java:308)
+        at java.lang.ClassLoader.loadClass(ClassLoader.java:358)
+        at sun.launcher.LauncherHelper.checkAndLoadMain(LauncherHelper.java:482)
+```
diff --git a/maven-surefire-plugin/src/site/markdown/featurematrix.md b/maven-surefire-plugin/src/site/markdown/featurematrix.md
index 11123f70e..18c6ad9f8 100644
--- a/maven-surefire-plugin/src/site/markdown/featurematrix.md
+++ b/maven-surefire-plugin/src/site/markdown/featurematrix.md
@@ -1,68 +1,51 @@
-  ------
-  Feature Matrix
-  ------
+---
+title: Feature Matrix
+---
+
+<!-- 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-->
+# Feature Matrix
+
+Not all features are supported for all test frameworks, and the following table gives a brief overview of support status:
+
+<table class="table table-bordered table-striped">
+<tr><th><b>Feature</b></th><th><b>JUnit3</b></th><th><b>JUnit4</b></th><th><b>JUnit47</b></th><th><b>TestNG</b></th><th><b>POJO</b></th><th><b>JUnit 5 Platform</b></th></tr>
+<tr><td style="text-align: left;">groups/category/tags support</td><td style="text-align: left;">N</td><td style="text-align: left;">N</td><td style="text-align: left;">Y</td><td style="text-align: left;">Y</td><td style="text-align: left;">N</td><td style="text-align: left;">Y</td></tr>
+<tr><td style="text-align: left;">security manager support</td><td style="text-align: left;">Y</td><td style="text-align: left;">N</td><td style="text-align: left;">N</td><td style="text-align: left;">N</td><td style="text-align: left;">N</td><td style="text-align: left;">N</td></tr>
+<tr><td style="text-align: left;">runOrder support</td><td style="text-align: left;">Y</td><td style="text-align: left;">Y</td><td style="text-align: left;">Y</td><td style="text-align: left;">?</td><td style="text-align: left;">Y</td><td style="text-align: left;">Y</td></tr>
+<tr><td style="text-align: left;">run &gt;1 individual test method in a class</td><td style="text-align: left;">N</td><td style="text-align: left;">Y</td><td style="text-align: left;">Y</td><td style="text-align: left;">Y</td><td style="text-align: left;">N</td><td style="text-align: left;">?(*1)</td></tr>
+<tr><td style="text-align: left;">parallel support</td><td style="text-align: left;">N</td><td style="text-align: left;">N</td><td style="text-align: left;">Y</td><td style="text-align: left;">Y</td><td style="text-align: left;">N</td><td style="text-align: left;">N(*2)</td></tr>
+<tr><td style="text-align: left;">custom run-listener</td><td style="text-align: left;">N</td><td style="text-align: left;">Y</td><td style="text-align: left;">Y</td><td style="text-align: left;">Y</td><td style="text-align: left;">-</td><td style="text-align: left;">N</td></tr>
+<tr><td style="text-align: left;">re-run count</td><td style="text-align: left;">N</td><td style="text-align: left;">Y</td><td style="text-align: left;">Y</td><td style="text-align: left;">N</td><td style="text-align: left;">N</td><td style="text-align: left;">Y(*3)</td></tr>
+<tr><td style="text-align: left;">skip after failure count</td><td style="text-align: left;">N</td><td style="text-align: left;">Y</td><td style="text-align: left;">Y</td><td style="text-align: left;">Y</td><td style="text-align: left;">N</td><td style="text-align: left;">N</td></tr>
+<tr><td style="text-align: left;">Surefire Extensions</td><td style="text-align: left;">Y</td><td style="text-align: left;">Y</td><td style="text-align: left;">Y</td><td style="text-align: left;">Y</td><td style="text-align: left;">Y</td><td style="text-align: left;">Y(*4)</td></tr>
+</table>
+
+Legend: &quot;Y&quot; means supported, &quot;N&quot; means not supported. &quot;?&quot; means not tested.
+
+If you would like to implement support for a given provider with an &quot;N&quot; or a &quot;?&quot; \(or create tests for it\), you should create a patch and mark the issue as an improvement. If there is something wrong with an implementation marked with &quot;Y&quot; that is considered a bug.
+
+\(*1\) The JUnit 5 Platform supports running multiple individual test methods in a single class, but there are some corner cases that are not supported, yet: [junit-team/junit5#1343](https://github.com/junit-team/junit5/issues/1343) and [junit-team/junit5#1406\)](https://github.com/junit-team/junit5/issues/1406).
+
+\(*2\) The test are executed in parallel but the report supports only a sequence of test events, see the issue [SUREFIRE-1795](https://issues.apache.org/jira/browse/SUREFIRE-1795).
+
+\(*3\) Since 3\.0\.0-M4
+
+\(*4\) 3 extensions related to JUnit5 annotation `DisplayName`.
 
-~~ 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
-
-Feature Matrix
-
-    Not all features are supported for all test frameworks, and the following table gives a brief overview
-    of support status:
-
-*---------------------------------------------+-----------+-----------+------------+-----------+----------+----------------------+
-|| <<Feature>>                                ||<<JUnit3>>||<<JUnit4>>||<<JUnit47>>||<<TestNG>>||<<POJO>> ||<<JUnit 5 Platform>> |
-*---------------------------------------------+------------+----------+------------+-----------+----------+----------------------+
-| groups/category/tags support                |     N      |    N     |      Y     |    Y      |  N       |  Y                   |
-*---------------------------------------------+------------+----------+------------+-----------+----------+----------------------+
-| security manager support                    |     Y      |    N     |      N     |    N      |  N       |  N                   |
-*---------------------------------------------+------------+----------+------------+-----------+----------+----------------------+
-| runOrder support                            |     Y      |    Y     |      Y     |    ?      |  Y       |  Y                   |
-*---------------------------------------------+------------+----------+------------+-----------+----------+----------------------+
-| run >1 individual test method in a class    |     N      |    Y     |      Y     |    Y      |  N       |  ?(*1)               |
-*---------------------------------------------+------------+----------+------------+-----------+----------+----------------------+
-| parallel support                            |     N      |    N     |      Y     |    Y      |  N       |  N(*2)               |
-*---------------------------------------------+------------+----------+------------+-----------+----------+----------------------+
-| custom run-listener                         |     N      |    Y     |      Y     |    Y      |  -       |  N                   |
-*---------------------------------------------+------------+----------+------------+-----------+----------+----------------------+
-| re-run count                                |     N      |    Y     |      Y     |    N      |  N       |  Y(*3)               |
-*---------------------------------------------+------------+----------+------------+-----------+----------+----------------------+
-| skip after failure count                    |     N      |    Y     |      Y     |    Y      |  N       |  N                   |
-*---------------------------------------------+------------+----------+------------+-----------+----------+----------------------+
-| Surefire Extensions                         |     Y      |    Y     |      Y     |    Y      |  Y       |  Y(*4)               |
-*---------------------------------------------+------------+----------+------------+-----------+----------+----------------------+
-
-
-    Legend: "Y" means supported, "N" means not supported. "?" means not tested.
-
-    If you would like to implement support for
-    a given provider with an "N" or a "?" (or create tests for it), you should create a patch and mark the issue as an
-    improvement. If there is something wrong with an implementation marked with "Y" that is considered a bug.
-
-   (*1) The JUnit 5 Platform supports running multiple individual test methods in a single class, but there are some
-   corner cases that are not supported, yet: {{{https://github.com/junit-team/junit5/issues/1343}junit-team/junit5#1343}}
-   and {{{https://github.com/junit-team/junit5/issues/1406}junit-team/junit5#1406)}}.
-
-   (*2) The test are executed in parallel but the report supports only a sequence of test events, see the issue
-   {{{https://issues.apache.org/jira/browse/SUREFIRE-1795}SUREFIRE-1795}}.
-
-   (*3) Since 3.0.0-M4
-
-   (*4) 3 extensions related to JUnit5 annotation <<<DisplayName>>>.
diff --git a/maven-surefire-plugin/src/site/markdown/history.md.vm b/maven-surefire-plugin/src/site/markdown/history.md.vm
index 85381a317..80d4c5c3c 100644
--- a/maven-surefire-plugin/src/site/markdown/history.md.vm
+++ b/maven-surefire-plugin/src/site/markdown/history.md.vm
@@ -1,90 +1,41 @@
-  ------
-  History
-  ------
-  Stephen Connolly
-  Allan Ramirez
-  ------
-  2011-06-27
-  ------
-  
-~~ 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: History
+author:
+  - Stephen Connolly
+  - Allan Ramirez
+date: 2011-06-27
+---
 
-~~ 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 ${thisPlugin} Plugin
+  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.
+-->
 
- This is the history of features of the plugin.
+# Maven ${thisPlugin} Plugin
 
-*---------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-||Versions                                    ||Release Targets                                                                                                                                                                   \ |
-*---------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-|                                             | Maven API 3.0 and Java 1.7                                                                                                                                                        \ |
-|                                             |                                                                                                                                                                                   \ |
-|                                             | {{{https://issues.apache.org/jira/browse/SUREFIRE-1493}Maven Plugin API 3.0}}                                                                                                     \ |
-| 3.0.0-M1                                    | {{{https://issues.apache.org/jira/browse/SUREFIRE-1474}Java 1.7 as minimum}}                                                                                                      \ |
-|                                             | {{{https://issues.apache.org/jira/browse/SUREFIRE-1212}@Component is deprecated. @Parameter should be used instead}}                                                              \ |
-|                                             | {{{https://issues.apache.org/jira/browse/SUREFIRE-1588}Surefire manifest jar classloading broken on latest Debian/Ubuntu Java8}}                                                  \ |
-|                                             | {{{https://issues.apache.org/jira/projects/SUREFIRE/versions/12342871}See the Release Notes for the version 3.0.0-M1}}                                                            \ |
-*---------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-|                                             | Fixed: JDK9 and Windows Class-Path issues, 3.0 and Legacy Report XSD, 3.0.0-M2 shadefire                                                                                          \ |
-|                                             |                                                                                                                                                                                   \ |
-|                                             | {{{https://issues.apache.org/jira/browse/SUREFIRE-1568}Fixed JDK9+ (Jigsaw) modular paths (module-info.java) having white spaces on file system}}                                 \ |
-|                                             | {{{https://issues.apache.org/jira/browse/SUREFIRE-1593}Windows slashes appear in relative paths of Class-Path in MANIFEST.MF (Boot Manifest-JAR)}}                                \ |
-|                                             | {{{https://issues.apache.org/jira/browse/SUREFIRE-1602}Surefire fails loading class ForkedBooter when using a sub-directory pom file}}                                            \ |
-|                                             | {{{https://issues.apache.org/jira/browse/SUREFIRE-1605}Plugin fails if used Toolchains together with JDK9+ and (Jigsaw) modular paths (module-info.java)}}                        \ |
-| 3.0.0-M2                                    | {{{https://issues.apache.org/jira/browse/SUREFIRE-1590}3.0 and Legacy Report XSD}}                                                                                                \ |
-|                                             | {{{https://issues.apache.org/jira/browse/SUREFIRE-1600}3.0.0-M2 shadefire}}                                                                                                       \ |
-|                                             |                                                                                                                                                                                   \ |
-|                                             | Feature: Option to switch-off Java 9 modules                                                                                                                                      \ |
-|                                             |                                                                                                                                                                                   \ |
-|                                             | {{{https://issues.apache.org/jira/browse/SUREFIRE-1531}Option to switch-off Java 9 modules}}                                                                                      \ |
-|                                             |                                                                                                                                                                                   \ |
-|                                             | {{{https://issues.apache.org/jira/projects/SUREFIRE/versions/12344396}See the Release Notes for the version 3.0.0-M2}}                                                            \ |
-*---------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-|                                             | Fixed: maven-surefire-report-plugin supports JDK11, JUnit5 issues, deprecated skipTests in Failsafe plugin, used ShadeFire 3.0.0-M2                                               \ |
-|                                             |                                                                                                                                                                                   \ |
-|                                             | {{{https://issues.apache.org/jira/browse/SUREFIRE-1613}maven-surefire-report-plugin fails on JDK 11}}                                                                             \ |
-| 3.0.0-M3                                    | {{{https://issues.apache.org/jira/browse/SUREFIRE-1614}JUnit Runner that writes to System.out corrupts Surefire's STDOUT when using JUnit's Vintage Engine}}                      \ |
-|                                             | {{{https://issues.apache.org/jira/browse/SUREFIRE-1616}Smart stacktrace in test summary should not print JUnit5 assertion exception type}}                                        \ |
-|                                             | {{{https://issues.apache.org/jira/browse/SUREFIRE-1611}Deprecate skipTests in Failsafe Plugin}}                                                                                   \ |
-|                                             | {{{https://issues.apache.org/jira/projects/SUREFIRE/versions/12342872}See the Release Notes for the version 3.0.0-M3}}                                                            \ |
-*---------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-|                                             | Provided 3 extensions of reporters which can be used to customize XML report, console and file reporters. It is very useful for JUnit5 users.                                     \ |
-|                                             | The internal implementation was reworked so that new commands and events can be easily added. The impl is located in a center point and it is a prerequisite in next versions.    \ |
-| 3.0.0-M4                                    | Provided bug fixes for Docker Alpine/BusyBox Linux, JUnit5 and 43 more.                                                                                                           \ |
-|                                             |                                                                                                                                                                                   \ |
-|                                             | {{{https://issues.apache.org/jira/browse/SUREFIRE-1222}ForkClient attempts to consume unrelated lines}}                                                                           \ |
-*---------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-|                                             | Test Report tasks (prerequisite: SUREFIRE-1222 in 3.0.0-M4)                                                                                                                       \ |
-|                                             | New interprocess communication with TCP/IP which fixed current blocker and critical bugs.                                                                                         \ |
-| 3.0.0-M5                                    | Provided extensions which can be used to customize this interprocess communication in plugin configuration. It is internally used to switch over the pipes and TCP connector.     \ |
-|                                             |                                                                                                                                                                                   \ |
-|                                             | {{{https://issues.apache.org/jira/browse/SUREFIRE-1658}TCP/IP Channel for forked Surefire JVM. Extensions API and SPI. Polymorphism for remote and local process communication.}} \ |
-*---------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| 3.0.0-M6                                    | ReportEntry contains new fields testRunId:long and RunMode which help identifying the tests and logs. The plugin supports Java 1.8 and Maven Plugin API 3.2.5. Many bug fixes.    \ |
-|                                             | {{{https://issues.apache.org/jira/issues/?jql=project%20%3D%20SUREFIRE%20AND%20fixVersion%20%3D%203.0.0-M6%20ORDER%20BY%20priority%20DESC%2C%20key}ASF Release versions}}         \ |
-*---------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| 3.0.0-M7                                    | SurefireProvider interface, TestSetRunListener, StatelessXmlReporter, and related code will be reworked. Currently, Java classes are executed as tests and we will support more.  \ |
-|                                             | {{{https://issues.apache.org/jira/issues/?jql=project%20%3D%20SUREFIRE%20AND%20fixVersion%20%3D%203.0.0-M7%20ORDER%20BY%20priority%20DESC%2C%20key}ASF Release versions}}         \ |
-*---------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| 3.0.0                                       | Breaking backwards compatibility with system properties in configuration parameters, removing deprecated configuration parameters and removing deprecated code, etc.              \ |
-|                                             | {{{https://issues.apache.org/jira/issues/?jql=project%20%3D%20SUREFIRE%20AND%20fixVersion%20%3D%203.0%20ORDER%20BY%20priority%20DESC%2C%20key}ASF Release versions}}              \ |
-*---------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+This is the history of features of the plugin.
+
+|Versions|Release Targets  |
+|:---|:---|
+|3\.0.0-M1|Maven API 3.0 and Java 1.7  <br /> <br />[Maven Plugin API 3.0](https://issues.apache.org/jira/browse/SUREFIRE-1493)  <br />[Java 1.7 as minimum](https://issues.apache.org/jira/browse/SUREFIRE-1474)  <br />[@Component is deprecated. @Parameter should be used instead](https://issues.apache.org/jira/browse/SUREFIRE-1212)  <br />[Surefire manifest jar classloading broken on latest Debian/Ubuntu Java8](https://issues.apache.org/jira/browse/SUREFIRE-1588)  <br />[See the Release No [...]
+|3\.0.0-M2|Fixed: JDK9 and Windows Class-Path issues, 3.0 and Legacy Report XSD, 3.0.0-M2 shadefire  <br /> <br />[Fixed JDK9+ (Jigsaw) modular paths (module-info.java) having white spaces on file system](https://issues.apache.org/jira/browse/SUREFIRE-1568)  <br />[Windows slashes appear in relative paths of Class-Path in MANIFEST.MF (Boot Manifest-JAR)](https://issues.apache.org/jira/browse/SUREFIRE-1593)  <br />[Surefire fails loading class ForkedBooter when using a sub-directory pom f [...]
+|3\.0.0-M3|Fixed: maven-surefire-report-plugin supports JDK11, JUnit5 issues, deprecated skipTests in Failsafe plugin, used ShadeFire 3.0.0-M2  <br /> <br />[maven-surefire-report-plugin fails on JDK 11](https://issues.apache.org/jira/browse/SUREFIRE-1613)  <br />[JUnit Runner that writes to System.out corrupts Surefire's STDOUT when using JUnit's Vintage Engine](https://issues.apache.org/jira/browse/SUREFIRE-1614)  <br />[Smart stacktrace in test summary should not print JUnit5 assertio [...]
+|3\.0.0-M4|Provided 3 extensions of reporters which can be used to customize XML report, console and file reporters. It is very useful for JUnit5 users.  <br />The internal implementation was reworked so that new commands and events can be easily added. The impl is located in a center point and it is a prerequisite in next versions.  <br />Provided bug fixes for Docker Alpine/BusyBox Linux, JUnit5 and 43 more.  <br /> <br />[ForkClient attempts to consume unrelated lines](https://issues. [...]
+|3\.0.0-M5|Test Report tasks (prerequisite: SUREFIRE-1222 in 3.0.0-M4)  <br />New interprocess communication with TCP/IP which fixed current blocker and critical bugs.  <br />Provided extensions which can be used to customize this interprocess communication in plugin configuration. It is internally used to switch over the pipes and TCP connector.  <br /> <br />[TCP/IP Channel for forked Surefire JVM. Extensions API and SPI. Polymorphism for remote and local process communication.](https: [...]
+|3\.0.0-M6|ReportEntry contains new fields testRunId:long and RunMode which help identifying the tests and logs. The plugin supports Java 1.8 and Maven Plugin API 3.2.5. Many bug fixes.  <br />[ASF Release versions](https://issues.apache.org/jira/issues/?jql=project%20%3D%20SUREFIRE%20AND%20fixVersion%20%3D%203.0.0-M6%20ORDER%20BY%20priority%20DESC%2C%20key)  |
+|3\.0.0-M7|SurefireProvider interface, TestSetRunListener, StatelessXmlReporter, and related code will be reworked. Currently, Java classes are executed as tests and we will support more.  <br />[ASF Release versions](https://issues.apache.org/jira/issues/?jql=project%20%3D%20SUREFIRE%20AND%20fixVersion%20%3D%203.0.0-M7%20ORDER%20BY%20priority%20DESC%2C%20key)  |
+|3\.0.0|Breaking backwards compatibility with system properties in configuration parameters, removing deprecated configuration parameters and removing deprecated code, etc.  <br />[ASF Release versions](https://issues.apache.org/jira/issues/?jql=project%20%3D%20SUREFIRE%20AND%20fixVersion%20%3D%203.0%20ORDER%20BY%20priority%20DESC%2C%20key)  |
diff --git a/maven-surefire-plugin/src/site/markdown/index.md.vm b/maven-surefire-plugin/src/site/markdown/index.md.vm
index 6217ebfe3..e33b60a8a 100644
--- a/maven-surefire-plugin/src/site/markdown/index.md.vm
+++ b/maven-surefire-plugin/src/site/markdown/index.md.vm
@@ -1,174 +1,116 @@
-  ------
-  Introduction
-  ------
-  Stephen Connolly
-  Allan Ramirez
-  ------
-  2011-06-27
-  ------
-
-~~ 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
-
-
-Maven ${thisPlugin} Plugin
+---
+title: Introduction
+author:
+  - Stephen Connolly
+  - Allan Ramirez
+date: 2011-06-27
+---
+
+<!--
+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.
+-->
+
+# Maven ${thisPlugin} Plugin
 
 #{if}(${project.artifactId}=="maven-surefire-plugin")
-  The Surefire Plugin is used during the <<<test>>> phase of the build
-  lifecycle to execute the unit tests of an application. It generates reports
-  in two different file formats:
+The Surefire Plugin is used during the `test` phase of the build lifecycle to execute the unit tests of an application. It generates reports in two different file formats:
 #{else}
-  The Failsafe Plugin is designed to run integration tests while the Surefire Plugin is designed to run unit tests.
-  The name (failsafe) was chosen both because it is a synonym of surefire and because it implies that when it fails, it
-  does so in a safe way.
+The Failsafe Plugin is designed to run integration tests while the Surefire Plugin is designed to run unit tests. The name (failsafe) was chosen both because it is a synonym of surefire and because it implies that when it fails, it does so in a safe way.
 
-  The Maven lifecycle has four phases for running integration tests:
+The Maven lifecycle has four phases for running integration tests:
 
-  * <<<pre-integration-test>>> for setting up the integration test environment.
+- `pre-integration-test` for setting up the integration test environment.
+- `integration-test` for running the integration tests.
+- `post-integration-test` for tearing down the integration test environment.
+- `verify` for checking the results of the integration tests.
 
-  * <<<integration-test>>> for running the integration tests.
+If you use the Surefire Plugin for running tests, then when you have a test failure, the build will stop at the `integration-test` phase and your integration test environment will not have been torn down correctly.
 
-  * <<<post-integration-test>>> for tearing down the integration test environment.
+The Failsafe Plugin is used during the `integration-test` and `verify` phases of the build lifecycle to execute the integration tests of an application. The Failsafe Plugin will not fail the build during the `integration-test` phase, thus enabling the `post-integration-test` phase to execute.
 
-  * <<<verify>>> for checking the results of the integration tests.
+NOTE: when running integration tests, you should invoke Maven with the (shorter to type too)
 
-  []
-
-  If you use the Surefire Plugin for running tests, then when you have a test failure, the build will stop at the
-  <<<integration-test>>> phase and your integration test environment will not have been torn down correctly.
-
-  The Failsafe Plugin is used during the <<<integration-test>>> and <<<verify>>> phases of the build
-  lifecycle to execute the integration tests of an application. The Failsafe Plugin will not fail the build during
-  the <<<integration-test>>> phase, thus enabling the <<<post-integration-test>>> phase to execute.
-
-  NOTE: when running integration tests, you should invoke Maven with the (shorter to type too)
-
-+---+
+```bash
 mvn verify
-+---+
-
-  rather than trying to invoke the <<<integration-test>>> phase directly, as otherwise the <<<post-integration-test>>>
-  phase will not be executed.
+```
 
-  The Failsafe Plugin generates reports in two different file formats:
+rather than trying to invoke the `integration-test` phase directly, as otherwise the `post-integration-test` phase will not be executed.
 
+The Failsafe Plugin generates reports in two different file formats:
 #{end}
 
-  * Plain text files (<<<*.txt>>>)
+- Plain text files (`*.txt`)
+- XML files (`*.xml`)
 
-  * XML files (<<<*.xml>>>)
+By default, these files are generated in `${esc.d}{basedir}/target/${thisPlugin.toLowerCase()}-reports/TEST-*.xml`.
 
-  []
+The schema for the ${thisPlugin} XML reports is available at [${thisPlugin} XML Report Schema](./xsd/${thisPlugin.toLowerCase()}-test-report.xsd).
 
-  By default, these files are generated in <<<$\{basedir\}/target/${thisPlugin.toLowerCase()}-reports/TEST-*.xml>>>.
-
-  The schema for the ${thisPlugin} XML reports is available at
-  {{{./xsd/${thisPlugin.toLowerCase()}-test-report.xsd}${thisPlugin} XML Report Schema}}.
-
-  For an HTML format of the report, please see the
-  {{{http://maven.apache.org/plugins/maven-surefire-report-plugin/}Maven Surefire Report Plugin}}.
+For an HTML format of the report, please see the [Maven Surefire Report Plugin](http://maven.apache.org/plugins/maven-surefire-report-plugin/).
 
 #{if}(${project.artifactId}=="maven-failsafe-plugin")
-  By default this plugin generates summary XML file at <<<$\{basedir\}/target/failsafe-reports/failsafe-summary.xml>>>
-  and the schema is available at {{{./xsd/failsafe-summary.xsd}Failsafe XML Summary Schema}}.
+By default this plugin generates summary XML file at `${esc.d}{basedir}/target/failsafe-reports/failsafe-summary.xml` and the schema is available at [Failsafe XML Summary Schema](./xsd/failsafe-summary.xsd).
 #{end}
 
-* Goals Overview
+Goals Overview
+--------------
 
 #{if}(${project.artifactId}=="maven-surefire-plugin")
-  The Surefire Plugin has only one goal:
-
-  * {{{./test-mojo.html}surefire:test}} runs the unit tests of an application.
-
-  []
+The Surefire Plugin has only one goal:
 
+- [surefire:test](./test-mojo.html) runs the unit tests of an application.
 #{else}
-  The Failsafe Plugin has only two goals:
-
-  * {{{./integration-test-mojo.html}failsafe:integration-test}} runs the integration tests of an application.
-
-  * {{{./verify-mojo.html}failsafe:verify}} verifies that the integration tests of an application passed.
-
-  []
+The Failsafe Plugin has only two goals:
 
+- [failsafe:integration-test](./integration-test-mojo.html) runs the integration tests of an application.
+- [failsafe:verify](./verify-mojo.html) verifies that the integration tests of an application passed.
 #{end}
 
-* Usage
-
-  General instructions on how to use the ${thisPlugin} Plugin can be found on the {{{./usage.html}usage page}}. Some more
-  specific use cases are described in the examples listed below. Additionally, users can contribute to the
-  {{{https://github.com/apache/maven-surefire}GitHub project}}.
-
-  In case you still have questions regarding the plugin's usage, please have a look at the {{{./faq.html}FAQ}} and feel
-  free to contact the {{{./mailing-lists.html}user mailing list}}. The posts to the mailing list are archived and could
-  already contain the answer to your question as part of an older thread. Hence, it is also worth browsing/searching
-  the {{{./mailing-lists.html}mail archive}}.
-
-  If you feel like the plugin is missing a feature or has a defect, you can file a feature request or bug report in our
-  {{{./issue-management.html}issue tracker}}. 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
-  {{{http://maven.apache.org/guides/development/guide-helping.html}guide to helping with Maven}}.
-
-* Examples
-
-  The following examples show how to use the ${thisPlugin} Plugin in more advanced use cases:
-
-  * {{{./examples/testng.html}Using TestNG}}
-
-  * {{{./examples/junit-platform.html}Using JUnit 5 Platform}}
-
-  * {{{./examples/junit.html}Using JUnit}}
-
-  * {{{./examples/pojo-test.html}Using POJO Tests}}
-
-  * {{{./examples/skipping-tests.html}Skipping Tests}}
-
-  * {{{./examples/skip-after-failure.html}Skip After Failure}}
-
-  * {{{./examples/inclusion-exclusion.html}Inclusions and Exclusions of Tests}}
-
-  * {{{./examples/single-test.html}Running a Single Test}}
-
-  * {{{./examples/rerun-failing-tests.html}Re-run Failing Tests}}
-
-  * {{{./examples/class-loading.html}Class Loading and Forking}}
-
-  * {{{./examples/debugging.html}Debugging Tests}}
-
-  * {{{./examples/system-properties.html}Using System Properties}}
-
-  * {{{./examples/configuring-classpath.html}Configuring the Classpath}}
-
-  * {{{./examples/providers.html}Selecting Providers}}
-
-  * {{{./examples/fork-options-and-parallel-execution.html}Fork Options and Parallel Test Execution}}
-
-  * {{{./examples/logging.html}Using Console Logs}}
-
-  * {{{./examples/shutdown.html}Shutdown of Forked JVM}}
-
-  * {{{./java9.html}Run tests with Java 9}}
-
-  * {{{./docker.html}Run tests in Docker}}
-
-  []
+Usage
+-----
+
+General instructions on how to use the ${thisPlugin} Plugin can be found on the [usage page](./usage.html). Some more specific use cases are described in the examples listed below. Additionally, users can contribute to the [GitHub project](https://github.com/apache/maven-surefire).
+
+In case you still have questions regarding the plugin's usage, please have a look at the [FAQ](./faq.html) and feel free to contact the [user mailing list](./mailing-lists.html). The posts to the mailing list are archived and could already contain the answer to your question as part of an older thread. Hence, it is also worth browsing/searching the [mail archive](./mailing-lists.html).
+
+If you feel like the plugin is missing a feature or has a defect, you can file a feature request or bug report in our [issue tracker](./issue-management.html). 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 wel [...]
+
+Examples
+--------
+
+The following examples show how to use the ${thisPlugin} Plugin in more advanced use cases:
+
+- [Using TestNG](./examples/testng.html)
+- [Using JUnit 5 Platform](./examples/junit-platform.html)
+- [Using JUnit](./examples/junit.html)
+- [Using POJO Tests](./examples/pojo-test.html)
+- [Skipping Tests](./examples/skipping-tests.html)
+- [Skip After Failure](./examples/skip-after-failure.html)
+- [Inclusions and Exclusions of Tests](./examples/inclusion-exclusion.html)
+- [Running a Single Test](./examples/single-test.html)
+- [Re-run Failing Tests](./examples/rerun-failing-tests.html)
+- [Class Loading and Forking](./examples/class-loading.html)
+- [Debugging Tests](./examples/debugging.html)
+- [Using System Properties](./examples/system-properties.html)
+- [Configuring the Classpath](./examples/configuring-classpath.html)
+- [Selecting Providers](./examples/providers.html)
+- [Fork Options and Parallel Test Execution](./examples/fork-options-and-parallel-execution.html)
+- [Using Console Logs](./examples/logging.html)
+- [Shutdown of Forked JVM](./examples/shutdown.html)
+- [Run tests with Java 9](./java9.html)
+- [Run tests in Docker](./docker.html)
diff --git a/maven-surefire-plugin/src/site/markdown/usage.md.vm b/maven-surefire-plugin/src/site/markdown/usage.md.vm
index 6b7e70698..2090c34a2 100644
--- a/maven-surefire-plugin/src/site/markdown/usage.md.vm
+++ b/maven-surefire-plugin/src/site/markdown/usage.md.vm
@@ -1,43 +1,44 @@
-  ------
-  Usage
-  ------
-  Brett Porter
-  Allan Ramirez
-  Stephen Connolly
-  ------
-  2011-06-27
-  ------
-  
-~~ 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
-
-Usage
+---
+title: Usage
+author:
+  - Brett Porter
+  - Allan Ramirez
+  - Stephen Connolly
+date: 2011-06-27
+---
+
+<!--
+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.
+-->
+
+# Usage
 
 #{if}(${project.artifactId}=="maven-surefire-plugin")
-  Best practice is to define the version of the Surefire Plugin that you want to use in either your <<<pom.xml>>>
-  or a parent <<<pom.xml>>>:
+Best practice is to define the version of the Surefire Plugin that you want to use in either your `pom.xml` or a parent `pom.xml`:
+#{else}
+To use the ${thisPlugin} Plugin, you need to add the following configuration to your `pom.xml`:
+#{end}
 
-+---+
+```xml
 <project>
   [...]
   <build>
+#{if}(${project.artifactId}=="maven-surefire-plugin")
     <pluginManagement>
       <plugins>
         <plugin>
@@ -47,19 +48,7 @@ Usage
         </plugin>
       </plugins>
     </pluginManagement>
-  </build>
-  [...]
-</project>
-+---+
-
 #{else}
-  To use the ${thisPlugin} Plugin, you need to add the following configuration to
-  your <<<pom.xml>>>:
-
-+---+
-<project>
-  [...]
-  <build>
     <plugins>
       <plugin>
         <groupId>${project.groupId}</groupId>
@@ -75,72 +64,53 @@ Usage
         </executions>
       </plugin>
     </plugins>
+#{end}
   </build>
   [...]
 </project>
-+---+
+```
 
-#{end}
 #{if}(${project.artifactId}=="maven-surefire-plugin")
-  The ${thisPlugin} Plugin can be invoked by calling the <<<test>>> phase of the
-  build lifecycle.
+The ${thisPlugin} Plugin can be invoked by calling the `test` phase of the build lifecycle.
+#{else}
+The ${thisPlugin} Plugin can be invoked by calling the `verify` phase of the build lifecycle.
+#{end}
 
-+---+
+```text
+#{if}(${project.artifactId}=="maven-surefire-plugin")
 mvn test
-+---+
-
 #{else}
-  The ${thisPlugin} Plugin can be invoked by calling the <<<verify>>> phase of the
-  build lifecycle.
-
-+---+
 mvn verify
-+---+
 #{end}
+```
 
-* Using Different Testing Providers
-
-  Tests in your test source directory can be any combination of the following:
-
-   * TestNG
+Using Different Testing Providers
+---------------------------------
 
-   * JUnit (3.8, 4.x or 5.x)
+Tests in your test source directory can be any combination of the following:
 
-   * POJO
+- TestNG
+- JUnit (3.8, 4.x or 5.x)
+- POJO
 
-  Which providers are available is controlled simply by the inclusion of the
-  appropriate dependencies (i.e., <<<junit:junit>>> or <<<junit:junit-dep>>> for JUnit4, <<junit-jupiter-engine>> or
-  <<junit-vintage-engine>> for JUnit5 and <<<org.testng:testng>>> 4.7+ for TestNG). Since this is required to compile the test
-  classes anyway, no additional configuration is required.
+Which providers are available is controlled simply by the inclusion of the appropriate dependencies (i.e., `junit:junit` or `junit:junit-dep` for JUnit4, **junit-jupiter-engine** or **junit-vintage-engine** for JUnit5 and `org.testng:testng` 4.7+ for TestNG). Since this is required to compile the test classes anyway, no additional configuration is required.
 
-  Note that any normal Surefire integration works identically no matter which
-  providers are in use - so you can still produce a Cobertura report and a
-  Surefire results report on your project web site for your TestNG tests,
-  for example.
+Note that any normal Surefire integration works identically no matter which providers are in use - so you can still produce a Cobertura report and a Surefire results report on your project web site for your TestNG tests, for example.
 
-  The POJO provider above allows you to write tests that do not depend on either of
-  JUnit and TestNG. It behaves in the same way, running all <<<test*>>> methods that are
-  public in the class, but the API dependency is not required. To perform
-  assertions, the JDK 1.4 <<<assert>>> keyword can be used.
-  See {{{./examples/pojo-test.html} Using POJO Tests}} for more information.
+The POJO provider above allows you to write tests that do not depend on either of JUnit and TestNG. It behaves in the same way, running all `test*` methods that are public in the class, but the API dependency is not required. To perform assertions, the JDK 1.4 `assert` keyword can be used. See [ Using POJO Tests](./examples/pojo-test.html) for more information.
 
-  All of the providers support the Surefire Plugin parameter configurations.
-  However, there are additional options available if you are running TestNG
-  tests (including if you are using TestNG to execute your JUnit tests, which
-  occurs by default if both are present in Surefire).
+All of the providers support the Surefire Plugin parameter configurations. However, there are additional options available if you are running TestNG tests (including if you are using TestNG to execute your JUnit tests, which occurs by default if both are present in Surefire).
 
-  See {{{./examples/testng.html} Using TestNG}} for more information.
+See [ Using TestNG](./examples/testng.html) for more information.
 
 #{if}(${project.artifactId}=="maven-failsafe-plugin")
-* Using jetty and ${project.artifactId}
 
-  You need to bind one of <<<jetty:start>>>, <<<jetty:run>>>, <<<jetty:run-exploded>>> or <<<jetty:run-war>>>
-  to the <<<pre-integration-test>>> phase with <<<daemon>>> set to true, bind
-  <<<failsafe:integration-test>>> to the <<<integration-test>>> phase, bind <<<jetty:stop>>>
-  to the <<<post-integration-test>>> phase and finally bind <<<failsafe:verify>>> to
-  the <<<verify>>> phase.  Here is an example:
+Using jetty and ${project.artifactId}
+-------------------------------------
 
-+---+
+You need to bind one of `jetty:start`, `jetty:run`, `jetty:run-exploded` or `jetty:run-war` to the `pre-integration-test` phase with `daemon` set to true, bind `failsafe:integration-test` to the `integration-test` phase, bind `jetty:stop` to the `post-integration-test` phase and finally bind `failsafe:verify` to the `verify` phase. Here is an example:
+
+```xml
 <project>
   [...]
   <build>
@@ -209,23 +179,17 @@ mvn verify
   </build>
   [...]
 </project>
-+---+
+```
 
-  You then invoke Maven with a phase of <<<verify>>> or later in order to run
-  the integration tests.  <<DO NOT>> directly invoke any of the phases
-  <<<pre-integration-test>>>, <<<integration-test>>>, or <<<post-integration-test>>> as
-  these are too long to type and they will likely leave a jetty container running.
+You then invoke Maven with a phase of `verify` or later in order to run the integration tests. **DO NOT** directly invoke any of the phases `pre-integration-test`, `integration-test`, or `post-integration-test` as these are too long to type and they will likely leave a jetty container running.
 
-+---+
+```bash
 mvn verify
-+---+
+```
 
-  Note: during test development, you will likely run a jetty instance in the background.
-  to help running the integration tests, it can be handy to bind <<<jetty:stop>>> to
-  the <<<pre-integration-test>>> phase before <<<jetty:run>>> to flush out any
-  running jetty instance before starting the integration test jetty instance, e.g.
+Note: during test development, you will likely run a jetty instance in the background. to help running the integration tests, it can be handy to bind `jetty:stop` to the `pre-integration-test` phase before `jetty:run` to flush out any running jetty instance before starting the integration test jetty instance, e.g.
 
-+---+
+```xml
 <project>
   [...]
   <build>
@@ -259,14 +223,14 @@ mvn verify
   </build>
   [...]
 </project>
-+---+
+```
 
-* Reporting integration test results
+Reporting integration test results
+----------------------------------
 
-  The ${thisPlugin} Plugin uses the exact same format as the ${thatPlugin} Plugin, so to generate a report you just add a second
-  Surefire Report Plugin report set using the ${thisPlugin} reports directory, e.g.
+The ${thisPlugin} Plugin uses the exact same format as the ${thatPlugin} Plugin, so to generate a report you just add a second Surefire Report Plugin report set using the ${thisPlugin} reports directory, e.g.
 
-+---+
+```xml
 <project>
   [...]
   <reporting>
@@ -288,15 +252,14 @@ mvn verify
   </reporting>
   [...]
 </project>
-+---+
+```
 
-* Running integration tests multiple times
+Running integration tests multiple times
+----------------------------------------
 
-  If you need to run your integration tests multiple times, just use multiple executions of the <<<integration-test>>>
-  goal.  You will need to specify a different summary file for each execution, and then configure the <<<verify>>> goal
-  with the multiple summary files in order to fail the build when any one execution has failures, e.g.
+If you need to run your integration tests multiple times, just use multiple executions of the `integration-test` goal. You will need to specify a different summary file for each execution, and then configure the `verify` goal with the multiple summary files in order to fail the build when any one execution has failures, e.g.
 
-+---+
+```xml
 <project>
   [...]
   <reporting>
@@ -348,16 +311,14 @@ mvn verify
   </reporting>
   [...]
 </project>
-+---+
+```
 
-* Usage in multi-module projects
+Usage in multi-module projects
+------------------------------
 
-  The recommendations for using the ${thisPlugin} Plugin listed at the top of this page are fine for 95% of use cases.
-  When you are defining a shared definition of the ${thisPlugin} Plugin in a parent pom, it is considered best practice
-  to define an execution id in order to allow child projects to override the configuration. Thus you might have the
-  following in your parent <<<pom.xml>>>:
+The recommendations for using the ${thisPlugin} Plugin listed at the top of this page are fine for 95% of use cases. When you are defining a shared definition of the ${thisPlugin} Plugin in a parent pom, it is considered best practice to define an execution id in order to allow child projects to override the configuration. Thus you might have the following in your parent `pom.xml`:
 
-+---+
+```xml
 <project>
   [...]
   <build>
@@ -382,11 +343,11 @@ mvn verify
   </build>
   [...]
 </project>
-+---+
+```
 
-  The child projects can then trigger usage of the ${thisPlugin} Plugin with
+The child projects can then trigger usage of the ${thisPlugin} Plugin with
 
-+---+
+```xml
 <project>
   [...]
   <build>
@@ -400,12 +361,11 @@ mvn verify
   </build>
   [...]
 </project>
-+---+
+```
 
-  For very complex builds, it may be better to separate the executions for the <<<integration-test>>> and <<<verify>>>
-  goals.
+For very complex builds, it may be better to separate the executions for the `integration-test` and `verify` goals.
 
-+---+
+```xml
 <project>
   [...]
   <build>
@@ -435,6 +395,5 @@ mvn verify
   </build>
   [...]
 </project>
-+---+
-
+```
 #{end}
diff --git a/maven-surefire-report-plugin/src/site/markdown/examples/changing-report-name.md.vm b/maven-surefire-report-plugin/src/site/markdown/examples/changing-report-name.md.vm
index 59b404d23..bc9490f7d 100644
--- a/maven-surefire-report-plugin/src/site/markdown/examples/changing-report-name.md.vm
+++ b/maven-surefire-report-plugin/src/site/markdown/examples/changing-report-name.md.vm
@@ -1,35 +1,28 @@
-  ------
-  Changing the Report Name
-  ------
-  Allan Ramirez
-  ------
-  July 2006
-  ------
+---
+title: Changing the Report Name
+author:
+  - Allan Ramirez
+date: July 2006
+---
 
-~~ Copyright 2006 The Apache Software Foundation.
-~~
-~~ Licensed 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.
+<!-- Copyright 2006 The Apache Software Foundation.-->
+<!---->
+<!-- Licensed 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.-->
+# Changing the Report Name
 
-~~ NOTE: For help with the syntax of this file, see:
-~~ http://maven.apache.org/doxia/references/apt-format.html
+In order to configure the file name of the generated report (which is "`surefire`" by default), the `outputName` property should be set to the desired name.
 
-Changing the Report Name
-
-  In order to configure the file name of the generated report (which is
-  "<<<surefire>>>" by default), the <<<outputName>>> property should
-  be set to the desired name.
-
-+----+
+```xml
 <project>
   [...]
   <reporting>
@@ -46,7 +39,6 @@ Changing the Report Name
   </reporting>
   [...]
 </project>
-+----+
+```
 
-  And after executing <<<mvn site>>>, the generated report file is named
-  <<desired_name.html>>.
+And after executing `mvn site`, the generated report file is named **desired\_name.html**.
diff --git a/maven-surefire-report-plugin/src/site/markdown/examples/cross-referencing.md.vm b/maven-surefire-report-plugin/src/site/markdown/examples/cross-referencing.md.vm
index dba721fab..e4569b6d2 100644
--- a/maven-surefire-report-plugin/src/site/markdown/examples/cross-referencing.md.vm
+++ b/maven-surefire-report-plugin/src/site/markdown/examples/cross-referencing.md.vm
@@ -1,40 +1,28 @@
-  ------
-  Source Code Cross Reference
-  ------
-  Allan Ramirez
-  ------
-  July 2006
-  ------
-
-~~ Copyright 2006 The Apache Software Foundation.
-~~
-~~ Licensed 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
-
-Source Code Cross Reference
-
-  There are times when we wish to know right away the line number of the
-  source code that caused a test to the fail. The Surefire Report Plugin
-  has the capability to cross reference the source code that made the test
-  fail. In order to activate this feature, the <<<maven-jxr-plugin>>> should
-  be declared in the <<<\<reporting\>>>> section of the POM along with the
-  <<<maven-surefire-report-plugin>>>. For more details, please read the
-  documentation of the
-  {{{http://maven.apache.org/plugins/maven-jxr-plugin/}Maven JXR Plugin}}.
-
-+----+
+---
+title: Source Code Cross Reference
+author:
+  - Allan Ramirez
+date: July 2006
+---
+
+<!-- Copyright 2006 The Apache Software Foundation.-->
+<!---->
+<!-- Licensed 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.-->
+# Source Code Cross Reference
+
+There are times when we wish to know right away the line number of the source code that caused a test to the fail. The Surefire Report Plugin has the capability to cross reference the source code that made the test fail. In order to activate this feature, the `maven-jxr-plugin` should be declared in the `<reporting>` section of the POM along with the `maven-surefire-report-plugin`. For more details, please read the documentation of the [Maven JXR Plugin](http://maven.apache.org/plugins/m [...]
+
+```xml
 <project>
   [...]
   <reporting>
@@ -56,23 +44,19 @@ Source Code Cross Reference
   </reporting>
   [...]
 </project>
-+----+
+```
 
-  After executing <<<mvn site>>> for site generation, you'll notice that from
-  the <<Failure Details>> section of the report, a link is available to
-  redirect you to the source code that caused the failure.
+After executing `mvn site` for site generation, you'll notice that from the **Failure Details** section of the report, a link is available to redirect you to the source code that caused the failure.
 
-  In the figure below the code that caused the failure is
-  <com.test.proj.AppTest:36>
+In the figure below the code that caused the failure is _com.test.proj.AppTest:36_
 
-[../images/failure-details.png] Failure Details
+<figure><img src="../images/failure-details.png" /><figcaption>Failure Details</figcaption></figure>
 
-  The link will redirect you to the source by clicking it.
+The link will redirect you to the source by clicking it.
 
-[../images/xref.png] The source
+<figure><img src="../images/xref.png" /><figcaption>The source</figcaption></figure>
 
-* Disabling the Cross Reference Link
+Disabling the Cross Reference Link
+----------------------------------
 
-  To disable the link to the source code, the <<linkXRef>> property should
-  be set to <<false>>. Alternatively one may simply omit the
-  <<<maven-jxr-plugin>>> from the <<<\<reporting\>>>> section.
+To disable the link to the source code, the **linkXRef** property should be set to **false**. Alternatively one may simply omit the `maven-jxr-plugin` from the `<reporting>` section.
diff --git a/maven-surefire-report-plugin/src/site/markdown/examples/linking-to-tests.md b/maven-surefire-report-plugin/src/site/markdown/examples/linking-to-tests.md
index 0ae77a16b..845765413 100644
--- a/maven-surefire-report-plugin/src/site/markdown/examples/linking-to-tests.md
+++ b/maven-surefire-report-plugin/src/site/markdown/examples/linking-to-tests.md
@@ -1,57 +1,45 @@
-  ------
-  Linking to Tests
-  ------
-  Sean Griffin
-  ------
-  May 2015
-  ------
-
-~~ Copyright 2006 The Apache Software Foundation.
-~~
-~~ Licensed 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
-
-Linking to Tests
-
-  Anchors surround the names of each test suite and test case in the report so
-  that you can remotely link to them.
-
-  The format of the anchor names for test suites is as follows:
-
-+----+
+---
+title: Linking to Tests
+author:
+  - Sean Griffin
+date: May 2015
+---
+
+<!-- Copyright 2006 The Apache Software Foundation.-->
+<!---->
+<!-- Licensed 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.-->
+# Linking to Tests
+
+Anchors surround the names of each test suite and test case in the report so that you can remotely link to them.
+
+The format of the anchor names for test suites is as follows:
+
+```xml
 <package><suiteName>
-+----+
+```
 
-  Notice that there is no "." between the package name and the suite name.
+Notice that there is no "." between the package name and the suite name.
 
-  The format of the anchor names for test cases is as follows:
+The format of the anchor names for test cases is as follows:
 
-+----+
+```text
 TC_<package>.<suiteName>.<testName>
-+----+
+```
 
-  To illustrate with an example, suppose the following:
+To illustrate with an example, suppose the following:
 
-  * Package name: org.foo
+- Package name: org.foo
+- Test suite name: FooTest
+- Test names: testFooWithBar, testFooWithBaz
 
-  * Test suite name: FooTest
-
-  * Test names: testFooWithBar, testFooWithBaz
-
-  []
-
-  The anchor name for the test suite would be "org.fooFooTest" and the anchor
-  names for the test cases would be "TC_org.foo.FooTest.testFooWithBar" and
-  "TC_org.foo.FooTest.testFooWithBaz".
\ No newline at end of file
+The anchor name for the test suite would be "org.fooFooTest" and the anchor names for the test cases would be "TC\_org.foo.FooTest.testFooWithBar" and "TC\_org.foo.FooTest.testFooWithBaz".
diff --git a/maven-surefire-report-plugin/src/site/markdown/examples/report-custom-location.md.vm b/maven-surefire-report-plugin/src/site/markdown/examples/report-custom-location.md.vm
index 87d810434..8d4dd98ca 100644
--- a/maven-surefire-report-plugin/src/site/markdown/examples/report-custom-location.md.vm
+++ b/maven-surefire-report-plugin/src/site/markdown/examples/report-custom-location.md.vm
@@ -1,37 +1,28 @@
-  ------
-  Configuring the Output Location of the Report
-  ------
-  Allan Ramirez
-  ------
-  July 2006
-  ------
-
-~~ Copyright 2006 The Apache Software Foundation.
-~~
-~~ Licensed 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
-
-Configuring the Output Location of the Report
-
-  To change the location of the generated output report along with other
-  project reports the <<outputDirectory>> property of both the
-  <<<maven-site-plugin>>> and <<<maven-surefire-report-plugin>>> should be set to the
-  desired alternative location. For more information, see the documentation of the
-  {{{http://maven.apache.org/plugins/maven-site-plugin/}Maven Site Plugin}}.
-
-+----+
+---
+title: Configuring the Output Location of the Report
+author:
+  - Allan Ramirez
+date: July 2006
+---
+
+<!-- Copyright 2006 The Apache Software Foundation.-->
+<!---->
+<!-- Licensed 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.-->
+# Configuring the Output Location of the Report
+
+To change the location of the generated output report along with other project reports the **outputDirectory** property of both the `maven-site-plugin` and `maven-surefire-report-plugin` should be set to the desired alternative location. For more information, see the documentation of the [Maven Site Plugin](http://maven.apache.org/plugins/maven-site-plugin/).
+
+```xml
 <project>
   [...]
   <reporting>
@@ -41,7 +32,7 @@ Configuring the Output Location of the Report
         <artifactId>maven-surefire-report-plugin</artifactId>
         <version>${project.version}</version>
         <configuration>
-          <outputDirectory>${basedir}/target/newsite</outputDirectory>
+          <outputDirectory>${esc.d}{basedir}/target/newsite</outputDirectory>
         </configuration>
       </plugin>
       <plugin>
@@ -49,24 +40,22 @@ Configuring the Output Location of the Report
         <artifactId>maven-site-plugin</artifactId>
         <version>2.1</version>
         <configuration>
-          <outputDirectory>${basedir}/target/newsite</outputDirectory>
+          <outputDirectory>${esc.d}{basedir}/target/newsite</outputDirectory>
         </configuration>
       </plugin>
     </plugins>
   </reporting>
   [...]
 </project>
-+----+
+```
 
-  Please take note that if the <<outputDirectory>> of the Site Plugin
-  is not configured, the output location of the Surefire report will still
-  be the default.
+Please take note that if the **outputDirectory** of the Site Plugin is not configured, the output location of the Surefire report will still be the default.
 
-* Configuring the Output Location using the Standalone Goal
+Configuring the Output Location using the Standalone Goal
+---------------------------------------------------------
 
-  To change the location of the generated output report using the standalone
-  goal, the <<outputDirectory>> property should be set to the new path:
+To change the location of the generated output report using the standalone goal, the **outputDirectory** property should be set to the new path:
 
-+---+
+```bash
 mvn surefire-report:report -DoutputDirectory=newpath
-+---+
+```
diff --git a/maven-surefire-report-plugin/src/site/markdown/examples/show-failures.md.vm b/maven-surefire-report-plugin/src/site/markdown/examples/show-failures.md.vm
index 969377e82..7718969c6 100644
--- a/maven-surefire-report-plugin/src/site/markdown/examples/show-failures.md.vm
+++ b/maven-surefire-report-plugin/src/site/markdown/examples/show-failures.md.vm
@@ -1,35 +1,28 @@
-  ------
-  Showing Only Failed Tests
-  ------
-  Allan Ramirez
-  ------
-  July 2006
-  ------
-
-~~ Copyright 2006 The Apache Software Foundation.
-~~
-~~ Licensed 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
-
-Showing Only Failed Tests
-
-  By default, the Surefire Report Plugin shows the full test result (i.e., successes
-  as well as failures) in the generated HTML. To be able to show the failures only, the
-  property <<showSuccess>> should be set to <<false>>.
-
-+----+
+---
+title: Showing Only Failed Tests
+author:
+  - Allan Ramirez
+date: July 2006
+---
+
+<!-- Copyright 2006 The Apache Software Foundation.-->
+<!---->
+<!-- Licensed 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.-->
+# Showing Only Failed Tests
+
+By default, the Surefire Report Plugin shows the full test result (i.e., successes as well as failures) in the generated HTML. To be able to show the failures only, the property **showSuccess** should be set to **false**.
+
+```xml
 <project>
   [...]
   <reporting>
@@ -46,12 +39,12 @@ Showing Only Failed Tests
   </reporting>
   [...]
 </project>
-+----+
+```
 
-  Then execute <<<mvn site>>> for the report generation.
+Then execute `mvn site` for the report generation.
 
-  It can also be set via command line with the standalone goal:
+It can also be set via command line with the standalone goal:
 
-+----+
+```bash
   mvn surefire-report:report -DshowSuccess=false
-+----+
+```
diff --git a/maven-surefire-report-plugin/src/site/markdown/index.md b/maven-surefire-report-plugin/src/site/markdown/index.md
index aa7169627..5eca70457 100644
--- a/maven-surefire-report-plugin/src/site/markdown/index.md
+++ b/maven-surefire-report-plugin/src/site/markdown/index.md
@@ -1,82 +1,50 @@
-  ------
-  Introduction
-  ------
-  Allan Ramirez
-  ------
-  July 2006
-  ------
+---
+title: Introduction
+author:
+  - Allan Ramirez
+date: July 2006
+---
 
-~~ Copyright 2006 The Apache Software Foundation.
-~~
-~~ Licensed 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.
+<!-- Copyright 2006 The Apache Software Foundation.-->
+<!---->
+<!-- Licensed 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.-->
+# Maven Surefire Report Plugin
 
-~~ NOTE: For help with the syntax of this file, see:
-~~ http://maven.apache.org/doxia/references/apt-format.html
+The Surefire Report Plugin parses the generated `TEST-*.xml` files under `${basedir}/target/surefire-reports` and renders them using DOXIA, which creates the web interface version of the test results.
 
-Maven Surefire Report Plugin
+## Goals Overview
 
-  The Surefire Report Plugin parses the generated <<<TEST-*.xml>>> files under
-  <<<$\{basedir\}/target/surefire-reports>>> and renders them using DOXIA,
-  which creates the web interface version of the test results.
+The Surefire Report Plugin has three goals:
 
-* Goals Overview
+- [surefire-report:report](./report-mojo.html) Generates the test results report into HTML format.
+- [surefire-report:report-only](./report-only-mojo.html) This goal does not run the tests, it only builds the report. It is provided as a work around for [SUREFIRE-257](https://issues.apache.org/jira/browse/SUREFIRE-257)
+- [surefire-report:failsafe-report-only](./failsafe-report-only-mojo.html) This goal does not run the tests, it only builds the IT reports. See [SUREFIRE-257](https://issues.apache.org/jira/browse/SUREFIRE-257)
 
-  The Surefire Report Plugin has three goals:
+_Note:_ As of version 2.8 this plugin requires Maven Site Plugin 2.1 or newer to work properly. Version 2.7.2 and older are still compatible with newer Surefire versions, so mixing is possible.
 
-  * {{{./report-mojo.html}surefire-report:report}} Generates the test
-  results report into HTML format.
+## Usage
 
-  * {{{./report-only-mojo.html}surefire-report:report-only}} This goal does
-  not run the tests, it only builds the report. It is provided as a work
-  around for {{{https://issues.apache.org/jira/browse/SUREFIRE-257}SUREFIRE-257}}
+General instructions on how to use the Surefire Report Plugin can be found on the [usage page](./usage.html). Some more specific use cases are described in the examples listed below. Additionally, users can contribute to the [GitHub project](https://github.com/apache/maven-surefire).
 
-  * {{{./failsafe-report-only-mojo.html}surefire-report:failsafe-report-only}} This goal does not
-  run the tests, it only builds the IT reports. See {{{https://issues.apache.org/jira/browse/SUREFIRE-257}SUREFIRE-257}}
+In case you still have questions regarding the plugin's usage, please have a look at the [FAQ](./faq.html) and feel free to contact the [user mailing list](./mailing-lists.html). The posts to the mailing list are archived and could already contain the answer to your question as part of an older thread. Hence, it is also worth browsing/searching the [mail archive](./mailing-lists.html).
 
-  []
+If you feel like the plugin is missing a feature or has a defect, you can file a feature request or bug report in our [issue tracker](./issue-management.html). 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 wel [...]
 
-  <Note:> As of version 2.8 this plugin requires Maven Site Plugin 2.1 or newer to work properly. Version 2.7.2 and
-  older are still compatible with newer Surefire versions, so mixing is possible.
+## Examples
 
-* Usage
+The following examples show how to use the Surefire Report Plugin in more advanced use cases:
 
-  General instructions on how to use the Surefire Report Plugin can be found on the {{{./usage.html}usage page}}. Some more
-  specific use cases are described in the examples listed below. Additionally, users can contribute to the
-  {{{https://github.com/apache/maven-surefire}GitHub project}}.
-
-  In case you still have questions regarding the plugin's usage, please have a look at the {{{./faq.html}FAQ}} and feel
-  free to contact the {{{./mailing-lists.html}user mailing list}}. The posts to the mailing list are archived and could
-  already contain the answer to your question as part of an older thread. Hence, it is also worth browsing/searching
-  the {{{./mailing-lists.html}mail archive}}.
-
-  If you feel like the plugin is missing a feature or has a defect, you can file a feature request or bug report in our
-  {{{./issue-management.html}issue tracker}}. 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
-  {{{http://maven.apache.org/guides/development/guide-helping.html}guide to helping with Maven}}.
-
-* Examples
-
-  The following examples show how to use the Surefire Report Plugin in more advanced use cases:
-
-  * {{{./examples/show-failures.html}Showing Only Failed Tests}}
-
-  * {{{./examples/changing-report-name.html}Changing the Report Name}}
-
-  * {{{./examples/report-custom-location.html}Configuring the Output Location of the Report}}
-
-  * {{{./examples/cross-referencing.html}Source Code Cross Reference}}
-
-  []
+- [Showing Only Failed Tests](./examples/show-failures.html)
+- [Changing the Report Name](./examples/changing-report-name.html)
+- [Configuring the Output Location of the Report](./examples/report-custom-location.html)
+- [Source Code Cross Reference](./examples/cross-referencing.html)
diff --git a/maven-surefire-report-plugin/src/site/markdown/usage.md.vm b/maven-surefire-report-plugin/src/site/markdown/usage.md.vm
index a6d93a70a..29ca3611b 100644
--- a/maven-surefire-report-plugin/src/site/markdown/usage.md.vm
+++ b/maven-surefire-report-plugin/src/site/markdown/usage.md.vm
@@ -1,36 +1,31 @@
-  ------
-  Usage
-  ------
-  Allan Ramirez
-  ------
-  July 2006
-  ------
-
-~~ Copyright 2006 The Apache Software Foundation.
-~~
-~~ Licensed 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
-
-Usage
-
-* Generate the Report as Part of Project Reports
-
-  To generate the Surefire report as part of the site generation, add the following in
-  the <<<\<reporting\>>>> section of your POM:
-
-+---+
+---
+title: Usage
+author:
+  - Allan Ramirez
+date: July 2006
+---
+
+<!-- Copyright 2006 The Apache Software Foundation.-->
+<!---->
+<!-- Licensed 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.-->
+# Usage
+
+Generate the Report as Part of Project Reports
+----------------------------------------------
+
+To generate the Surefire report as part of the site generation, add the following in the `<reporting>` section of your POM:
+
+```xml
 <project>
   ...
   <reporting>
@@ -44,22 +39,21 @@ Usage
   </reporting>
   ...
 </project>
-+---+
-
-  When <<<mvn site>>> is invoked, the report will automatically be
-  included in the Project Reports menu as shown in the figure below.
+```
 
-[images/surefire-sample1.png] Sample Surefire Report
+When `mvn site` is invoked, the report will automatically be included in the Project Reports menu as shown in the figure below.
 
-* Generate the Report in a Standalone Fashion
+<figure><img src="images/surefire-sample1.png" /><figcaption>Sample Surefire Report</figcaption></figure>
 
-  The plugin can also generate the report using its standalone goal:
+Generate the Report in a Standalone Fashion
+-------------------------------------------
 
-+---+
-mvn surefire-report:report  
-+---+
+The plugin can also generate the report using its standalone goal:
 
-  An HTML report should be generated in <<<$\{basedir\}/target/reports/surefire.html>>>.
+```bash
+mvn surefire-report:report
+```
 
-[images/surefire-sample2.png] Sample standalone surefire-report
+An HTML report should be generated in `${esc.d}{basedir}/target/reports/surefire.html`.
 
+<figure><img src="images/surefire-sample2.png" /><figcaption>Sample standalone surefire-report</figcaption></figure>
diff --git a/surefire-api/src/site/markdown/index.md b/surefire-api/src/site/markdown/index.md
index f83f0ba7e..675e949d1 100644
--- a/surefire-api/src/site/markdown/index.md
+++ b/surefire-api/src/site/markdown/index.md
@@ -1,52 +1,46 @@
-  ~~ 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.
-
- -----
- Surefire API Design
- -----
- Brett Porter
- -----
- 2007-03-03
- -----
-
-Surefire API
-
-* Definitions
-
-*-------------+-----------------------------------------------+
-| test method | Individual test method within a class         |
-*-------------+-----------------------------------------------+
-| test        | 1..N test methods in 1 or more classes.       |
-*-------------+-----------------------------------------------+
-| suite       | 1..N tests.                                   |
-*-------------+-----------------------------------------------+
-| group       | A named subset of test methods within a test. |
-*-------------+-----------------------------------------------+
-
-  How each definition is applied depends on the provider, and the test suite being used.
-
-  * Directory test suite: this constructs a single suite from a directory file set. Each discovered class is treated as a test.
-
-  * TestNG XML test suite: this constructs a single suite from a <<<testng.xml>>> file. The definitions inside the file will match those above.
-
-  * JUnit 3.x: Groups are not supported.
-
-  []
-
-  See {{{../surefire-providers/index.html}Surefire Providers}} for more information on specific providers.
-
-~~TODO: fix up URLs, move some to providers/javadoc.
+---
+title: Surefire API Design
+author:
+  - Brett Porter
+date: 2007-03-03
+---
+
+<!--
+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.
+-->
+
+# Surefire API
+
+## Definitions
+
+<table class="table table-bordered table-striped">
+<tr><td style="text-align: left;">test method</td><td style="text-align: left;">Individual test method within a class</td></tr>
+<tr><td style="text-align: left;">test</td><td style="text-align: left;">1..N test methods in 1 or more classes.</td></tr>
+<tr><td style="text-align: left;">suite</td><td style="text-align: left;">1..N tests.</td></tr>
+<tr><td style="text-align: left;">group</td><td style="text-align: left;">A named subset of test methods within a test.</td></tr>
+</table>
+
+How each definition is applied depends on the provider, and the test suite being used.
+
+- Directory test suite: this constructs a single suite from a directory file set. Each discovered class is treated as a test.
+- TestNG XML test suite: this constructs a single suite from a `testng.xml` file. The definitions inside the file will match those above.
+- JUnit 3.x: Groups are not supported.
+
+See [Surefire Providers](../surefire-providers/index.html) for more information on specific providers.
+
+<!--TODO: fix up URLs, move some to providers/javadoc.-->


(maven-surefire) 01/02: Rename the site documents ahead of converting them

Posted by sl...@apache.org.
This is an automated email from the ASF dual-hosted git repository.

slachiewicz pushed a commit to branch surefire-3.5.x
in repository https://gitbox.apache.org/repos/asf/maven-surefire.git

commit a93e5d1f31d2c54c9e5ba723951ee76fd9b42a42
Author: Sylwester Lachiewicz <sl...@apache.org>
AuthorDate: Mon Aug 17 17:11:26 2026 +0200

    Rename the site documents ahead of converting them
---
 maven-surefire-plugin/src/site/{apt/api.apt.vm => markdown/api.md}        | 0
 .../src/site/{apt/developing.apt.vm => markdown/developing.md}            | 0
 .../class-loading.apt.vm => markdown/examples/class-loading.md.vm}        | 0
 .../examples/configuring-classpath.md.vm}                                 | 0
 .../{apt/examples/cucumber.apt.vm => markdown/examples/cucumber.md.vm}    | 0
 .../src/site/{apt/examples/cwd.apt.vm => markdown/examples/cwd.md}        | 0
 .../{apt/examples/debugging.apt.vm => markdown/examples/debugging.md.vm}  | 0
 .../examples/fork-options-and-parallel-execution.md.vm}                   | 0
 .../examples/inclusion-exclusion.md.vm}                                   | 0
 .../src/site/{apt/examples/jpms.apt.vm => markdown/examples/jpms.md.vm}   | 0
 .../junit-platform.apt.vm => markdown/examples/junit-platform.md.vm}      | 0
 .../src/site/{apt/examples/junit.apt.vm => markdown/examples/junit.md.vm} | 0
 .../site/{apt/examples/logging.apt.vm => markdown/examples/logging.md.vm} | 0
 .../{apt/examples/pojo-test.apt.vm => markdown/examples/pojo-test.md}     | 0
 .../examples/process-communication.md.vm}                                 | 0
 .../{apt/examples/providers.apt.vm => markdown/examples/providers.md.vm}  | 0
 .../examples/rerun-failing-tests.md.vm}                                   | 0
 .../{apt/examples/shutdown.apt.vm => markdown/examples/shutdown.md.vm}    | 0
 .../examples/single-test.apt.vm => markdown/examples/single-test.md.vm}   | 0
 .../examples/skip-after-failure.md.vm}                                    | 0
 .../skipping-tests.apt.vm => markdown/examples/skipping-tests.md.vm}      | 0
 .../src/site/{apt/examples/spock.apt.vm => markdown/examples/spock.md.vm} | 0
 .../examples/system-properties.md.vm}                                     | 0
 .../site/{apt/examples/testng.apt.vm => markdown/examples/testng.md.vm}   | 0
 .../examples/toolchains.apt.vm => markdown/examples/toolchains.md.vm}     | 0
 .../src/site/{apt/featurematrix.apt.vm => markdown/featurematrix.md}      | 0
 .../src/site/{apt/history.apt.vm => markdown/history.md.vm}               | 0
 maven-surefire-plugin/src/site/{apt/index.apt.vm => markdown/index.md.vm} | 0
 maven-surefire-plugin/src/site/{apt/usage.apt.vm => markdown/usage.md.vm} | 0
 .../examples/changing-report-name.md.vm}                                  | 0
 .../examples/cross-referencing.md.vm}                                     | 0
 .../linking-to-tests.apt.vm => markdown/examples/linking-to-tests.md}     | 0
 .../examples/report-custom-location.md.vm}                                | 0
 .../show-failures.apt.vm => markdown/examples/show-failures.md.vm}        | 0
 .../src/site/{apt/index.apt => markdown/index.md}                         | 0
 .../src/site/{apt/usage.apt.vm => markdown/usage.md.vm}                   | 0
 surefire-api/src/site/{apt/index.apt => markdown/index.md}                | 0
 37 files changed, 0 insertions(+), 0 deletions(-)

diff --git a/maven-surefire-plugin/src/site/apt/api.apt.vm b/maven-surefire-plugin/src/site/markdown/api.md
similarity index 100%
rename from maven-surefire-plugin/src/site/apt/api.apt.vm
rename to maven-surefire-plugin/src/site/markdown/api.md
diff --git a/maven-surefire-plugin/src/site/apt/developing.apt.vm b/maven-surefire-plugin/src/site/markdown/developing.md
similarity index 100%
rename from maven-surefire-plugin/src/site/apt/developing.apt.vm
rename to maven-surefire-plugin/src/site/markdown/developing.md
diff --git a/maven-surefire-plugin/src/site/apt/examples/class-loading.apt.vm b/maven-surefire-plugin/src/site/markdown/examples/class-loading.md.vm
similarity index 100%
rename from maven-surefire-plugin/src/site/apt/examples/class-loading.apt.vm
rename to maven-surefire-plugin/src/site/markdown/examples/class-loading.md.vm
diff --git a/maven-surefire-plugin/src/site/apt/examples/configuring-classpath.apt.vm b/maven-surefire-plugin/src/site/markdown/examples/configuring-classpath.md.vm
similarity index 100%
rename from maven-surefire-plugin/src/site/apt/examples/configuring-classpath.apt.vm
rename to maven-surefire-plugin/src/site/markdown/examples/configuring-classpath.md.vm
diff --git a/maven-surefire-plugin/src/site/apt/examples/cucumber.apt.vm b/maven-surefire-plugin/src/site/markdown/examples/cucumber.md.vm
similarity index 100%
rename from maven-surefire-plugin/src/site/apt/examples/cucumber.apt.vm
rename to maven-surefire-plugin/src/site/markdown/examples/cucumber.md.vm
diff --git a/maven-surefire-plugin/src/site/apt/examples/cwd.apt.vm b/maven-surefire-plugin/src/site/markdown/examples/cwd.md
similarity index 100%
rename from maven-surefire-plugin/src/site/apt/examples/cwd.apt.vm
rename to maven-surefire-plugin/src/site/markdown/examples/cwd.md
diff --git a/maven-surefire-plugin/src/site/apt/examples/debugging.apt.vm b/maven-surefire-plugin/src/site/markdown/examples/debugging.md.vm
similarity index 100%
rename from maven-surefire-plugin/src/site/apt/examples/debugging.apt.vm
rename to maven-surefire-plugin/src/site/markdown/examples/debugging.md.vm
diff --git a/maven-surefire-plugin/src/site/apt/examples/fork-options-and-parallel-execution.apt.vm b/maven-surefire-plugin/src/site/markdown/examples/fork-options-and-parallel-execution.md.vm
similarity index 100%
rename from maven-surefire-plugin/src/site/apt/examples/fork-options-and-parallel-execution.apt.vm
rename to maven-surefire-plugin/src/site/markdown/examples/fork-options-and-parallel-execution.md.vm
diff --git a/maven-surefire-plugin/src/site/apt/examples/inclusion-exclusion.apt.vm b/maven-surefire-plugin/src/site/markdown/examples/inclusion-exclusion.md.vm
similarity index 100%
rename from maven-surefire-plugin/src/site/apt/examples/inclusion-exclusion.apt.vm
rename to maven-surefire-plugin/src/site/markdown/examples/inclusion-exclusion.md.vm
diff --git a/maven-surefire-plugin/src/site/apt/examples/jpms.apt.vm b/maven-surefire-plugin/src/site/markdown/examples/jpms.md.vm
similarity index 100%
rename from maven-surefire-plugin/src/site/apt/examples/jpms.apt.vm
rename to maven-surefire-plugin/src/site/markdown/examples/jpms.md.vm
diff --git a/maven-surefire-plugin/src/site/apt/examples/junit-platform.apt.vm b/maven-surefire-plugin/src/site/markdown/examples/junit-platform.md.vm
similarity index 100%
rename from maven-surefire-plugin/src/site/apt/examples/junit-platform.apt.vm
rename to maven-surefire-plugin/src/site/markdown/examples/junit-platform.md.vm
diff --git a/maven-surefire-plugin/src/site/apt/examples/junit.apt.vm b/maven-surefire-plugin/src/site/markdown/examples/junit.md.vm
similarity index 100%
rename from maven-surefire-plugin/src/site/apt/examples/junit.apt.vm
rename to maven-surefire-plugin/src/site/markdown/examples/junit.md.vm
diff --git a/maven-surefire-plugin/src/site/apt/examples/logging.apt.vm b/maven-surefire-plugin/src/site/markdown/examples/logging.md.vm
similarity index 100%
rename from maven-surefire-plugin/src/site/apt/examples/logging.apt.vm
rename to maven-surefire-plugin/src/site/markdown/examples/logging.md.vm
diff --git a/maven-surefire-plugin/src/site/apt/examples/pojo-test.apt.vm b/maven-surefire-plugin/src/site/markdown/examples/pojo-test.md
similarity index 100%
rename from maven-surefire-plugin/src/site/apt/examples/pojo-test.apt.vm
rename to maven-surefire-plugin/src/site/markdown/examples/pojo-test.md
diff --git a/maven-surefire-plugin/src/site/apt/examples/process-communication.apt.vm b/maven-surefire-plugin/src/site/markdown/examples/process-communication.md.vm
similarity index 100%
rename from maven-surefire-plugin/src/site/apt/examples/process-communication.apt.vm
rename to maven-surefire-plugin/src/site/markdown/examples/process-communication.md.vm
diff --git a/maven-surefire-plugin/src/site/apt/examples/providers.apt.vm b/maven-surefire-plugin/src/site/markdown/examples/providers.md.vm
similarity index 100%
rename from maven-surefire-plugin/src/site/apt/examples/providers.apt.vm
rename to maven-surefire-plugin/src/site/markdown/examples/providers.md.vm
diff --git a/maven-surefire-plugin/src/site/apt/examples/rerun-failing-tests.apt.vm b/maven-surefire-plugin/src/site/markdown/examples/rerun-failing-tests.md.vm
similarity index 100%
rename from maven-surefire-plugin/src/site/apt/examples/rerun-failing-tests.apt.vm
rename to maven-surefire-plugin/src/site/markdown/examples/rerun-failing-tests.md.vm
diff --git a/maven-surefire-plugin/src/site/apt/examples/shutdown.apt.vm b/maven-surefire-plugin/src/site/markdown/examples/shutdown.md.vm
similarity index 100%
rename from maven-surefire-plugin/src/site/apt/examples/shutdown.apt.vm
rename to maven-surefire-plugin/src/site/markdown/examples/shutdown.md.vm
diff --git a/maven-surefire-plugin/src/site/apt/examples/single-test.apt.vm b/maven-surefire-plugin/src/site/markdown/examples/single-test.md.vm
similarity index 100%
rename from maven-surefire-plugin/src/site/apt/examples/single-test.apt.vm
rename to maven-surefire-plugin/src/site/markdown/examples/single-test.md.vm
diff --git a/maven-surefire-plugin/src/site/apt/examples/skip-after-failure.apt.vm b/maven-surefire-plugin/src/site/markdown/examples/skip-after-failure.md.vm
similarity index 100%
rename from maven-surefire-plugin/src/site/apt/examples/skip-after-failure.apt.vm
rename to maven-surefire-plugin/src/site/markdown/examples/skip-after-failure.md.vm
diff --git a/maven-surefire-plugin/src/site/apt/examples/skipping-tests.apt.vm b/maven-surefire-plugin/src/site/markdown/examples/skipping-tests.md.vm
similarity index 100%
rename from maven-surefire-plugin/src/site/apt/examples/skipping-tests.apt.vm
rename to maven-surefire-plugin/src/site/markdown/examples/skipping-tests.md.vm
diff --git a/maven-surefire-plugin/src/site/apt/examples/spock.apt.vm b/maven-surefire-plugin/src/site/markdown/examples/spock.md.vm
similarity index 100%
rename from maven-surefire-plugin/src/site/apt/examples/spock.apt.vm
rename to maven-surefire-plugin/src/site/markdown/examples/spock.md.vm
diff --git a/maven-surefire-plugin/src/site/apt/examples/system-properties.apt.vm b/maven-surefire-plugin/src/site/markdown/examples/system-properties.md.vm
similarity index 100%
rename from maven-surefire-plugin/src/site/apt/examples/system-properties.apt.vm
rename to maven-surefire-plugin/src/site/markdown/examples/system-properties.md.vm
diff --git a/maven-surefire-plugin/src/site/apt/examples/testng.apt.vm b/maven-surefire-plugin/src/site/markdown/examples/testng.md.vm
similarity index 100%
rename from maven-surefire-plugin/src/site/apt/examples/testng.apt.vm
rename to maven-surefire-plugin/src/site/markdown/examples/testng.md.vm
diff --git a/maven-surefire-plugin/src/site/apt/examples/toolchains.apt.vm b/maven-surefire-plugin/src/site/markdown/examples/toolchains.md.vm
similarity index 100%
rename from maven-surefire-plugin/src/site/apt/examples/toolchains.apt.vm
rename to maven-surefire-plugin/src/site/markdown/examples/toolchains.md.vm
diff --git a/maven-surefire-plugin/src/site/apt/featurematrix.apt.vm b/maven-surefire-plugin/src/site/markdown/featurematrix.md
similarity index 100%
rename from maven-surefire-plugin/src/site/apt/featurematrix.apt.vm
rename to maven-surefire-plugin/src/site/markdown/featurematrix.md
diff --git a/maven-surefire-plugin/src/site/apt/history.apt.vm b/maven-surefire-plugin/src/site/markdown/history.md.vm
similarity index 100%
rename from maven-surefire-plugin/src/site/apt/history.apt.vm
rename to maven-surefire-plugin/src/site/markdown/history.md.vm
diff --git a/maven-surefire-plugin/src/site/apt/index.apt.vm b/maven-surefire-plugin/src/site/markdown/index.md.vm
similarity index 100%
rename from maven-surefire-plugin/src/site/apt/index.apt.vm
rename to maven-surefire-plugin/src/site/markdown/index.md.vm
diff --git a/maven-surefire-plugin/src/site/apt/usage.apt.vm b/maven-surefire-plugin/src/site/markdown/usage.md.vm
similarity index 100%
rename from maven-surefire-plugin/src/site/apt/usage.apt.vm
rename to maven-surefire-plugin/src/site/markdown/usage.md.vm
diff --git a/maven-surefire-report-plugin/src/site/apt/examples/changing-report-name.apt.vm b/maven-surefire-report-plugin/src/site/markdown/examples/changing-report-name.md.vm
similarity index 100%
rename from maven-surefire-report-plugin/src/site/apt/examples/changing-report-name.apt.vm
rename to maven-surefire-report-plugin/src/site/markdown/examples/changing-report-name.md.vm
diff --git a/maven-surefire-report-plugin/src/site/apt/examples/cross-referencing.apt.vm b/maven-surefire-report-plugin/src/site/markdown/examples/cross-referencing.md.vm
similarity index 100%
rename from maven-surefire-report-plugin/src/site/apt/examples/cross-referencing.apt.vm
rename to maven-surefire-report-plugin/src/site/markdown/examples/cross-referencing.md.vm
diff --git a/maven-surefire-report-plugin/src/site/apt/examples/linking-to-tests.apt.vm b/maven-surefire-report-plugin/src/site/markdown/examples/linking-to-tests.md
similarity index 100%
rename from maven-surefire-report-plugin/src/site/apt/examples/linking-to-tests.apt.vm
rename to maven-surefire-report-plugin/src/site/markdown/examples/linking-to-tests.md
diff --git a/maven-surefire-report-plugin/src/site/apt/examples/report-custom-location.apt.vm b/maven-surefire-report-plugin/src/site/markdown/examples/report-custom-location.md.vm
similarity index 100%
rename from maven-surefire-report-plugin/src/site/apt/examples/report-custom-location.apt.vm
rename to maven-surefire-report-plugin/src/site/markdown/examples/report-custom-location.md.vm
diff --git a/maven-surefire-report-plugin/src/site/apt/examples/show-failures.apt.vm b/maven-surefire-report-plugin/src/site/markdown/examples/show-failures.md.vm
similarity index 100%
rename from maven-surefire-report-plugin/src/site/apt/examples/show-failures.apt.vm
rename to maven-surefire-report-plugin/src/site/markdown/examples/show-failures.md.vm
diff --git a/maven-surefire-report-plugin/src/site/apt/index.apt b/maven-surefire-report-plugin/src/site/markdown/index.md
similarity index 100%
rename from maven-surefire-report-plugin/src/site/apt/index.apt
rename to maven-surefire-report-plugin/src/site/markdown/index.md
diff --git a/maven-surefire-report-plugin/src/site/apt/usage.apt.vm b/maven-surefire-report-plugin/src/site/markdown/usage.md.vm
similarity index 100%
rename from maven-surefire-report-plugin/src/site/apt/usage.apt.vm
rename to maven-surefire-report-plugin/src/site/markdown/usage.md.vm
diff --git a/surefire-api/src/site/apt/index.apt b/surefire-api/src/site/markdown/index.md
similarity index 100%
rename from surefire-api/src/site/apt/index.apt
rename to surefire-api/src/site/markdown/index.md