You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by kw...@apache.org on 2026/04/16 14:43:15 UTC

(maven-site-plugin) branch feature/apt-to-markdown created (now da925c86)

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

kwin pushed a change to branch feature/apt-to-markdown
in repository https://gitbox.apache.org/repos/asf/maven-site-plugin.git


      at da925c86 Convert APT to Markdown format

This branch includes the following new commits:

     new 21f1a8a5 Move to match target converter format MARKDOWN with doxia-converter
     new da925c86 Convert APT to Markdown format

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.



(maven-site-plugin) 02/02: Convert APT to Markdown format

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

kwin pushed a commit to branch feature/apt-to-markdown
in repository https://gitbox.apache.org/repos/asf/maven-site-plugin.git

commit da925c8607e831184c928095b58dad458a3705b8
Author: Konrad Windszus <kw...@apache.org>
AuthorDate: Thu Apr 16 16:43:05 2026 +0200

    Convert APT to Markdown format
---
 src/site/{apt => markdown}/developer-overview.odg  | Bin
 .../markdown/examples/adding-deploy-protocol.md.vm |  73 +++--
 src/site/markdown/examples/configuring-reports.md  | 146 ++++-----
 src/site/markdown/examples/creating-content.md.vm  | 238 +++++----------
 src/site/markdown/examples/creatingskins.md        | 115 +++----
 .../inheritance-site-distribution-management.md    |  86 +++---
 src/site/markdown/examples/moduleexcludes.md.vm    |  76 +++--
 src/site/markdown/examples/multimodule.md          | 174 ++++-------
 .../examples/site-deploy-to-sourceforge.net.md     | 318 ++++++++++----------
 src/site/markdown/examples/sitedescriptor.md       | 332 ++++++++-------------
 src/site/markdown/examples/siterun.md.vm           |  76 +++--
 src/site/markdown/history.md                       | 215 +++++--------
 src/site/markdown/index.md.vm                      | 146 ++++-----
 src/site/markdown/migrate.md                       | 221 ++++++--------
 src/site/markdown/usage.md                         | 233 ++++++---------
 15 files changed, 974 insertions(+), 1475 deletions(-)

diff --git a/src/site/apt/developer-overview.odg b/src/site/markdown/developer-overview.odg
similarity index 100%
rename from src/site/apt/developer-overview.odg
rename to src/site/markdown/developer-overview.odg
diff --git a/src/site/markdown/examples/adding-deploy-protocol.md.vm b/src/site/markdown/examples/adding-deploy-protocol.md.vm
index 2503faa6..c20f27b5 100644
--- a/src/site/markdown/examples/adding-deploy-protocol.md.vm
+++ b/src/site/markdown/examples/adding-deploy-protocol.md.vm
@@ -1,53 +1,47 @@
- ------
- Adding a Protocol to Deploy the Site
- ------
- Hervé Boutemy
- ------
- 2011-07-24
- ------
+---
+title: Adding a Protocol to Deploy the Site
+author: 
+  - Hervé Boutemy
+date: 2011-07-24
+---
 
- ~~ Licensed to the Apache Software Foundation (ASF) under one
- ~~ or more contributor license agreements.  See the NOTICE file
- ~~ distributed with this work for additional information
- ~~ regarding copyright ownership.  The ASF licenses this file
- ~~ to you under the Apache License, Version 2.0 (the
- ~~ "License"); you may not use this file except in compliance
- ~~ with the License.  You may obtain a copy of the License at
- ~~
- ~~   http://www.apache.org/licenses/LICENSE-2.0
- ~~
- ~~ Unless required by applicable law or agreed to in writing,
- ~~ software distributed under the License is distributed on an
- ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- ~~ KIND, either express or implied.  See the License for the
- ~~ specific language governing permissions and limitations
- ~~ under the License.
+<!-- 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-->
+# Adding a Protocol to Deploy the Site
 
- ~~ NOTE: For help with the syntax of this file, see:
- ~~ http://maven.apache.org/doxia/references/apt-format.html
+Out of the box, Maven only supports `file:`, `http:`, `https:`, and `scp:` as transport protocols.
 
+If you try to deploy a site with an unsupported protocol, you&apos;ll get an error:
 
-Adding a Protocol to Deploy the Site
-
-  Out of the box, Maven only supports <<<file:>>>, <<<http:>>>, <<<https:>>>, and <<<scp:>>> as transport protocols.
-
-  If you try to deploy a site with an unsupported protocol, you'll get an error:
-
------
+```
 [ERROR] 
 Unsupported protocol: '...' for site deployment to distributionManagement.site.url=...
 Currently supported protocols are: ...
     Protocols may be added through wagon providers.
     For more information, see http://maven.apache.org/plugins/maven-site-plugin/examples/adding-deploy-protocol.html
------
+```
 
-  As explained in the error message, to deploy a site with a non-built-in protocol, you need to add the corresponding
-  {{{/wagon/}wagon provider}}.
+As explained in the error message, to deploy a site with a non-built-in protocol, you need to add the corresponding [wagon provider](/wagon/).
 
-  You can add it either as a {{{/guides/mini/guide-using-extensions.html}global extension}},
-  or declare it at as a dependency of the site plugin:
+You can add it either as a [global extension](/guides/mini/guide-using-extensions.html), or declare it at as a dependency of the site plugin:
 
-+-----+
+```unknown
 <project>
   ...
   <build>
@@ -70,4 +64,5 @@ Currently supported protocols are: ...
   </build>
   ...
 </project>
-+-----+
+```
+
diff --git a/src/site/markdown/examples/configuring-reports.md b/src/site/markdown/examples/configuring-reports.md
index 2c0487cb..625e38db 100644
--- a/src/site/markdown/examples/configuring-reports.md
+++ b/src/site/markdown/examples/configuring-reports.md
@@ -1,67 +1,48 @@
- ------
- Configuring Reports
- ------
- Dennis Lundberg
- Hervé Boutemy
- ------
- 2012-12-02
- ------
-
- ~~ 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
-
-
-Configuring Reports
-
-  Maven has several reports that you can add to your web site to display the
-  current state of the project. These reports take the form of plugin goals, just
-  like those used to build the project.
-
-  {{{/plugins/maven-project-info-reports-plugin/}Maven Project Info Reports Plugin}}
-  provides many standard reports by extracting information from the POM, for example:
-
-  * Continous Integration
-
-  * Dependencies
-
-  * Issue Tracking
-
-  * License
-
-  * Mailing Lists
-
-  * Project Team
-
-  * Source Repository
-
-  []
-
-  To find out more please see to the
-  {{{/plugins/maven-project-info-reports-plugin/}Project Info Reports Plugin}}.
-
-  To add these reports to your site, you must add the plugin to the
-  <<<\<reporting\>>>> element in the POM. The following example shows how to
-  configure the standard Project Info Reports that display information from the
-  POM in a friendly format:
-
-+-----------------+
+---
+title: Configuring Reports
+author: 
+  - Dennis Lundberg
+  - Hervé Boutemy
+date: 2012-12-02
+---
+
+<!-- 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-->
+# Configuring Reports
+
+Maven has several reports that you can add to your web site to display the current state of the project. These reports take the form of plugin goals, just like those used to build the project.
+
+[Maven Project Info Reports Plugin](/plugins/maven-project-info-reports-plugin/) provides many standard reports by extracting information from the POM, for example:
+
+- Continous Integration
+- Dependencies
+- Issue Tracking
+- License
+- Mailing Lists
+- Project Team
+- Source Repository
+
+To find out more please see to the [Project Info Reports Plugin](/plugins/maven-project-info-reports-plugin/).
+
+To add these reports to your site, you must add the plugin to the `<reporting>` element in the POM. The following example shows how to configure the standard Project Info Reports that display information from the POM in a friendly format:
+
+```unknown
 <project>
   ...
   <reporting>
@@ -75,32 +56,21 @@ Configuring Reports
   </reporting>
   ...
 </project>
-+-----------------+
+```
 
-  If you have included the appropriate <<<\<menu ref="reports"/\>>>> tag in your
-  {{{./sitedescriptor.html}site descriptor}}, then when you regenerate the site
-  those items will appear in a menu called "Project Reports".
+If you have included the appropriate `<menu ref="reports"/>` tag in your [site descriptor](./sitedescriptor.html), then when you regenerate the site those items will appear in a menu called &quot;Project Reports&quot;.
 
-  <<Note:>> Many report plugins provide a parameter called <<<outputDirectory>>>
-  or similar to specify the destination for their report outputs. This parameter
-  is only relevant if the report plugin is run standalone, i.e. by invocation
-  directly from the command line. In contrast, when reports are generated as
-  part of the site, the configuration of the Maven Site Plugin will determine
-  the effective output directory to ensure that all reports end up in a common
-  location.
+**Note:** Many report plugins provide a parameter called `outputDirectory` or similar to specify the destination for their report outputs. This parameter is only relevant if the report plugin is run standalone, i.e. by invocation directly from the command line. In contrast, when reports are generated as part of the site, the configuration of the Maven Site Plugin will determine the effective output directory to ensure that all reports end up in a common location.
 
-  Check out reporting plugins ("R" value in the "Type" column) in the {{{/plugins/}plugins page}},
-  for a list of available reporting plugins from Apache Maven Team.
+Check out reporting plugins \(&quot;R&quot; value in the &quot;Type&quot; column\) in the [plugins page](/plugins/), for a list of available reporting plugins from Apache Maven Team.
 
-Selecting Reports from a Plugin: Configuring Report Sets
+# Selecting Reports from a Plugin: Configuring Report Sets
 
-  By default, when you add a plugin in reporting section, <every> reporting goal available in the
-  plugin is rendered once.
+By default, when you add a plugin in reporting section, _every_ reporting goal available in the plugin is rendered once.
 
-  If you want to choose only some reports from a plugin, or if you want to run a report multiple times
-  with a different configuration, you need to configure report sets:
+If you want to choose only some reports from a plugin, or if you want to run a report multiple times with a different configuration, you need to configure report sets:
 
-+-----------------+
+```unknown
 <project>
   ...
   <reporting>
@@ -141,11 +111,9 @@ Selecting Reports from a Plugin: Configuring Report Sets
   </reporting>
   ...
 </project>
-+-----------------+
+```
+
+_Notice_: don&apos;t forget to define reportSets for plugins which provide aggregator reports, like maven-javadoc-plugin, maven-jxr-plugin or maven-checkstyle-plugin or you&apos;ll have these aggregate reports run by default in addition to non-aggregate reports.
 
-  <Notice>: don't forget to define reportSets for plugins which provide aggregator reports, like maven-javadoc-plugin,
-  maven-jxr-plugin or maven-checkstyle-plugin or you'll have these aggregate reports run by default in addition
-  to non-aggregate reports.
+See the [reportSet documentation in POM reference](/ref/current/maven-model/maven.html#class_reportSet) for complete description of available configurations.
 
-  See the {{{/ref/current/maven-model/maven.html#class_reportSet}reportSet documentation in POM reference}} for complete
-  description of available configurations.
diff --git a/src/site/markdown/examples/creating-content.md.vm b/src/site/markdown/examples/creating-content.md.vm
index cdf46f2e..54c13d14 100644
--- a/src/site/markdown/examples/creating-content.md.vm
+++ b/src/site/markdown/examples/creating-content.md.vm
@@ -1,44 +1,38 @@
- ------
- Creating Content
- ------
- Dennis Lundberg
- ------
- 2009-03-08
- ------
-
- ~~ 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
-
-
-Creating Content
-
-  Now it's time to create some content for your site. Site
-  content is structured by format, as several formats are supported.
-
-%{toc|section=1|fromDepth=2|toDepth=3}
-
-* Documentation formats
-
-  Here's an example of a directory structure for a site:
-
--------------------
+---
+title: Creating Content
+author: 
+  - Dennis Lundberg
+date: 2009-03-08
+---
+
+<!-- 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-->
+# Creating Content
+
+Now it&apos;s time to create some content for your site. Site content is structured by format, as several formats are supported.
+
+<!-- MACRO{toc|section=1|fromDepth=2|toDepth=3} -->
+## Documentation formats
+
+Here&apos;s an example of a directory structure for a site:
+
+```
 +- src/
    +- site/
       +- apt/
@@ -58,51 +52,20 @@ Creating Content
       |  +- xhtml-content.xhtml
       |
       +- site.xml
---------------------
-
- The <<<$\{basedir\}/src/site>>> directory which contains a site
- descriptor along with various directories corresponding to the supported
- document formats. Let's take a look at examples of the various document
- formats.
-
-  * APT:
-  The APT format ("Almost Plain Text") is a wiki-like format that allows you to
-  write simple, structured documents (like this one) very quickly. A full
-  reference of the
-  {{{/doxia/references/apt-format.html} APT Format}} is
-  available.
-
-  * FML:
-  The FML format is the FAQ format. This is the same that were used in Maven 1.x.
-  For more info about the
-  {{{/doxia/references/fml-format.html}FML Format}}
-  check the {{{/doxia/}Doxia}} site.
-
-  * XDoc:
-  The XDoc format is the same as
-  {{{/maven-1.x/using/site.html} used in Maven 1.x}}.
-  A reference for the
-  {{{/doxia/references/xdoc-format.html} XDoc Format}}
-  is available.
-
-  * Markdown (since maven-site-plugin 3.3):
-  {{{http://en.wikipedia.org/wiki/Markdown} Markdown}} is a widespread Markup language.
-
-  []
-
-  Other formats are available, but the above four are recognized by default by the site plugin.
-  Any other document format for which a Doxia parser exists can be used as well (see the list of
-  {{{/doxia/references/index.html}Doxia Markup Languages}}),
-  but in this case you need to add the corresponding Doxia dependency to your site plugin configuration, as
-  explained in the last paragraph.
-  Note that Doxia also supports several output formats, the site plugin only creates XHTML5.
-
-  Note that all of the above is optional - just one index file is required in
-  one of the input trees. The paths under each format will be merged together
-  to form the root directory of the site. After running '<<<mvn site:site>>>'
-  on the example above you will end up with this in your <<<target>>> directory:
-
--------------------
+```
+
+The `${basedir}/src/site` directory which contains a site descriptor along with various directories corresponding to the supported document formats. Let&apos;s take a look at examples of the various document formats.
+
+- APT: The APT format \(&quot;Almost Plain Text&quot;\) is a wiki-like format that allows you to write simple, structured documents \(like this one\) very quickly. A full reference of the [ APT Format](/doxia/references/apt-format.html) is available.
+- FML: The FML format is the FAQ format. This is the same that were used in Maven 1\.x. For more info about the [FML Format](/doxia/references/fml-format.html) check the [Doxia](/doxia/) site.
+- XDoc: The XDoc format is the same as [ used in Maven 1\.x](/maven-1.x/using/site.html). A reference for the [ XDoc Format](/doxia/references/xdoc-format.html) is available.
+- Markdown \(since maven-site-plugin 3\.3\): [ Markdown](http://en.wikipedia.org/wiki/Markdown) is a widespread Markup language.
+
+Other formats are available, but the above four are recognized by default by the site plugin. Any other document format for which a Doxia parser exists can be used as well \(see the list of [Doxia Markup Languages](/doxia/references/index.html)\), but in this case you need to add the corresponding Doxia dependency to your site plugin configuration, as explained in the last paragraph. Note that Doxia also supports several output formats, the site plugin only creates XHTML5\.
+
+Note that all of the above is optional - just one index file is required in one of the input trees. The paths under each format will be merged together to form the root directory of the site. After running &apos;`mvn site:site`&apos; on the example above you will end up with this in your `target` directory:
+
+```
 +- target/
    +- site/
       +- css/
@@ -114,27 +77,17 @@ Creating Content
       +- faq.html
       +- other.html
       +- xhtml-content.html
---------------------
-
-  This means that <<</src/site/apt/index.apt>>> will be available in the site as
-  <<</index.html>>>. So, in {{{./sitedescriptor.html} your site descriptor}} you
-  might link to <<</index.html>>> and <<</other.html>>>, where the source of
-  these two files would be <<</src/site/apt/index.apt>>> and
-  <<</src/site/xdoc/other.xdoc>>>.
+```
 
-  The <<<css>>> and <<<images>>> directories contain stylesheets and images
-  from the skin being used. You can read more about skins in
-  {{{./sitedescriptor.html}the site descriptor documentation}}.
+This means that `/src/site/apt/index.apt` will be available in the site as `/index.html`. So, in [ your site descriptor](./sitedescriptor.html) you might link to `/index.html` and `/other.html`, where the source of these two files would be `/src/site/apt/index.apt` and `/src/site/xdoc/other.xdoc`.
 
+The `css` and `images` directories contain stylesheets and images from the skin being used. You can read more about skins in [the site descriptor documentation](./sitedescriptor.html).
 
-* Adding Extra Resources
+## Adding Extra Resources
 
-  You can add any arbitrary resource to your site by including them in a
-  <<<resources>>> directory as shown below. Additional CSS files can be picked
-  up when they are placed in the <<<css>>> directory within the <<<resources>>>
-  directory.
+You can add any arbitrary resource to your site by including them in a `resources` directory as shown below. Additional CSS files can be picked up when they are placed in the `css` directory within the `resources` directory.
 
--------------------
+```
 +- src/
    +- site/
       +- resources/
@@ -143,67 +96,45 @@ Creating Content
          |
          +- images/
             +- pic1.jpg
---------------------
+```
 
-  The file <<<site.css>>> will be added to the default XHTML5 output, so it can
-  be used to adjust the default Maven stylesheets if desired.
+The file `site.css` will be added to the default XHTML5 output, so it can be used to adjust the default Maven stylesheets if desired.
 
-  The file <<<pic1.jpg>>> will be available via a relative reference to the
-  <<<images>>> directory from any page in your site.
+The file `pic1.jpg` will be available via a relative reference to the `images` directory from any page in your site.
 
+## Filtering
 
-* Filtering
+To filter properties into any supported documentation format, add a `.vm` extension to the filename.
 
-  To filter properties into any supported documentation format, add a <<<.vm>>>
-  extension to the filename.
+For example, the module for the Maven website contains a [`content/xdoc/download.xml.vm`](http://svn.apache.org/repos/asf/maven/site/trunk/content/xdoc/download.xml.vm) file, which uses the expression `${currentStableVersion}` to filter in a property set in the [POM](http://svn.apache.org/repos/asf/maven/site/trunk/pom.xml).
 
-  For example, the module for the Maven website contains a
-  {{{http://svn.apache.org/repos/asf/maven/site/trunk/content/xdoc/download.xml.vm}<<<content/xdoc/download.xml.vm>>>}}
-  file, which uses the expression <<<$\{currentStableVersion}>>> to filter in a
-  property set in the
-  {{{http://svn.apache.org/repos/asf/maven/site/trunk/pom.xml}POM}}.
+**Note:** [Apache Velocity](http://velocity.apache.org/) is used to apply the filtering.
 
-  <<Note:>> {{{http://velocity.apache.org/}Apache Velocity}} is used to apply the filtering.
+Some properties are defined by default: see [ Doxia Site Renderer&apos;s Velocity processing reference](/doxia/doxia-sitetools/doxia-site-renderer/#Velocity_processing) for more information. For a complete usage overview, see Velocity&apos;s [user guide](http://velocity.apache.org/engine/devel/user-guide.html).
 
-  Some properties are defined by default: see
-  {{{/doxia/doxia-sitetools/doxia-site-renderer/#Velocity_processing} Doxia Site Renderer's Velocity processing reference}}
-  for more information. For a complete usage overview, see Velocity's {{{http://velocity.apache.org/engine/devel/user-guide.html}user guide}}.
+Since version 3\.5, you can save processed markup by setting `saveProcessedContent` to `true`: see [corresponding documentation](../site-mojo.html#saveProcessedContent) for more details.
 
-  Since version 3.5, you can save processed markup by setting <<<saveProcessedContent>>> to <<<true>>>: see
-  {{{../site-mojo.html#saveProcessedContent}corresponding documentation}} for more details.
+### Common Issues and Workarounds
 
-** Common Issues and Workarounds
+- **dotted properties**:
 
-  * <<dotted properties>>:
+    As Velocity uses a dot-notation to traverse beans, you **cannot** use dotted properties defined in `<properties>` directly.
 
-  As Velocity uses a dot-notation to traverse beans, you <<cannot>>
-  use dotted properties defined in <<<\<properties\>>>> directly.
+    It is generally advised to access properties by using the `$<a id="esc.d"></a>esc.dcontext` tool: e.g., with `$<a id="esc.d"></a>esc.dcontext.get("my.property")`.
 
-  It is generally advised to access properties by using the <<<${esc.d}context>>> tool:
-  e.g., with <<<${esc.d}context.get("my.property")>>>.
+- **Markdown conflict with Velocity on $<a id="esc.h"></a>esc.h$<a id="esc.h"></a>esc.h syntax**:
 
-  * <<Markdown conflict with Velocity on ${esc.h}${esc.h} syntax>>:
+    Since `$<a id="esc.h"></a>esc.h$<a id="esc.h"></a>esc.h` denotes a [single line comment](https://velocity.apache.org/engine/2.3/vtl-reference.html#single-line-comments) in Velocity, Markdown headers using this syntax are suppressed from generated content.
 
-  Since <<<${esc.h}${esc.h}>>> denotes a
-  {{{https://velocity.apache.org/engine/2.3/vtl-reference.html#single-line-comments}single line comment}} in Velocity,
-  Markdown headers using this syntax are suppressed from generated content.
+    You can use [unparsed content syntax](https://velocity.apache.org/engine/2.3/vtl-reference.html#unparsed-content) `$<a id="esc.h"></a>esc.h[[#[[##]]#]]$<a id="esc.h"></a>esc.h` or [escape tool](https://velocity.apache.org/tools/3.1/apidocs/org/apache/velocity/tools/generic/EscapeTool.html) like `$<a id="esc.d"></a>esc.d{esc.h}$<a id="esc.d"></a>esc.d{esc.h}`.
 
-  You can use {{{https://velocity.apache.org/engine/2.3/vtl-reference.html#unparsed-content}unparsed content syntax}}
-  <<<${esc.h}[[#[[##]]#]]${esc.h}>>> or
-  {{{https://velocity.apache.org/tools/3.1/apidocs/org/apache/velocity/tools/generic/EscapeTool.html}escape tool}}
-  like <<<${esc.d}\{esc.h\}${esc.d}\{esc.h\}>>>.
+## Internationalization
 
-* Internationalization
+Internationalization in Maven is very simple, as long as the reports you are using have that particular locale defined. For an overview of supported languages and instructions on how to add further languages, please see the related article [ Internationalization](../i18n.html).
 
-  Internationalization in Maven is very simple, as long as the reports you are
-  using have that particular locale defined. For an overview of supported
-  languages and instructions on how to add further languages, please see the
-  related article {{{../i18n.html} Internationalization}}.
+To enable multiple locales, or languages, add a configuration similar to the following to your POM:
 
-  To enable multiple locales, or languages, add a configuration similar to the
-  following to your POM:
-
-+------------------
+```unknown
 <project>
   ...
   <build>
@@ -220,18 +151,13 @@ Creating Content
   </build>
   ...
 </project>
-+------------------
+```
 
-  This will generate both a default (<<<Locale#ROOT>>>) and a French version of the site.
-  It will be generated at the root of the site, with a copy of the French
-  translation of the site in the <<<fr/>>> subdirectory.
+This will generate both a default \(`Locale#ROOT`\) and a French version of the site. It will be generated at the root of the site, with a copy of the French translation of the site in the `fr/` subdirectory.
 
-  To add your own content for that translation instead of using the default,
-  create a subdirectory with that locale's name in your site directory and
-  create a new site descriptor with the name of the locale in the file name.
-  For example:
+To add your own content for that translation instead of using the default, create a subdirectory with that locale&apos;s name in your site directory and create a new site descriptor with the name of the locale in the file name. For example:
 
--------------------
+```
 +- src/
    +- site/
       +- apt/
@@ -243,7 +169,7 @@ Creating Content
       |
       +- site.xml         (Default site descriptor)
       +- site_fr.xml      (French site descriptor)
---------------------
+```
+
+With one site descriptor per language, the translated site\(s\) can evolve independently.
 
-  With one site descriptor per language, the translated site(s) can evolve
-  independently.
diff --git a/src/site/markdown/examples/creatingskins.md b/src/site/markdown/examples/creatingskins.md
index ce5267a6..db1c4726 100644
--- a/src/site/markdown/examples/creatingskins.md
+++ b/src/site/markdown/examples/creatingskins.md
@@ -1,87 +1,66 @@
- ------
- Creating Skins
- ------
- Brett Porter
- Dennis Lundberg
- ------
- 2009-03-08
- ------
+---
+title: Creating Skins
+author: 
+  - Brett Porter
+  - Dennis Lundberg
+date: 2009-03-08
+---
 
- ~~ 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-->
+<!---->
+<!--   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-->
+# Creating Skins
 
- ~~ NOTE: For help with the syntax of this file, see:
- ~~ http://maven.apache.org/doxia/references/apt-format.html
+If you want to tune the way your site looks, you can use a custom skin to provide your own CSS stylesheets. If that is still not enough, you can even tweak the output templates that Maven uses to generate the site documentation.
 
+For an in-depth discussion of site customization, please have a look at [ Maven: The Complete Reference, Chapter 10\. Site Generation](http://books.sonatype.com/mvnref-book/reference/site-generation.html) provided by Sonatype.
 
-Creating Skins
+## About
 
-  If you want to tune the way your site looks, you can use a custom skin to
-  provide your own CSS stylesheets. If that is still not enough, you can even tweak
-  the output templates that Maven uses to generate the site documentation.
+A skin contains the following elements:
 
-  For an in-depth discussion of site customization, please have a look at
-  {{{http://books.sonatype.com/mvnref-book/reference/site-generation.html} Maven: The Complete Reference, Chapter 10. Site Generation}}
-  provided by Sonatype.
+- Resources to copy into each project \(such as images used by the CSS\)
+- A couple of CSS files, containing the visual styling
+- A Velocity template in `/META-INF/maven/site.vm` for an alternate HTML rendering of the site.
+- Since Maven Site Plugin 3\.5, an optional [skin descriptor](/doxia/doxia-sitetools/doxia-skin-model/index.html) in `/META-INF/maven/skin.xml` containing meta-data about the skin
+## Maven Site Skin Archetype
 
-* About
+[`maven-archetype-site-skin` archetype](/archetypes/maven-archetype-site-skin/) can be used to easily create a complete new skin project, including its dedicated `/META-INF/maven/site.vm`.
 
-  A skin contains the following elements:
+## Building
 
-    * Resources to copy into each project (such as images used by the CSS)
+A skin is built like any other JAR - with a `packaging` of `jar`. No additional plugins are needed.
 
-    * A couple of CSS files, containing the visual styling
+Resources should be put in the normal `src/main/resources` directory.
 
-    * A Velocity template in <<</META-INF/maven/site.vm>>> for an alternate HTML rendering of the site.
+Once the JAR is built and deployed, it can be used by projects.
 
-    * Since Maven Site Plugin 3.5, an optional {{{/doxia/doxia-sitetools/doxia-skin-model/index.html}skin descriptor}}
-    in <<</META-INF/maven/skin.xml>>> containing meta-data about the skin
+## Constructing the CSS
 
-* Maven Site Skin Archetype
+<!-- @todo More information is needed here on constructing the CSS-->
 
-  {{{/archetypes/maven-archetype-site-skin/}<<<maven-archetype-site-skin>>> archetype}} can be used to easily create a complete
-  new skin project, including its dedicated <<</META-INF/maven/site.vm>>>.
+If you are interested in constructing your own CSS, it is recommended that you copy the file [`maven-theme.css`](https://github.com/apache/maven-default-skin/tree/master/src/main/resources/css/maven-theme.css) from Maven Default Skin and modify it to suit your needs.
 
-* Building
+## Customizing the HTML Output with a Velocity Template
 
-  A skin is built like any other JAR - with a <<<packaging>>> of <<<jar>>>.
-  No additional plugins are needed.
+The format of the Velocity template is currently out of scope for this document.
 
-  Resources should be put in the normal <<<src/main/resources>>> directory.
+For more information about how to write Velocity templates see the [Velocity User Guide](https://velocity.apache.org/engine/2.3/user-guide.html) and [Velocity Template Language Reference Guide](https://velocity.apache.org/engine/2.3/vtl-reference.html).
 
-  Once the JAR is built and deployed, it can be used by projects.
+Notice that Velocity 2\.3 is used since Maven Site Plugin 4\.0\.0-M2, but version 1\.7 was used previously.
 
-* Constructing the CSS
-
-~~ @todo More information is needed here on constructing the CSS
-
-  If you are interested in constructing your own CSS, it is recommended that
-  you copy the file
-  {{{https://github.com/apache/maven-default-skin/tree/master/src/main/resources/css/maven-theme.css}<<<maven-theme.css>>>}}
-  from Maven Default Skin and modify it to suit your needs.
-
-* Customizing the HTML Output with a Velocity Template
-
-  The format of the Velocity template is currently out of scope for this
-  document.
-
-  For more information about how to write Velocity templates see the
-  {{{https://velocity.apache.org/engine/2.3/user-guide.html}Velocity User Guide}}
-  and
-  {{{https://velocity.apache.org/engine/2.3/vtl-reference.html}Velocity Template Language Reference Guide}}.
-
-  Notice that Velocity 2.3 is used since Maven Site Plugin 4.0.0-M2, but version 1.7 was used previously.
diff --git a/src/site/markdown/examples/inheritance-site-distribution-management.md b/src/site/markdown/examples/inheritance-site-distribution-management.md
index 90ef3ff8..0bc2997e 100644
--- a/src/site/markdown/examples/inheritance-site-distribution-management.md
+++ b/src/site/markdown/examples/inheritance-site-distribution-management.md
@@ -1,66 +1,54 @@
- ------
- Inheritance of Site Distribution Management
- ------
-Matthias Bünger
- ------
- 2024-07-07
- ------
+---
+title: Inheritance of Site Distribution Management
+author: 
+  - Matthias Bünger
+date: 2024-07-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.
+<!-- 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-->
+# Inheritance of the Site Distribution Management
 
- ~~ NOTE: For help with the syntax of this file, see:
- ~~ http://maven.apache.org/doxia/references/apt-format.html
+Inside your POM you can not only configure the `distributionManagement` for the releases and snapshots of your project, but also where to deploy your site when using the [`site:deploy`](../deploy-mojo.html) goal. The following configuration would deploy the project&apos;s site to a local directory called `bar`.
 
-
-Inheritance of the Site Distribution Management
-
-  Inside your POM you can not only configure the <<<distributionManagement>>> for the releases and snapshots
-  of your project, but also where to deploy your site when using the <<<{{{../deploy-mojo.html}site:deploy}}>>>
-  goal. The following configuration would deploy the project's site to a local directory called <<<bar>>>.
-
-+-----+
+```unknown
 <distributionManagement>
   <site>
       <id>local</id>
       <url>file:///C:/foo/bar</url>
   </site>
 </distributionManagement>
-+-----+
+```
 
-  The content of this directory would look similar to the following after your deployment:
+The content of this directory would look similar to the following after your deployment:
 
------
+```
 bar/ (root of site)
 ├── css
 └── report.html
------
+```
 
-  You see that all files are placed directly inside the directory and that no subdirectory named after the <<<artifactId>>> is created.
-  That's a small, but important difference in comparison how the regular <<<deploy>>> phase of the build lifecycle works
-  where always a subdirectory is created for each project. So you have to be aware not to use the exact same value
-  for the site for multiple projects, as otherwise files of the first deployed project will be overwritten by the files
-  of the second deployed one and so on.
+You see that all files are placed directly inside the directory and that no subdirectory named after the `artifactId` is created. That&apos;s a small, but important difference in comparison how the regular `deploy` phase of the build lifecycle works where always a subdirectory is created for each project. So you have to be aware not to use the exact same value for the site for multiple projects, as otherwise files of the first deployed project will be overwritten by the files of the seco [...]
 
-  To handle this easily you can use a the same parent POM with each of your projects.
-  When using a parent POM with a project, the site configuration is inherited from the parent, but each child project
-  is located in a subdirectory with its <<<artifactId>>> name, resulting in a structure like in the following example:
+To handle this easily you can use a the same parent POM with each of your projects. When using a parent POM with a project, the site configuration is inherited from the parent, but each child project is located in a subdirectory with its `artifactId` name, resulting in a structure like in the following example:
 
------
+```
 bar/ (root of site)
 ├── css
 ├── project-A
@@ -70,7 +58,7 @@ bar/ (root of site)
 │   ├── css
 │   └── report.html
 └── report.html
------
+```
+
+As you can see the site content of the parent POM is located in the root of the site directory, while the content of each project using the parent POM \(called &quot;project-A&quot; and &quot;project-B&quot; in the example\) is located inside a subdirectory.
 
-  As you can see the site content of the parent POM is located in the root of the site directory, while the content of
-  each project using the parent POM (called "project-A" and "project-B" in the example) is located inside a subdirectory.
diff --git a/src/site/markdown/examples/moduleexcludes.md.vm b/src/site/markdown/examples/moduleexcludes.md.vm
index e4dfc794..b15c4c93 100644
--- a/src/site/markdown/examples/moduleexcludes.md.vm
+++ b/src/site/markdown/examples/moduleexcludes.md.vm
@@ -1,39 +1,35 @@
- ------
- Excluding Document Formats
- ------
- Maria Odea Ching
- ------
- 2009-03-08
- ------
+---
+title: Excluding Document Formats
+author: 
+  - Maria Odea Ching
+date: 2009-03-08
+---
 
- ~~ 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-->
+<!---->
+<!--   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-->
+# Excluding Document Formats
 
- ~~ NOTE: For help with the syntax of this file, see:
- ~~ http://maven.apache.org/doxia/references/apt-format.html
+To exclude specific document formats from the generated site, you can use the `moduleExcludes` parameter.
 
+For example, you have the following site content in your POM
 
-Excluding Document Formats
-
-  To exclude specific document formats from the generated site, you can use the <<<moduleExcludes>>> parameter.
-
-  For example, you have the following site content in your POM
-
------
+```
 Module1
 |-- src
 |   |-- main
@@ -43,13 +39,11 @@ Module1
 |       `-- fml
 |           `-- sample-fml.fml
 `-- pom.xml
------
+```
 
-  and you want to exclude all the documents in the fml format from the
-  generated site, you need to set the following in your POM and then execute
-  "<<<mvn site>>>".
+and you want to exclude all the documents in the fml format from the generated site, you need to set the following in your POM and then execute &quot;`mvn site`&quot;.
 
-+-----+
+```unknown
 <project>
   ...
   <build>
@@ -68,9 +62,9 @@ Module1
   </build>
   ...
 </project>
-+-----+
+```
+
+You will see that no `sample-fml.html` will be present in the generated site.
 
-  You will see that no <<<sample-fml.html>>> will be present in the generated site.
+See the documentation of the [moduleExcludes](../site-mojo.html#moduleExcludes) Mojo parameter for more details.
 
-  See the documentation of the {{{../site-mojo.html#moduleExcludes}moduleExcludes}}
-  Mojo parameter for more details.
\ No newline at end of file
diff --git a/src/site/markdown/examples/multimodule.md b/src/site/markdown/examples/multimodule.md
index be59930d..d12b35ea 100644
--- a/src/site/markdown/examples/multimodule.md
+++ b/src/site/markdown/examples/multimodule.md
@@ -1,103 +1,62 @@
- ------
- Multi-module Sites
- ------
- Vincent Siveton
- <vi...@gmail.com>
- Maria Odea Ching
- Dennis Lundberg
- Lukas Theussl
- ------
- 2011-01-18
- ------
-
- ~~ 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
-
-
-Building multi-module sites
-
-  When running <<<mvn site>>> on a top level project, Maven will build all sites for every module
-  defined in the <<<modules>>> section of the pom individually. Note that each site is
-  generated in each individual project's target location. As a result, relative links between
-  different modules will NOT work. They will however work when you deploy or stage the site.
-
-* Staging and deploying
-
-  To preview the whole tree of a multi-module site, you can use the
-  <<<{{{../stage-mojo.html}site:stage}}>>> goal. This will
-  copy individual sites to their proper place at the staging location.
-
-  <<<{{{../deploy-mojo.html}site:deploy}}>>> does the same thing as <<<site:stage>>>,
-  but uses the url defined in the <<<\<distributionManagement\>>>> element of the pom
-  as deployment location. This is usually a remote url, but both remote protocols like
-  <<<scp>>> and local protocols like <<<file>>> are supported.
-
-  Finally, <<<{{{../stage-deploy-mojo.html}site:stage-deploy}}>>> does the same thing as
-  <<<site:deploy>>> but uses the <<<stagingDirectory>>> parameter as deployment location.
-  This can be used to deploy the site to a remote staging area (<<<site:stage>>> is always local).
-
-  <<Notes:>>
-
-  * If subprojects inherit the (distribution) site URL from a parent POM, they will automatically
-  append their <artifactId> to form their effective deployment location.
-  This goes for both the project url and the url defined in the
-  <<<\<distributionManagement\>>>> element of the pom.
-
-  * If your multi-module tree does not
-  follow the Maven conventions, or if module directories are named differently than
-  module artifacts, you have to specify the url's for <<each>> child project.
-  See also <<<{{{../faq.html#Use_of_url}How does the Site Plugin use the \<url\> element in the POM?}}>>>.
-
-  * The pom.xml of the topmost project in a multi-module build must define the distributionManagement URL
-  element (called "rootURL" hereafter). The rootURL must be the topmost distributionManagement URL
-  in the multi-module project, implying that any distributionManagement URL defined within another
-  project in a multimodule build must start with the rootURL and append unique paths
-  (to be situated "below" the rootURL).
-
-  * All projects in multi-module builds must define unique distributionManagement url elements,
-  below/under the root distributionManagement URL in terms of URL path.
-
-  * If the artifactId and module name (i.e. directory name) are not identical for any project within a
-  multi-module build, the distributionManagement URL element must be defined in the pom.xml file in the project.
-
-* Inheritance
-
-  Site descriptors are inherited along the same lines as project descriptors
-  are. If you want your project's site descriptor to be inherited, you need to
-  attach it to the project's main artifact. You use the
-  <<<{{{../attach-descriptor-mojo.html}site:attach-descriptor}}>>>
-  goal to attach the site descriptor to your project's main artifact.
-
-  In Maven 3 you must attach the site descriptor yourself, even for projects
-  with packaging set to "pom".
-
-  By default, all the parent descriptor settings are inherited with the only exception of menus, see below.
-  From the body, the links and breadcrumbs accumulate to contain all the parent's
-  site descriptor links and breadcrumbs.
-  If the parent contains some breadcrumb and the inheriting site descriptor doesn't,
-  a breadcrumb with the current site descriptor's name will be added automatically.
-
-  However, it is possible to inherit menus as well. To do so, use the <<<inherit>>> attribute in the site descriptor. This can
-  be either <<<top>>> or <<<bottom>>>, indicating where the inherited menu will be placed. For example:
-
-+-----+
+---
+title: Multi-module Sites
+author: 
+  - Vincent Siveton
+  - _vincent.siveton@gmail.com_
+  - Maria Odea Ching
+  - Dennis Lundberg
+  - Lukas Theussl
+date: 2011-01-18
+---
+
+<!-- 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-->
+# Building multi-module sites
+
+When running `mvn site` on a top level project, Maven will build all sites for every module defined in the `modules` section of the pom individually. Note that each site is generated in each individual project&apos;s target location. As a result, relative links between different modules will NOT work. They will however work when you deploy or stage the site.
+
+## Staging and deploying
+
+To preview the whole tree of a multi-module site, you can use the [`site:stage`](../stage-mojo.html) goal. This will copy individual sites to their proper place at the staging location.
+
+[`site:deploy`](../deploy-mojo.html) does the same thing as `site:stage`, but uses the url defined in the `<distributionManagement>` element of the pom as deployment location. This is usually a remote url, but both remote protocols like `scp` and local protocols like `file` are supported.
+
+Finally, [`site:stage-deploy`](../stage-deploy-mojo.html) does the same thing as `site:deploy` but uses the `stagingDirectory` parameter as deployment location. This can be used to deploy the site to a remote staging area \(`site:stage` is always local\).
+
+**Notes:**
+
+- If subprojects inherit the \(distribution\) site URL from a parent POM, they will automatically append their _artifactId_ to form their effective deployment location. This goes for both the project url and the url defined in the `<distributionManagement>` element of the pom.
+- If your multi-module tree does not follow the Maven conventions, or if module directories are named differently than module artifacts, you have to specify the url&apos;s for **each** child project. See also [`How does the Site Plugin use the <url> element in the POM?`](../faq.html#Use_of_url).
+- The pom.xml of the topmost project in a multi-module build must define the distributionManagement URL element \(called &quot;rootURL&quot; hereafter\). The rootURL must be the topmost distributionManagement URL in the multi-module project, implying that any distributionManagement URL defined within another project in a multimodule build must start with the rootURL and append unique paths \(to be situated &quot;below&quot; the rootURL\).
+- All projects in multi-module builds must define unique distributionManagement url elements, below/under the root distributionManagement URL in terms of URL path.
+- If the artifactId and module name \(i.e. directory name\) are not identical for any project within a multi-module build, the distributionManagement URL element must be defined in the pom.xml file in the project.
+## Inheritance
+
+Site descriptors are inherited along the same lines as project descriptors are. If you want your project&apos;s site descriptor to be inherited, you need to attach it to the project&apos;s main artifact. You use the [`site:attach-descriptor`](../attach-descriptor-mojo.html) goal to attach the site descriptor to your project&apos;s main artifact.
+
+In Maven 3 you must attach the site descriptor yourself, even for projects with packaging set to &quot;pom&quot;.
+
+By default, all the parent descriptor settings are inherited with the only exception of menus, see below. From the body, the links and breadcrumbs accumulate to contain all the parent&apos;s site descriptor links and breadcrumbs. If the parent contains some breadcrumb and the inheriting site descriptor doesn&apos;t, a breadcrumb with the current site descriptor&apos;s name will be added automatically.
+
+However, it is possible to inherit menus as well. To do so, use the `inherit` attribute in the site descriptor. This can be either `top` or `bottom`, indicating where the inherited menu will be placed. For example:
+
+```unknown
 <project>
   ...
   <body>
@@ -109,17 +68,15 @@ Building multi-module sites
   </body>
   ...
 </project>
-+-----+
+```
 
-* Aggregate Reports
+## Aggregate Reports
 
-  Some reports can be run against the sum of every modules: these are aggregate reports. This is the case of
-  maven-javadoc-plugin, maven-jxr-plugin or maven-checkstyle-plugin.
+Some reports can be run against the sum of every modules: these are aggregate reports. This is the case of maven-javadoc-plugin, maven-jxr-plugin or maven-checkstyle-plugin.
 
-  To benefit from aggregate reports, you must configure a reportSet in the parent pom, and turn inheritance off to avoid
-  the aggregate report to be run in modules. For example, with maven-jxr-report:
+To benefit from aggregate reports, you must configure a reportSet in the parent pom, and turn inheritance off to avoid the aggregate report to be run in modules. For example, with maven-jxr-report:
 
-+--------------+
+```unknown
 <project>
   ...
   <reporting>
@@ -142,4 +99,5 @@ Building multi-module sites
   </reporting>
   ...
 </project>
-+--------------+
+```
+
diff --git a/src/site/markdown/examples/site-deploy-to-sourceforge.net.md b/src/site/markdown/examples/site-deploy-to-sourceforge.net.md
index a98fe102..91159644 100644
--- a/src/site/markdown/examples/site-deploy-to-sourceforge.net.md
+++ b/src/site/markdown/examples/site-deploy-to-sourceforge.net.md
@@ -1,79 +1,66 @@
- ------
- Deploying to sourceforge.net
- ------
- Barrie Treloar
- ------
- 2009-03-08
- ------
-
-~~ 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
-
-Deploying to sourceforge.net
-
-  This {{{http://sourceforge.net/community/forum/topic.php?id=3518&page}sf.net announcement}} indicates that the
-  new hostname for project web file management has changed. The new hostname for file management is:
-  <<<web.sourceforge.net>>> and
-  the new accepted methods are: SFTP, SCP, rsync over SSH. Unfortunately <<<web.sourceforge.net>>> also has a restricted
-  shell environment and does not allow remote commands to be executed.
-
-  In addition shell access to <<<shell.sourceforge.net>>> now requires the creation of a shell before it can be
-  accessed.
-
-  Both of these mean that if you attempt to deploy your site without following these steps you will get an error.
-
-* Quick Start
-
-  * Create a shell on <<<shell.sourceforge.net>>> with your username and project group
-
 ---
-ssh -t <username>,<project name>@shell.sf.net create
+title: Deploying to sourceforge.net
+author: 
+  - Barrie Treloar
+date: 2009-03-08
 ---
 
-  * Use <<<shell.sourceforge.net>>> (instead of <<<web.sourceforge.net>>>) in you site URL
-
-+---
-  ...
-  <distributionManagement>
-    ...
-    <site>
-      <id>your_project.sf.net</id>
-      <url>scp://shell.sourceforge.net/home/project-web/your_project/htdocs</url>
-    </site>
-  </distributionManagement>
-+---
-
-  * Run <<<mvn site:deploy>>>
-
-  * Verify that you have a working web site by opening a browser to <<<http://your_project.sf.net>>>
-
-  []
-
-* Detailed Instructions with Examples
-
-  The following examples will use the <<<qifcon>>> project and the user <<<barrie>>>.
-  Substitute these with your own project name and user name.
-
-** Create a shell on <<<shell.sourceforge.net>>> with your username and project group
-
------
+<!-- 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-->
+# Deploying to sourceforge.net
+
+This [sf.net announcement](http://sourceforge.net/community/forum/topic.php?id=3518&page) indicates that the new hostname for project web file management has changed. The new hostname for file management is: `web.sourceforge.net` and the new accepted methods are: SFTP, SCP, rsync over SSH. Unfortunately `web.sourceforge.net` also has a restricted shell environment and does not allow remote commands to be executed.
+
+In addition shell access to `shell.sourceforge.net` now requires the creation of a shell before it can be accessed.
+
+Both of these mean that if you attempt to deploy your site without following these steps you will get an error.
+
+## Quick Start
+
+- Create a shell on `shell.sourceforge.net` with your username and project group
+
+    ```
+    ssh -t <username>,<project name>@shell.sf.net create
+    ```
+
+- Use `shell.sourceforge.net` \(instead of `web.sourceforge.net`\) in you site URL
+
+    ```unknown
+      ...
+      <distributionManagement>
+        ...
+        <site>
+          <id>your_project.sf.net</id>
+          <url>scp://shell.sourceforge.net/home/project-web/your_project/htdocs</url>
+        </site>
+      </distributionManagement>
+    ```
+
+- Run `mvn site:deploy`
+- Verify that you have a working web site by opening a browser to `http://your_project.sf.net`
+## Detailed Instructions with Examples
+
+The following examples will use the `qifcon` project and the user `barrie`. Substitute these with your own project name and user name.
+
+### Create a shell on `shell.sourceforge.net` with your username and project group
+
+```
 $ ssh -t barrie,qifcon@shell.sf.net create
 barrie,qifcon@shell.sf.net's password:
 
@@ -86,13 +73,13 @@ Use the "shutdown" command to destroy the shell before the time limit.
 For path information and login help, type "sf-help".
 
 -bash-3.2$
------
+```
 
-** Use <<<shell.sourceforge.net>>> (instead of <<<web.sourceforge.net>>>) in you site URL
+### Use `shell.sourceforge.net` \(instead of `web.sourceforge.net`\) in you site URL
 
-  In the project's <<<pom.xml>>>:
+In the project&apos;s `pom.xml`:
 
-+---+
+```unknown
   ...
   <distributionManagement>
     ...
@@ -102,11 +89,11 @@ For path information and login help, type "sf-help".
     </site>
   </distributionManagement>
   ...
-+---+
+```
 
-** Run <<<mvn site:deploy>>>
+### Run `mvn site:deploy`
 
------
+```
 C:\ide\Finance\qifcon\site>mvn site:deploy
 [INFO] Scanning for projects...
 [INFO] Searching repository for plugin with prefix: 'site'.
@@ -135,105 +122,99 @@ scp://shell.sourceforge.net/home/groups/q/qi/qifcon/htdocs - Session: Disconnect
 [INFO] Finished at: Sat Nov 08 08:09:40 CST 2008
 [INFO] Final Memory: 6M/11M
 [INFO] ------------------------------------------------------------------------
------
-
-** Verify you have a working web site
+```
 
-  Open a browser to <<<http://qifcon.sf.net>>>.
+### Verify you have a working web site
 
+Open a browser to `http://qifcon.sf.net`.
 
-* Troubleshooting
+## Troubleshooting
 
-** Trying to deploy to <<<web.sourceforge.net>>>
+### Trying to deploy to `web.sourceforge.net`
 
-  The accepted methods for deploying to <<<web.sourceforge.net>>> are: SFTP, SCP, rsync over SSH.
+The accepted methods for deploying to `web.sourceforge.net` are: SFTP, SCP, rsync over SSH.
 
-  This will mean that the zipped archive created by Wagon can be uploaded, but the commands
-  that Wagon uses to create directories, unzip and chmod files will fail silently.
+This will mean that the zipped archive created by Wagon can be uploaded, but the commands that Wagon uses to create directories, unzip and chmod files will fail silently.
 
-  There are two types of failures:
+There are two types of failures:
 
-  [[1]] No such file or directory
+1. No such file or directory
 
-    This will occur if you are deploying into a subdirectory that does not yet exist.
-    The cause is that the <<<mkdir>>> command has failed silently.
+    This will occur if you are deploying into a subdirectory that does not yet exist. The cause is that the `mkdir` command has failed silently.
 
     An example of this error:
 
------
-C:\ide\Finance\qifcon\site>mvn site:deploy
-[INFO] Scanning for projects...
-[INFO] Searching repository for plugin with prefix: 'site'.
-[INFO] ------------------------------------------------------------------------
-[INFO] Building QifCon
-[INFO]    task-segment: [site:deploy]
-[INFO] ------------------------------------------------------------------------
-[INFO] [site:deploy]
-Using private key: C:\Projects\putty\barrie@sourceforge-net.openssh
-scp://web.sourceforge.net/home/groups/q/qi/qifcon/htdocs/site - Session: Opened
-Executing command: mkdir -p /home/groups/q/qi/qifcon/htdocs/site/.
-Executing command: mkdir -p /home/groups/q/qi/qifcon/htdocs/site/.
-Executing command: scp -t /home/groups/q/qi/qifcon/htdocs/site/./wagon12736.zip
-scp://web.sourceforge.net/home/groups/q/qi/qifcon/htdocs/site - Session: Disconnecting
-scp://web.sourceforge.net/home/groups/q/qi/qifcon/htdocs/site - Session: Disconnected
-[INFO] ------------------------------------------------------------------------
-[ERROR] BUILD ERROR
-[INFO] ------------------------------------------------------------------------
-[INFO] Error uploading site
-
-Embedded error: SCP terminated with error: 'scp: /home/groups/q/qi/qifcon/htdocs/site/./wagon12736.zip: No such file or directory'
-[INFO] ------------------------------------------------------------------------
-[INFO] For more information, run Maven with the -e switch
-[INFO] ------------------------------------------------------------------------
-[INFO] Total time: 15 seconds
-[INFO] Finished at: Sat Nov 08 07:27:34 CST 2008
-[INFO] Final Memory: 6M/11M
-[INFO] ------------------------------------------------------------------------
------
-
-  [[2]] Unable to unzip the zip file created by Wagon
-
-    If the directory exists then the Wagon zip file can be uploaded and <<<site:deploy>>> will appear to
-    succeed, but the web site will not work since the Wagon zip file can not be unzipped.
-
------
-C:\ide\Finance\qifcon\site>mvn site:deploy
-[INFO] Scanning for projects...
-[INFO] Searching repository for plugin with prefix: 'site'.
-[INFO] ------------------------------------------------------------------------
-[INFO] Building QifCon
-[INFO]    task-segment: [site:deploy]
-[INFO] ------------------------------------------------------------------------
-[INFO] [site:deploy]
-Using private key: C:\Projects\putty\barrie@sourceforge-net.openssh
-scp://web.sourceforge.net/home/groups/q/qi/qifcon/htdocs/site - Session: Opened
-Executing command: mkdir -p /home/groups/q/qi/qifcon/htdocs/site/.
-Executing command: mkdir -p /home/groups/q/qi/qifcon/htdocs/site/.
-Executing command: scp -t /home/groups/q/qi/qifcon/htdocs/site/./wagon21889.zip
-Uploading: ./wagon21889.zip to scp://web.sourceforge.net/home/groups/q/qi/qifcon/htdocs/site
-
-########################
-Transfer finished. 95979 bytes copied in 1.872 seconds
-Executing command: cd /home/groups/q/qi/qifcon/htdocs/site/.; unzip -q -o wagon21889.zip; rm -f wagon21889.zip
-Executing command: chmod -Rf g+w,a+rX /home/groups/q/qi/qifcon/htdocs/site
-scp://web.sourceforge.net/home/groups/q/qi/qifcon/htdocs/site - Session: Disconnecting
-scp://web.sourceforge.net/home/groups/q/qi/qifcon/htdocs/site - Session: Disconnected
-[INFO] ------------------------------------------------------------------------
-[INFO] BUILD SUCCESSFUL
-[INFO] ------------------------------------------------------------------------
-[INFO] Total time: 18 seconds
-[INFO] Finished at: Sat Nov 08 07:51:04 CST 2008
-[INFO] Final Memory: 6M/11M
-[INFO] ------------------------------------------------------------------------
------
-
-  []
-
-** No shell created error
-
-  If you try to run <<<ssh>>> without first creating a shell you will get the following error:
-
------
+    ```
+    C:\ide\Finance\qifcon\site>mvn site:deploy
+    [INFO] Scanning for projects...
+    [INFO] Searching repository for plugin with prefix: 'site'.
+    [INFO] ------------------------------------------------------------------------
+    [INFO] Building QifCon
+    [INFO]    task-segment: [site:deploy]
+    [INFO] ------------------------------------------------------------------------
+    [INFO] [site:deploy]
+    Using private key: C:\Projects\putty\barrie@sourceforge-net.openssh
+    scp://web.sourceforge.net/home/groups/q/qi/qifcon/htdocs/site - Session: Opened
+    Executing command: mkdir -p /home/groups/q/qi/qifcon/htdocs/site/.
+    Executing command: mkdir -p /home/groups/q/qi/qifcon/htdocs/site/.
+    Executing command: scp -t /home/groups/q/qi/qifcon/htdocs/site/./wagon12736.zip
+    scp://web.sourceforge.net/home/groups/q/qi/qifcon/htdocs/site - Session: Disconnecting
+    scp://web.sourceforge.net/home/groups/q/qi/qifcon/htdocs/site - Session: Disconnected
+    [INFO] ------------------------------------------------------------------------
+    [ERROR] BUILD ERROR
+    [INFO] ------------------------------------------------------------------------
+    [INFO] Error uploading site
+    
+    Embedded error: SCP terminated with error: 'scp: /home/groups/q/qi/qifcon/htdocs/site/./wagon12736.zip: No such file or directory'
+    [INFO] ------------------------------------------------------------------------
+    [INFO] For more information, run Maven with the -e switch
+    [INFO] ------------------------------------------------------------------------
+    [INFO] Total time: 15 seconds
+    [INFO] Finished at: Sat Nov 08 07:27:34 CST 2008
+    [INFO] Final Memory: 6M/11M
+    [INFO] ------------------------------------------------------------------------
+    ```
+
+1. Unable to unzip the zip file created by Wagon
+
+    If the directory exists then the Wagon zip file can be uploaded and `site:deploy` will appear to succeed, but the web site will not work since the Wagon zip file can not be unzipped.
+
+    ```
+    C:\ide\Finance\qifcon\site>mvn site:deploy
+    [INFO] Scanning for projects...
+    [INFO] Searching repository for plugin with prefix: 'site'.
+    [INFO] ------------------------------------------------------------------------
+    [INFO] Building QifCon
+    [INFO]    task-segment: [site:deploy]
+    [INFO] ------------------------------------------------------------------------
+    [INFO] [site:deploy]
+    Using private key: C:\Projects\putty\barrie@sourceforge-net.openssh
+    scp://web.sourceforge.net/home/groups/q/qi/qifcon/htdocs/site - Session: Opened
+    Executing command: mkdir -p /home/groups/q/qi/qifcon/htdocs/site/.
+    Executing command: mkdir -p /home/groups/q/qi/qifcon/htdocs/site/.
+    Executing command: scp -t /home/groups/q/qi/qifcon/htdocs/site/./wagon21889.zip
+    Uploading: ./wagon21889.zip to scp://web.sourceforge.net/home/groups/q/qi/qifcon/htdocs/site
+    
+    ########################
+    Transfer finished. 95979 bytes copied in 1.872 seconds
+    Executing command: cd /home/groups/q/qi/qifcon/htdocs/site/.; unzip -q -o wagon21889.zip; rm -f wagon21889.zip
+    Executing command: chmod -Rf g+w,a+rX /home/groups/q/qi/qifcon/htdocs/site
+    scp://web.sourceforge.net/home/groups/q/qi/qifcon/htdocs/site - Session: Disconnecting
+    scp://web.sourceforge.net/home/groups/q/qi/qifcon/htdocs/site - Session: Disconnected
+    [INFO] ------------------------------------------------------------------------
+    [INFO] BUILD SUCCESSFUL
+    [INFO] ------------------------------------------------------------------------
+    [INFO] Total time: 18 seconds
+    [INFO] Finished at: Sat Nov 08 07:51:04 CST 2008
+    [INFO] Final Memory: 6M/11M
+    [INFO] ------------------------------------------------------------------------
+    ```
+
+### No shell created error
+
+If you try to run `ssh` without first creating a shell you will get the following error:
+
+```
 $ ssh barrie,qifcon@shell.sf.net
 barrie,qifcon@shell.sf.net's password:
 Logging in to your interactive shell...
@@ -250,4 +231,5 @@ ready for use.  An example create that enters the shell when ready:
     ssh -t USER,PROJECT@shell.sourceforge.net create
 
 Connection to shell.sf.net closed.
------
+```
+
diff --git a/src/site/markdown/examples/sitedescriptor.md b/src/site/markdown/examples/sitedescriptor.md
index 673f7e56..61278a1b 100644
--- a/src/site/markdown/examples/sitedescriptor.md
+++ b/src/site/markdown/examples/sitedescriptor.md
@@ -1,75 +1,57 @@
- ------
- Configuring the Site Descriptor
- ------
- Vincent Siveton
- <vi...@gmail.com>
- Maria Odea Ching
- Dennis Lundberg
- ------
- 2011-08-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
-
-
-Configuring the Site Descriptor
-
-  You can create your own site descriptor for your project when you want to override the navigation tree for the site.
-  For example, aside from the generated reports you want to add additional content to your site. In order for it
-  to be accessible in the generated site, you must configure your site descriptor. You create the site descriptor in
-  a file called <<<site.xml>>> which should be located in your <<<src/site>>> directory.
-
-  There is a
-  {{{/doxia/doxia-sitetools/doxia-site-model/site.html}reference documentation for the site descriptor}}
-  available with its XML Schema.
-
-  Have a look at the
-  {{{https://github.com/apache/maven-site-plugin/blob/master/src/site/site.xml}site descriptor for Maven Site Plugin}}
-  for a real life example.
-
-%{toc|section=1|fromDepth=2|toDepth=3}
-
-* Title
-
-  The title of each generated page will be a combination of the <site title>
-  and the title of the current page. By default the Site Plugin will use the
-  value of the <<<\<name\>>>> element from your <<<pom.xml>>> file as the
-  site title. The complete title for this page is "Maven Site Plugin - Configuring
-  the Site Descriptor".
-
-  If you want to use a different site title, but do not want to change the
-  <<<\<name\>>>> element in your <<<pom.xml>>>, you can configure this in your
-  <<<site.xml>>>, like this:
-
-+-----+
+---
+title: Configuring the Site Descriptor
+author: 
+  - Vincent Siveton
+  - _vincent.siveton@gmail.com_
+  - Maria Odea Ching
+  - Dennis Lundberg
+date: 2011-08-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-->
+# Configuring the Site Descriptor
+
+You can create your own site descriptor for your project when you want to override the navigation tree for the site. For example, aside from the generated reports you want to add additional content to your site. In order for it to be accessible in the generated site, you must configure your site descriptor. You create the site descriptor in a file called `site.xml` which should be located in your `src/site` directory.
+
+There is a [reference documentation for the site descriptor](/doxia/doxia-sitetools/doxia-site-model/site.html) available with its XML Schema.
+
+Have a look at the [site descriptor for Maven Site Plugin](https://github.com/apache/maven-site-plugin/blob/master/src/site/site.xml) for a real life example.
+
+<!-- MACRO{toc|section=1|fromDepth=2|toDepth=3} -->
+## Title
+
+The title of each generated page will be a combination of the _site title_ and the title of the current page. By default the Site Plugin will use the value of the `<name>` element from your `pom.xml` file as the site title. The complete title for this page is &quot;Maven Site Plugin - Configuring the Site Descriptor&quot;.
+
+If you want to use a different site title, but do not want to change the `<name>` element in your `pom.xml`, you can configure this in your `site.xml`, like this:
+
+```unknown
 <project name="My Site Title">
   ...
 </project>
-+-----+
+```
 
-* Banner
+## Banner
 
-  You can include some logos on top of your site, using the following syntax:
+You can include some logos on top of your site, using the following syntax:
 
-+-----+
+```unknown
 <project>
   ...
   <bannerLeft>
@@ -83,81 +65,65 @@ Configuring the Site Descriptor
   </bannerRight>
   ...
 </project>
-+-----+
+```
 
-  Refer to the site descriptor
-  {{{/doxia/doxia-sitetools/doxia-site-model/site.html}reference}}
-  for a complete tag description.
+Refer to the site descriptor [reference](/doxia/doxia-sitetools/doxia-site-model/site.html) for a complete tag description.
 
+## Publish Date
 
-* Publish Date
+With the out-of-the-box Velocity template, the position of the &quot;Last Published&quot; date is configurable. By default, the position is on the left but you can change it. To do this, you can add a `<publishDate>` element to your `site.xml` like the following:
 
-  With the out-of-the-box Velocity template, the position of the "Last Published" date is configurable.
-  By default, the position is on the left but you can change it.
-  To do this, you can add a <<<\<publishDate\>>>> element to your
-  <<<site.xml>>> like the following:
-
-+-----+
+```unknown
 <project>
   ...
   <publishDate position="right"/>
   ...
 </project>
-+-----+
+```
 
-  The <<<position>>> attribute can have one of these values: <<<left>>>,
-  <<<right>>>, <<<navigation-top>>>, <<<navigation-bottom>>>, <<<bottom>>>.
+The `position` attribute can have one of these values: `left`, `right`, `navigation-top`, `navigation-bottom`, `bottom`.
 
-  If you want hide the publish date, you can use this in your <<<site.xml>>>:
+If you want hide the publish date, you can use this in your `site.xml`:
 
-+-----+
+```unknown
 <project>
   ...
   <publishDate position="none"/>
   ...
 </project>
-+-----+
+```
 
-  The format of the "Last Published" date is the ISO extended date format that is
-  {{{http://www.w3.org/QA/Tips/iso-date}recommended by the W3C}}. Because the
-  web has an international, cross-cultural audience it is recommended to <not>
-  change the date format.
-  There is however a <<<format>>> attribute to the <<<\<publishDate\>>>> element
-  that can be used if you really need a different date format.
+The format of the &quot;Last Published&quot; date is the ISO extended date format that is [recommended by the W3C](http://www.w3.org/QA/Tips/iso-date). Because the web has an international, cross-cultural audience it is recommended to _not_ change the date format. There is however a `format` attribute to the `<publishDate>` element that can be used if you really need a different date format.
 
-* Version
+## Version
 
-  You can show the "Version" of your project on the site, by adding a <<<\<version\>>>> element to your
-  <<<site.xml>>> like this:
+You can show the &quot;Version&quot; of your project on the site, by adding a `<version>` element to your `site.xml` like this:
 
-+-----+
+```unknown
 <project>
   ...
   <version position="right"/>
   ...
 </project>
-+-----+
+```
 
-  The <<<position>>> attribute can have the same values as the <<<publishDate>>> attribute, see above.
-  If the <<<position>>> attribute is omitted, the default value is <<<left>>>.
+The `position` attribute can have the same values as the `publishDate` attribute, see above. If the `position` attribute is omitted, the default value is `left`.
 
-  If you want hide the version, you can use this in your <<<site.xml>>>:
+If you want hide the version, you can use this in your `site.xml`:
 
-+-----+
+```unknown
 <project>
   ...
   <version position="none"/>
   ...
 </project>
-+-----+
+```
 
-* "Powered by" Logo
+## &quot;Powered by&quot; Logo
 
-  You can add your own "Powered by" logo to your site.
-  To do this, you add a <<<\<poweredBy\>>>> element in your <<<site.xml>>> like
-  this:
+You can add your own &quot;Powered by&quot; logo to your site. To do this, you add a `<poweredBy>` element in your `site.xml` like this:
 
-+-----+
+```unknown
 <project>
   ...
   <poweredBy>
@@ -166,19 +132,17 @@ Configuring the Site Descriptor
   </poweredBy>
   ...
 </project>
-+-----+
+```
 
-* Inheritance
+## Inheritance
 
-  See {{{./multimodule.html} Building multi-module sites}}.
+See [ Building multi-module sites](./multimodule.html).
 
-* Including Generated Content
+## Including Generated Content
 
-  Files in the format-based directory structure can be linked to by their target
-  HTML filename, e.g. <<<$\{basedir\}/src/site/apt/foo.apt>>> and
-  <<<$\{basedir\}/src/site/fml/faq.fml>>> can be linked to via:
+Files in the format-based directory structure can be linked to by their target HTML filename, e.g. `${basedir}/src/site/apt/foo.apt` and `${basedir}/src/site/fml/faq.fml` can be linked to via:
 
-+-----+
+```unknown
 <project>
   ...
   <body>
@@ -191,13 +155,11 @@ Configuring the Site Descriptor
   </body>
   ...
 </project>
-+-----+
+```
 
-  There are also several preset menus that can be used in the site descriptor to
-  include generated content from your project. These are linked via the
-  <<<ref>>> attribute, like so:
+There are also several preset menus that can be used in the site descriptor to include generated content from your project. These are linked via the `ref` attribute, like so:
 
-+-----+
+```unknown
 <project>
   ...
   <body>
@@ -207,31 +169,20 @@ Configuring the Site Descriptor
   </body>
   ...
 </project>
-+-----+
-
-  <<Note:>> The old syntax using <<<$\{reports\}>>>, <<<$\{parent\}>>> and
-  <<<$\{modules\}>>> has been deprecated and you are encouraged to use the new
-  syntax instead. The support for the old syntax will be removed in a future
-  version of the Site Plugin.
-
-  The currently available preset menus are:
-
-  * <<<reports>>> - a menu with links to all the generated reports for your
-  project
+```
 
-  * <<<parent>>> - a menu with a link to the parent project's site
+**Note:** The old syntax using `${reports}`, `${parent}` and `${modules}` has been deprecated and you are encouraged to use the new syntax instead. The support for the old syntax will be removed in a future version of the Site Plugin.
 
-  * <<<modules>>> - a menu containing the links to the sites of the submodules
-  of this project
+The currently available preset menus are:
 
-  []
+- `reports` - a menu with links to all the generated reports for your project
+- `parent` - a menu with a link to the parent project&apos;s site
+- `modules` - a menu containing the links to the sites of the submodules of this project
+## Inject xhtml into &lt;head&gt;
 
-* Inject xhtml into \<head\>
+You can inject some HTML code into the generated `<head>` element of each page by adding a head element to the body element of your project&apos;s site descriptor. The following example adds some javascript:
 
-  You can inject some HTML code into the generated <<<\<head\>>>> element of each page by adding a head element
-  to the body element of your project's site descriptor. The following example adds some javascript:
-
-+-----+
+```unknown
 <project>
   ...
   <body>
@@ -243,17 +194,15 @@ Configuring the Site Descriptor
   </body>
   ...
 </project>
-+-----+
+```
 
-  Notice: since Maven Site Plugin version 3.5, if XHTML content is used, it has to be escaped, for example through
-  CDATA XML notation. Previously, XML content didn't need such escaping.
+Notice: since Maven Site Plugin version 3\.5, if XHTML content is used, it has to be escaped, for example through CDATA XML notation. Previously, XML content didn&apos;t need such escaping.
 
-* Links
+## Links
 
-  To add links below your site logo, just add a links element to the <<<\<body\>>>> element of the site descriptor.
-  Each item in the links element will be rendered as a link in a bar directly below your project's logo.
+To add links below your site logo, just add a links element to the `<body>` element of the site descriptor. Each item in the links element will be rendered as a link in a bar directly below your project&apos;s logo.
 
-+-----+
+```unknown
 <project>
   ...
   <body>
@@ -266,18 +215,15 @@ Configuring the Site Descriptor
   </body>
   ...
 </project>
-+-----+
+```
 
-* Breadcrumbs
+## Breadcrumbs
 
-  If there exists a logical hierarchy within your site modules, you may want to generate a series of
-  breadcrumbs to give a way to easily navigate the project tree.
+If there exists a logical hierarchy within your site modules, you may want to generate a series of breadcrumbs to give a way to easily navigate the project tree.
 
-  To configure breadcrumbs, add a <<<\<breadcrumbs\>>>> element to the <<<\<body\>>>> element in the site descriptor.
-  Each item element will render a link, and the items in the <<<\<breadcrumbs\>>>> element will be rendered in order.
-  The breadcrumb items should be listed from highest level to lowest level.
+To configure breadcrumbs, add a `<breadcrumbs>` element to the `<body>` element in the site descriptor. Each item element will render a link, and the items in the `<breadcrumbs>` element will be rendered in order. The breadcrumb items should be listed from highest level to lowest level.
 
-+-----+
+```unknown
 <project>
   ...
   <body>
@@ -290,17 +236,15 @@ Configuring the Site Descriptor
   </body>
   ...
 </project>
-+-----+
+```
 
-  <<Note>> that in a multi-module build, if the parent contains a breadcrumb and the inheriting site
-  descriptor doesn't, a breadcrumb with the current site descriptor's name will be added automatically.
-  See the notes on {{{./multimodule.html}building a multi-module site}} for more details.
+**Note** that in a multi-module build, if the parent contains a breadcrumb and the inheriting site descriptor doesn&apos;t, a breadcrumb with the current site descriptor&apos;s name will be added automatically. See the notes on [building a multi-module site](./multimodule.html) for more details.
 
-* Custom footer
+## Custom footer
 
-  You can replace the auto-generated footer content by specifying a custom <<<\<footer\>>>> element:
+You can replace the auto-generated footer content by specifying a custom `<footer>` element:
 
-+-----+
+```unknown
 <project>
   ...
   <body>
@@ -310,33 +254,27 @@ Configuring the Site Descriptor
   </body>
   ...
 </project>
-+-----+
+```
 
-  Notice: since Maven Site Plugin version 3.5, if XHTML content is used, it has to be escaped, for example through
-  CDATA XML notation. Previously, XML content didn't need such escaping.
+Notice: since Maven Site Plugin version 3\.5, if XHTML content is used, it has to be escaped, for example through CDATA XML notation. Previously, XML content didn&apos;t need such escaping.
 
-* Custom content
+## Custom content
 
-  There is also a dummy <<<\<custom\>>>> element then can be used to specify some arbitrary content.
-  Note that you need to write your own velocity template to make use of this element,
-  it is ignored by the default Velocity template used by the Site Plugin.
+There is also a dummy `<custom>` element then can be used to specify some arbitrary content. Note that you need to write your own velocity template to make use of this element, it is ignored by the default Velocity template used by the Site Plugin.
 
-+-----+
+```unknown
 <project>
   ...
   <custom>Custom content</custom>
   ...
 </project>
-+-----+
+```
 
-* Skinning
+## Skinning
 
-  Skins can be created to customize the look and feel of a site in a consistent way. For more information on creating a
-  skin, see {{{./creatingskins.html}Creating a Skin}}. To use a specific skin in your project, you use the <<<\<skin\>>>>
-  element of the site descriptor. This is a regular artifact or dependency-like element. For example, to use the
-  {{{/skins/maven-fluido-skin/}Maven Fluido Skin}}, you would include:
+Skins can be created to customize the look and feel of a site in a consistent way. For more information on creating a skin, see [Creating a Skin](./creatingskins.html). To use a specific skin in your project, you use the `<skin>` element of the site descriptor. This is a regular artifact or dependency-like element. For example, to use the [Maven Fluido Skin](/skins/maven-fluido-skin/), you would include:
 
-+-----+
+```unknown
 <project>
   ...
   <skin>
@@ -346,29 +284,21 @@ Configuring the Site Descriptor
   </skin>
   ...
 </project>
-+-----+
+```
 
-  <<Note:>> The <<<\<version\>>>> element is optional and, like plugins, if
-  omitted the latest version available will be used. It is recommended that you
-  always specify a version so that your site is reproducible over time.
+**Note:** The `<version>` element is optional and, like plugins, if omitted the latest version available will be used. It is recommended that you always specify a version so that your site is reproducible over time.
 
-  This skin will copy the necessary resources including CSS and if necessary use the included alternate Velocity
-  template to render the site.
+This skin will copy the necessary resources including CSS and if necessary use the included alternate Velocity template to render the site.
 
-  If you don't specify a skin, the Site Plugin will use
-  {{{/skins/maven-default-skin/}Maven Default Skin}}.
+If you don&apos;t specify a skin, the Site Plugin will use [Maven Default Skin](/skins/maven-default-skin/).
 
-* Custom Properties
+## Custom Properties
 
-  The authors of skins have the option to use custom properties that are unique
-  to their skin. The users of the skin can then specify their own values for
-  these properties in their <<<site.xml>>> using the <<<\<custom\>>>> element.
+The authors of skins have the option to use custom properties that are unique to their skin. The users of the skin can then specify their own values for these properties in their `site.xml` using the `<custom>` element.
 
-  One skin that uses this is the Maven Fluido Skin. There are many examples on
-  {{{/skins/maven-fluido-skin/}their site}} showing what
-  is possible to do with custom properties. Here is one example:
+One skin that uses this is the Maven Fluido Skin. There are many examples on [their site](/skins/maven-fluido-skin/) showing what is possible to do with custom properties. Here is one example:
 
-+-----+
+```unknown
 <project>
   ...
   <custom>
@@ -379,23 +309,17 @@ Configuring the Site Descriptor
   </custom>
   ...
 </project>
-+-----+
-
-* Expressions
-
-  The <<<site.xml>>> can contain some expressions, like <<<$\{project.name\}>>>.
-  Each expression will be evaluated when the site is rendered.
+```
 
-  Expressions can be:
+## Expressions
 
-  * $\{project.*\}, for instance <<<$\{project.organization.name\}>>> referenced in <<< <project><organization><name> >>>
+The `site.xml` can contain some expressions, like `${project.name}`. Each expression will be evaluated when the site is rendered.
 
-  * $\{project.properties\}, for instance <<<$\{myProperty\}>>> referenced in <<< <project><properties><myProperty> >>>
+Expressions can be:
 
-  * $\{environmentVariable\}, for instance <<<$\{JAVA_HOME\}>>>
+- ${project.*}, for instance `${project.organization.name}` referenced in ` <project><organization><name> `
+- ${project.properties}, for instance `${myProperty}` referenced in ` <project><properties><myProperty> `
+- ${environmentVariable}, for instance `${JAVA_HOME}`
 
-  []
+**Note:**There are additional restrictions on using dotted project properties in content pages. See [Filtering](./creating-content.html#Filtering) for details on injecting properties into content pages.
 
-  <<Note:>>There are additional restrictions on using dotted project properties
-  in content pages. See {{{./creating-content.html#Filtering}Filtering}} for details
-  on injecting properties into content pages.
diff --git a/src/site/markdown/examples/siterun.md.vm b/src/site/markdown/examples/siterun.md.vm
index 55c13498..4781e502 100644
--- a/src/site/markdown/examples/siterun.md.vm
+++ b/src/site/markdown/examples/siterun.md.vm
@@ -1,40 +1,35 @@
- ------
- Configuring Site Run
- ------
- Maria Odea Ching
- ------
- 2009-03-08
- ------
-
- ~~ 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
-
-
-Configuring Site Run
-
-  For the <<<{{{../run-mojo.html}site:run}}>>> goal, you can configure which port to use to start up the site as well as the directory where
-  the pages for the site will be rendered.
-
-  For example, you can have the following configuration in your POM:
-
-+-----+
+---
+title: Configuring Site Run
+author: 
+  - Maria Odea Ching
+date: 2009-03-08
+---
+
+<!-- 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-->
+# Configuring Site Run
+
+For the [`site:run`](../run-mojo.html) goal, you can configure which port to use to start up the site as well as the directory where the pages for the site will be rendered.
+
+For example, you can have the following configuration in your POM:
+
+```unknown
 <project>
   ...
   <build>
@@ -52,8 +47,7 @@ Configuring Site Run
   </build>
   ...
 </project>
-+-----+
+```
+
+When you execute &quot;`mvn site:run`&quot;, you will see in the command line that the Jetty server is started at port 9000\. To access the site, type `http://localhost:9000` in your browser. You will also see that the dummy web application is generated in the `${basedir}/target/site/tempdir` directory as specified by the `tempWebappDirectory` parameter.
 
-  When you execute "<<<mvn site:run>>>", you will see in the command line that the Jetty server is started at port 9000.
-  To access the site, type <<<http://localhost:9000>>> in your browser. You will also see that the dummy web application is
-  generated in the <<<$\{basedir\}/target/site/tempdir>>> directory as specified by the <<<tempWebappDirectory>>> parameter.
diff --git a/src/site/markdown/history.md b/src/site/markdown/history.md
index 9f77f26b..44ca302a 100644
--- a/src/site/markdown/history.md
+++ b/src/site/markdown/history.md
@@ -1,148 +1,85 @@
- ------
- Maven Site Plugin History
- ------
- Hervé Boutemy
- ------
- 2018-01-20
- ------
+---
+title: Maven Site Plugin History
+author: 
+  - Hervé Boutemy
+date: 2018-01-20
+---
 
- ~~ 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-->
+<!---->
+<!--   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 Site Plugin History
 
+## Overview
 
-Maven Site Plugin History
+Maven Site Plugin uses:
 
-* Overview
+- [Doxia](/doxia/) to parse [many markup languages](/doxia/references/) then render HTML: see [Creating Content](./examples/creating-content.html) documentation for more details \(particularly which markups are enabled by default in maven-site-plugin and how to add one\),
+- [Doxia Sitetools - Site Renderer](/doxia/doxia-sitetools/doxia-site-renderer/) to integrate document content into a template packaged as a skin: see [Creating Skins](./examples/creatingskins.html) documentation for more details,
+- [Maven Reporting Executor](/shared/maven-reporting-exec/) to manage reports execution \(since Maven 3; reports execution was managed by Maven itself in Maven 2: see old [Using maven-site-plugin with Maven3](https://maven.apache.org/plugins-archives/maven-site-plugin-3.9.0/maven-3.html) documentation for more details\).
+![Developer Overview](developer-overview.png)
+## Maven Site Plugin vs Doxia vs Doxia Sitetools
 
- Maven Site Plugin uses:
+Given this layered approach, rendering issues reported to [MSITE Maven Site Plugin issue tracker](https://issues.apache.org/jira/projects/MSITE) are often translated to [Doxia](https://issues.apache.org/jira/projects/DOXIA) or [Doxia Sitetools](https://issues.apache.org/jira/projects/DOXIASITETOOLS) issues. Any issues fixed in Doxia or Doxia Sitetools are inherited to the maven-site-plugin once its dependency is updated.
 
-  * {{{/doxia/}Doxia}} to parse {{{/doxia/references/}many markup languages}} then render HTML: see
-  {{{./examples/creating-content.html}Creating Content}} documentation for more details (particularly which markups
-  are enabled by default in maven-site-plugin and how to add one),
+Knowing which version of maven-site-plugin uses which version of Doxia or Doxia Sitetools is useful to choose to which version to upgrade maven-site-plugin to benefit from a fix: this is the basis for the [simplified migration guide](./migrate.html).
 
-  * {{{/doxia/doxia-sitetools/doxia-site-renderer/}Doxia Sitetools - Site Renderer}} to integrate document content into
-  a template packaged as a skin: see {{{./examples/creatingskins.html}Creating Skins}} documentation for more details,
+|release date|maven-site-plugin|[Doxia](/doxia/)|[Doxia Sitetools](/doxia/doxia-sitetools/)|[Maven Reporting Executor](/shared/maven-reporting-exec/)|minimum Java|minimum Maven|Comment|
+|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
+|2024-10|3\.21\.0|2\.0\.0|2\.0\.0|2\.0\.0|||Doxia 2\.0\.0|
+|2024-08|3\.20\.0|||||||
+|2024-07|4\.0\.0-M16|||||||
+|2024-05|4\.0\.0-M15|2\.0\.0-M12|2\.0\.0-M19|2\.0\.0-M14|8|3\.6\.3||
+|2024-05|4\.0\.0-M14|2\.0\.0-M10|2\.0\.0-M18|2\.0\.0-M13||||
+|2023-12|4\.0\.0-M13|||||||
+|2023-11|4\.0\.0-M12||2\.0\.0-M16|2\.0\.0-M12||||
+|2023-10|4\.0\.0-M11|2\.0\.0-M8|2\.0\.0-M13|2\.0\.0-M11||||
+|2023-10|4\.0\.0-M10||2\.0\.0-M12|2\.0\.0-M10||||
+|2023-07|4\.0\.0-M9|2\.0\.0-M7|2\.0\.0-M11|2\.0\.0-M9||||
+|2023-04|4\.0\.0-M8||2\.0\.0-M10|2\.0\.0-M8||||
+|2023-04|4\.0\.0-M7||2\.0\.0-M7|2\.0\.0-M6||||
+|2023-03|4\.0\.0-M6|2\.0\.0-M6|=|2\.0\.0-M5||||
+|2023-02|4\.0\.0-M5|2\.0\.0-M5|=|2\.0\.0-M4||||
+|2022-12|4\.0\.0-M4|2\.0\.0-M4|=|2\.0\.0-M3||||
+|2022-07|4\.0\.0-M3|||2\.0\.0-M2||||
+|2022-06|4\.0\.0-M2|2\.0\.0-M3|=|||||
+|2022-05|4\.0\.0-M1|2\.0\.0-M2|=|2\.0\.0-M1|8|3\.2\.5|Test of Doxia 2\.0\.0 milestones|
+|release date|maven-site-plugin|[Doxia](/doxia/) 1|[Doxia Sitetools](/doxia/doxia-sitetools/) 1|[Maven Reporting Executor](/shared/maven-reporting-exec/) 1|minimum Java|minimum Maven|Comment|
+|2022-07|3\.12\.1|||||||
+|2022-04|3\.12\.0||||8|3\.2\.5||
+|2022-02|3\.11\.0|||1\.6\.0||||
+|2021-12|3\.10\.0|1\.11\.1|=|||||
+|2020-06|3\.9\.1||1\.9\.2|1\.5\.1|7|3\.0\.5||
+|2020-03|3\.9\.0|1\.9\.1|1\.9\.2|||||
+|2019-07|3\.8\.2|1\.9|1\.9\.1||7|3\.0|addition of confluence/docbook/twiki support by default|
+|2018-04|3\.7\.1||1\.8\.1|||||
+|2017-12|3\.7|1\.8|=|1\.4|||Markdown parser/HTML renderer [changed](/doxia/doxia/doxia-modules/doxia-module-markdown/)|
+|2016-11|3\.6||1\.7\.4|1\.3||||
+|2016-04|3\.5\.1||1\.7\.1|||||
+|2016-02|3\.5|1\.7|=||6|2\.2\.1|`site.xml`&apos;s `head` and `footer` changed from DOM to String, requiring CDATA|
+|2014-07|3\.4|1\.6|=|1\.2|||Reports inherit configuration from pluginManagement|
+|2013-05|3\.3|1\.4|=|1\.1|||addition of Markdown support by default in maven-site-plugin|
+|2012-10|3\.2||=|||||
+|2012-04|3\.1|1\.3|=|1\.0\.2|5|2\.2\.1||
+|2011-08|3\.0|1\.2|=|1\.0\.1|5|2\.2\.0|first maven-site-plugin that renders reports with Maven 3|
+|2012-04|2\.4|1\.3|=|||||
+|2011-05|2\.3|1\.2|=|||||
+|2010-11|2\.2|1\.1\.4|=|||||
+|2010-06|2\.1\.1|1\.1\.3|=|||||
+|2009-12|2\.1|1\.1\.2|=|||||
+|2009-03|2\.0|1\.0|=|||||
 
-  * {{{/shared/maven-reporting-exec/}Maven Reporting Executor}} to manage reports execution (since Maven 3; reports execution
-  was managed by Maven itself in Maven 2: see old {{{https://maven.apache.org/plugins-archives/maven-site-plugin-3.9.0/maven-3.html}Using maven-site-plugin with Maven3}} documentation for
-  more details).
-
-  []
-
-[developer-overview.png] Developer Overview
-
-* Maven Site Plugin vs Doxia vs Doxia Sitetools
-
-  Given this layered approach, rendering issues reported to {{{https://issues.apache.org/jira/projects/MSITE}MSITE Maven Site Plugin issue tracker}}
-  are often translated to {{{https://issues.apache.org/jira/projects/DOXIA}Doxia}} or
-  {{{https://issues.apache.org/jira/projects/DOXIASITETOOLS}Doxia Sitetools}} issues. Any issues fixed in
-  Doxia or Doxia Sitetools are inherited to the maven-site-plugin once its dependency is updated.
-
-  Knowing which version of
-  maven-site-plugin uses which version of Doxia or Doxia Sitetools is useful to choose to which version to upgrade
-  maven-site-plugin to benefit from a fix: this is the basis for the  {{{./migrate.html}simplified migration guide}}.
-
-*-----------------*--------------------*--------*------------------*--------------------*---*-------*---------------*
-|| release date || maven-site-plugin || {{{/doxia/}Doxia}} || {{{/doxia/doxia-sitetools/}Doxia Sitetools}} || {{{/shared/maven-reporting-exec/}Maven Reporting Executor}} || minimum Java || minimum  Maven || Comment
-*-----------------*--------------------*--------*------------------*--------------------*---*-------*---------------*
-| 2024-10         | 3.21.0             | 2.0.0  | 2.0.0            | 2.0.0              |   |       | Doxia 2.0.0
-*-----------------*--------------------*--------*------------------*--------------------*---*-------*---------------*
-| 2024-08         | 3.20.0             |        |                  |
-*-----------------*--------------------*--------*------------------*--------------------*---*-------*---------------*
-| 2024-07         | 4.0.0-M16          |        |                  |
-*-----------------*--------------------*--------*------------------*--------------------*---*-------*---------------*
-| 2024-05         | 4.0.0-M15          | 2.0.0-M12 | 2.0.0-M19     | 2.0.0-M14          | 8 | 3.6.3 |
-*-----------------*--------------------*--------*------------------*--------------------*---*-------*---------------*
-| 2024-05         | 4.0.0-M14          | 2.0.0-M10 | 2.0.0-M18     | 2.0.0-M13
-*-----------------*--------------------*--------*------------------*--------------------*---*-------*---------------*
-| 2023-12         | 4.0.0-M13          |        |                  |
-*-----------------*--------------------*--------*------------------*--------------------*---*-------*---------------*
-| 2023-11         | 4.0.0-M12          |        | 2.0.0-M16        | 2.0.0-M12
-*-----------------*--------------------*--------*------------------*--------------------*---*-------*---------------*
-| 2023-10         | 4.0.0-M11          | 2.0.0-M8 | 2.0.0-M13      | 2.0.0-M11
-*-----------------*--------------------*--------*------------------*--------------------*---*-------*---------------*
-| 2023-10         | 4.0.0-M10          |        | 2.0.0-M12        | 2.0.0-M10
-*-----------------*--------------------*--------*------------------*--------------------*---*-------*---------------*
-| 2023-07         | 4.0.0-M9           | 2.0.0-M7 | 2.0.0-M11      | 2.0.0-M9
-*-----------------*--------------------*--------*------------------*--------------------*---*-------*---------------*
-| 2023-04         | 4.0.0-M8           |        | 2.0.0-M10        | 2.0.0-M8
-*-----------------*--------------------*--------*------------------*--------------------*---*-------*---------------*
-| 2023-04         | 4.0.0-M7           |        | 2.0.0-M7         | 2.0.0-M6
-*-----------------*--------------------*--------*------------------*--------------------*---*-------*---------------*
-| 2023-03         | 4.0.0-M6           | 2.0.0-M6 | =              | 2.0.0-M5
-*-----------------*--------------------*--------*------------------*--------------------*---*-------*---------------*
-| 2023-02         | 4.0.0-M5           | 2.0.0-M5 | =              | 2.0.0-M4
-*-----------------*--------------------*--------*------------------*--------------------*---*-------*---------------*
-| 2022-12         | 4.0.0-M4           | 2.0.0-M4 | =              | 2.0.0-M3
-*-----------------*--------------------*--------*------------------*--------------------*---*-------*---------------*
-| 2022-07         | 4.0.0-M3           |        |                  | 2.0.0-M2
-*-----------------*--------------------*--------*------------------*--------------------*---*-------*---------------*
-| 2022-06         | 4.0.0-M2           | 2.0.0-M3 | =              |
-*-----------------*--------------------*--------*------------------*--------------------*---*-------*---------------*
-| 2022-05         | 4.0.0-M1           | 2.0.0-M2 | =              | 2.0.0-M1           | 8 | 3.2.5 | Test of Doxia 2.0.0 milestones
-*-----------------*--------------------*--------*------------------*--------------------*---*-------*---------------*
-|| release date || maven-site-plugin || {{{/doxia/}Doxia}} 1 || {{{/doxia/doxia-sitetools/}Doxia Sitetools}} 1 || {{{/shared/maven-reporting-exec/}Maven Reporting Executor}} 1 || minimum Java || minimum  Maven || Comment
-*-----------------*--------------------*--------*------------------*--------------------*---*-------*---------------*
-| 2022-07         | 3.12.1             |        |                  |
-*-----------------*--------------------*--------*------------------*--------------------*---*-------*---------------*
-| 2022-04         | 3.12.0             |        |                  |                    | 8 | 3.2.5 |
-*-----------------*--------------------*--------*------------------*--------------------*---*-------*---------------*
-| 2022-02         | 3.11.0             |        |                  | 1.6.0              |
-*-----------------*--------------------*--------*------------------*--------------------*---*-------*---------------*
-| 2021-12         | 3.10.0             | 1.11.1 | =                |
-*-----------------*--------------------*--------*------------------*--------------------*---*-------*---------------*
-| 2020-06         | 3.9.1              |        | 1.9.2            | 1.5.1              | 7 | 3.0.5 |
-*-----------------*--------------------*--------*------------------*--------------------*---*-------*---------------*
-| 2020-03         | 3.9.0              | 1.9.1  | 1.9.2            |
-*-----------------*--------------------*--------*------------------*--------------------*---*-------*---------------*
-| 2019-07         | 3.8.2              | 1.9    | 1.9.1            |                    | 7 | 3.0   | addition of confluence/docbook/twiki support by default
-*-----------------*--------------------*--------*------------------*--------------------*---*-------*---------------*
-| 2018-04         | 3.7.1              |        | 1.8.1            |
-*-----------------*--------------------*--------*------------------*--------------------*---*-------*---------------*
-| 2017-12         | 3.7                | 1.8    | =                | 1.4                |   |       | Markdown parser/HTML renderer {{{/doxia/doxia/doxia-modules/doxia-module-markdown/}changed}}
-*-----------------*--------------------*--------*------------------*--------------------*---*-------*---------------*
-| 2016-11         | 3.6                |        | 1.7.4            | 1.3
-*-----------------*--------------------*--------*------------------*--------------------*---*-------*---------------*
-| 2016-04         | 3.5.1              |        | 1.7.1            |
-*-----------------*--------------------*--------*------------------*--------------------*---*-------*---------------*
-| 2016-02         | 3.5                | 1.7    | =                |                    | 6 | 2.2.1 | <<<site.xml>>>'s <<<head>>> and <<<footer>>> changed from DOM to String, requiring CDATA
-*-----------------*--------------------*--------*------------------*--------------------*---*-------*---------------*
-| 2014-07         | 3.4                | 1.6    | =                | 1.2                |   |       | Reports inherit configuration from pluginManagement
-*-----------------*--------------------*--------*------------------*--------------------*---*-------*---------------*
-| 2013-05         | 3.3                | 1.4    | =                | 1.1                |   |       | addition of Markdown support by default in maven-site-plugin
-*-----------------*--------------------*--------*------------------*--------------------*---*-------*---------------*
-| 2012-10         | 3.2                |        | =                |
-*-----------------*--------------------*--------*------------------*--------------------*---*-------*---------------*
-| 2012-04         | 3.1                | 1.3    | =                | 1.0.2              | 5 | 2.2.1 |
-*-----------------*--------------------*--------*------------------*--------------------*---*-------*---------------*
-| 2011-08         | 3.0                | 1.2    | =                | 1.0.1              | 5 | 2.2.0 | first maven-site-plugin that renders reports with Maven 3
-*-----------------*--------------------*--------*------------------*--------------------*---*-------*---------------*
-| 2012-04         | 2.4                | 1.3    | =
-*-----------------*--------------------*--------*------------------*--------------------*---*-------*---------------*
-| 2011-05         | 2.3                | 1.2    | =
-*-----------------*--------------------*--------*------------------*--------------------*---*-------*---------------*
-| 2010-11         | 2.2                | 1.1.4  | =
-*-----------------*--------------------*--------*------------------*--------------------*---*-------*---------------*
-| 2010-06         | 2.1.1              | 1.1.3  | =
-*-----------------*--------------------*--------*------------------*--------------------*---*-------*---------------*
-| 2009-12         | 2.1                | 1.1.2  | =
-*-----------------*--------------------*--------*------------------*--------------------*---*-------*---------------*
-| 2009-03         | 2.0                | 1.0    | =
-*-----------------*--------------------*--------*------------------*--------------------*---*-------*---------------*
diff --git a/src/site/markdown/index.md.vm b/src/site/markdown/index.md.vm
index 14f6740e..fbdc550c 100644
--- a/src/site/markdown/index.md.vm
+++ b/src/site/markdown/index.md.vm
@@ -1,113 +1,73 @@
- ------
- Introduction
- ------
- Maria Odea Ching
- ------
- 2013-07-22
- ------
+---
+title: Introduction
+author: 
+  - Maria Odea Ching
+date: 2013-07-22
+---
 
- ~~ 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-->
+<!---->
+<!--   http://www.apache.org/licenses/LICENSE-2.0-->
+<!---->
+<!-- Unless required by applicable law or agreed to in writing,-->
+<!-- software distributed under the License is distributed on an-->
+<!-- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY-->
+<!-- KIND, either express or implied.  See the License for the-->
+<!-- specific language governing permissions and limitations-->
+<!-- under the License.-->
 
- ~~ NOTE: For help with the syntax of this file, see:
- ~~ http://maven.apache.org/doxia/references/apt-format.html
+# ${project.name}
 
+The Site Plugin is used to generate a site for the project. The generated site also includes the project&apos;s reports that were configured in the POM.
 
-${project.name}
+Please read the [migration guide](./migrate.html) if you want to upgrade from a previous version.
 
- The Site Plugin is used to generate a site for the project. The generated site also includes the project's reports
- that were configured in the POM.
- 
- Please read the {{{./migrate.html}migration guide}} if you want to upgrade from a previous version.
+#[[##]]# Goals Overview
 
-* Goals Overview
+The Site Plugin has seven goals:
 
-   The Site Plugin has seven goals:
+- [site:site](./site-mojo.html) is used generate a site for a single project. Note that links between module sites in a multi module build will **not** work, since local build directory structure doesn&apos;t match deployed site.
+- [site:deploy](./deploy-mojo.html) is used to deploy the generated site using Wagon supported protocol to the site URL specified in the `<distributionManagement>` section of the POM.
+- [site:run](./run-mojo.html) starts the site up, rendering documents as requested for faster editing. It uses Jetty as the web server.
+- [site:stage](./stage-mojo.html) generates a site in a local staging or mock directory based on the site URL specified in the `<distributionManagement>` section of the POM. It can be used to test that links between module sites in a multi module build work. This goal requires the site to already have been generated using the site goal, such as by calling `mvn site`.
+- [site:stage-deploy](./stage-deploy-mojo.html) deploys the generated site to a staging or mock directory to the site URL specified in the `<distributionManagement>` section of the POM.
+- [site:attach-descriptor](./attach-descriptor-mojo.html) adds the site descriptor \(`site.xml`\) to the list of files to be installed/deployed. For more references of the site descriptor, [here&apos;s a link](./examples/sitedescriptor.html).
+- [site:jar](./jar-mojo.html) bundles the site output into a JAR so that it can be deployed to a repository.
+- [site:effective-site](./effective-site-mojo.html) calculates the effective site descriptor, after inheritance and interpolation.
 
-   * {{{./site-mojo.html}site:site}} is used generate a site for a single project.
-     Note that links between module sites in a multi module build will <<not>> work, since local build directory structure
-     doesn't match deployed site.
+#[[##]]# Usage
 
-   * {{{./deploy-mojo.html}site:deploy}} is used to deploy the generated site using Wagon supported protocol to
-     the site URL specified in the <<<\<distributionManagement\>>>> section of the POM.
+General instructions on how to use the Site Plugin can be found on the [usage page](./usage.html). Some more specific use cases are described in the examples given below.
 
-   * {{{./run-mojo.html}site:run}} starts the site up, rendering documents as requested for faster editing. It uses Jetty
-     as the web server.
+In case you still have questions regarding the plugin&apos;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).
 
-   * {{{./stage-mojo.html}site:stage}} generates a site in a local staging or mock directory based on the site URL
-     specified in the <<<\<distributionManagement\>>>> section of the POM. It can be used
-     to test that links between module sites in a multi module build work. This goal requires the site to already have been
-     generated using the site goal, such as by calling <<<mvn site>>>.
+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  [...]
 
-   * {{{./stage-deploy-mojo.html}site:stage-deploy}} deploys the generated site to a staging or mock directory to the site
-     URL specified in the <<<\<distributionManagement\>>>> section of the POM.
+#[[##]]# Examples
 
-   * {{{./attach-descriptor-mojo.html}site:attach-descriptor}} adds the site descriptor (<<<site.xml>>>) to the list of
-     files to be installed/deployed. For more references of the site descriptor,
-     {{{./examples/sitedescriptor.html}here's a link}}.
+The following examples show how to use the Site Plugin in more advanced use cases:
 
-   * {{{./jar-mojo.html}site:jar}} bundles the site output into a JAR so that it can be deployed to a repository.
+- [Creating Content](./examples/creating-content.html)
+- [Configuring the Site Descriptor](./examples/sitedescriptor.html)
+- [Configuring Site Run](./examples/siterun.html)
+- [Excluding Document Formats](./examples/moduleexcludes.html)
 
-   * {{{./effective-site-mojo.html}site:effective-site}} calculates the effective site descriptor, after inheritance and
-     interpolation.
+#[[###]]# Reports
 
-* Usage
+- [Configuring Reports](./examples/configuring-reports.html)
+- [Reports Internationalization](./i18n.html)
 
-  General instructions on how to use the Site Plugin can be found on the {{{./usage.html}usage page}}. Some more
-  specific use cases are described in the examples given below.
+#[[###]]# Site Template
 
-  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}}.
+- [Creating Skins](./examples/creatingskins.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-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
-  {{{/guides/development/guide-helping.html}guide to helping with Maven}}.
-
-* Examples
-
-   The following examples show how to use the Site Plugin in more advanced use cases:
-
-   * {{{./examples/creating-content.html}Creating Content}}
-
-   * {{{./examples/sitedescriptor.html}Configuring the Site Descriptor}}
-
-   * {{{./examples/siterun.html}Configuring Site Run}}
-
-   * {{{./examples/moduleexcludes.html}Excluding Document Formats}}
-
-** Reports
-
-   * {{{./examples/configuring-reports.html}Configuring Reports}}
-
-   * {{{./i18n.html}Reports Internationalization}}
-
-** Site Template
-
-     * {{{./examples/creatingskins.html}Creating Skins}}
-
-** Deploying
-
-     * {{{./examples/adding-deploy-protocol.html}Adding a Protocol to Deploy the Site}}
-
-     * {{{./examples/site-deploy-to-sourceforge.net.html}Deploying to sourceforge.net}}
+#[[###]]# Deploying
 
+- [Adding a Protocol to Deploy the Site](./examples/adding-deploy-protocol.html)
+- [Deploying to sourceforge.net](./examples/site-deploy-to-sourceforge.net.html)
diff --git a/src/site/markdown/migrate.md b/src/site/markdown/migrate.md
index 37ec1de5..500cbd48 100644
--- a/src/site/markdown/migrate.md
+++ b/src/site/markdown/migrate.md
@@ -1,133 +1,88 @@
- ------
- Migrate
- ------
- Dennis Lundberg
- Hervé Boutemy
- ------
- 2016-04-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
-
-
-Migrate
-
-  The Site Plugin has had a couple of upgrades that requires the user to make
-  adjustments to their environment, documents or configuration. Below is a list
-  of key changes and what updates you as a user need to be aware of: you can have
-  a look at {{{./history.html} history}} for precise details of internal components updates.
-
-* From 3.4 to 3.5.1
-
-  * Since {{{http://velocity.apache.org}Velocity}} has been upgraded from version 1.5 to version 1.7,
-  which changes escaping rules, you may need to update escape sequences in your <<<.vm>>> documents and/or skins.
-  If you can't update content and/or skin immediately, you can manually downgrade Velocity version by
-  configuring a dependency to Maven Site Plugin:
-
-+-----------------+
-    <plugin>
-      <groupId>org.apache.maven.plugins</groupId>
-      <artifactId>maven-site-plugin</artifactId>
-      <dependencies>
-        <dependency>
-          <groupId>org.apache.velocity</groupId>
-          <artifactId>velocity</artifactId>
-          <version>1.5</version>
-        </dependency>
-      </dependencies>
-    </plugin>
-+-----------------+
-
-  * Site Decoration Model 1.7.0 has changed type for <<<head>>> and <<<footer>>> from <<<DOM>>> to <<<String>>>:
-  if your <<<site.xml>>> (or one parent) contains XML content, you'll need to escape it, usually by
-  adding <<<\<![CDATA[>>> and <<<]]\>>>> around the content:
-
-+-----------------+
-<project xmlns="http://maven.apache.org/DECORATION/1.7.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-    xsi:schemaLocation="http://maven.apache.org/DECORATION/1.7.0 http://maven.apache.org/xsd/decoration-1.7.0.xsd">
-    <body>
-        <head>
-            <![CDATA[<anyHeadElement/>]]>
-        </head>
-        <footer>
-            <![CDATA[<anyFooterElement/>]]>
-        </footer>
-    ...
-    </body>
-</project>
-+-----------------+
-
-  * Interpolation of <<<$\{project.*}>>> and <<<$\{*}>>> expressions in <<<site.xml>>> have changed to be
-  consistent with equivalent feature in Maven <<<pom.xml>>>: interpolation is now done <after> inheritance.
-  For <<<site.xml>>>, this may lead to failures on urls (often on <<<$\{project.url}>>> expression),
-  that are expected to be rebased during inheritance: a new <early interpolation> feature has been added
-  in Maven Site Plugin 3.5.1 throught <<<$\{this.*}>>> expressions (see
-  {{{/doxia/doxia-sitetools/doxia-integration-tools/index.html} Doxia Integration Tools reference documentation}}).
-  With this feature (for example <<<$\{this.url}>>> or <<<$\{this.customProperty}>>> expressions), you'll get
-  former <<<site.xml>>> interpolation result.
-
-  []
-
-* From 2.x to 3.x
-
-  * Version 3 of the plugin requires at least <<Maven 2.2.0>> to run.
-
-  * If you use <<Maven 3>> please read the {{{./maven-3.html}Maven 3}} guide about relevant issues.
-
-  []
-
-* From 2.2.x to 2.3.x
-
-  * The <<<site:stage>>> and <<<site:stage-deploy>>> goals have been decoupled from site generation.
-  Executing these goals without generating the site first will lead to a build failure.
-
-  []
-
-* From 2.1.x to 2.2.x
-
-  * The plugin now requires at least <<Maven 2.2.0>> to run, you cannot use it
-  with older Maven versions.
-
-  * The plugin now requires at least <<Java 5>> to run, you cannot use it
-  with older Java versions.
-
-  []
-
-* From 2.0.x to 2.1.x
-
-  * The plugin now requires at least <<Maven 2.1>> to run, you cannot use it
-  with older Maven versions.
-
-  * The plugin has been upgraded to use <<Doxia 1.1>>, which has seen a lot of
-  major changes itself. If you experience unexpected behavior, please read these
-  resources:
-
-    * {{{/doxia/whatsnew-1.1.html}Doxia: what's new in 1.1?}}
-
-    * {{{/doxia/references/doxia-apt.html}Doxia: Enhancements to the APT format}}
-
-    * {{{/doxia/issues/index.html}Doxia: Issues & Gotchas}}
-
-    * {{{/doxia/faq.html}Doxia: Frequently Asked Questions}}
-
-    []
-
-  []
+---
+title: Migrate
+author: 
+  - Dennis Lundberg
+  - Hervé Boutemy
+date: 2016-04-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.-->
+
+# Migrate
+
+The Site Plugin has had a couple of upgrades that requires the user to make adjustments to their environment, documents or configuration. Below is a list of key changes and what updates you as a user need to be aware of: you can have a look at [ history](./history.html) for precise details of internal components updates.
+
+## From 3\.4 to 3\.5\.1
+
+- Since [Velocity](http://velocity.apache.org) has been upgraded from version 1\.5 to version 1\.7, which changes escaping rules, you may need to update escape sequences in your `.vm` documents and/or skins. If you can&apos;t update content and/or skin immediately, you can manually downgrade Velocity version by configuring a dependency to Maven Site Plugin:
+
+    ```unknown
+        <plugin>
+          <groupId>org.apache.maven.plugins</groupId>
+          <artifactId>maven-site-plugin</artifactId>
+          <dependencies>
+            <dependency>
+              <groupId>org.apache.velocity</groupId>
+              <artifactId>velocity</artifactId>
+              <version>1.5</version>
+            </dependency>
+          </dependencies>
+        </plugin>
+    ```
+
+- Site Decoration Model 1\.7\.0 has changed type for `head` and `footer` from `DOM` to `String`: if your `site.xml` \(or one parent\) contains XML content, you&apos;ll need to escape it, usually by adding `<![CDATA[` and `]]>` around the content:
+
+    ```unknown
+    <project xmlns="http://maven.apache.org/DECORATION/1.7.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+        xsi:schemaLocation="http://maven.apache.org/DECORATION/1.7.0 http://maven.apache.org/xsd/decoration-1.7.0.xsd">
+        <body>
+            <head>
+                <![CDATA[<anyHeadElement/>]]>
+            </head>
+            <footer>
+                <![CDATA[<anyFooterElement/>]]>
+            </footer>
+        ...
+        </body>
+    </project>
+    ```
+
+- Interpolation of `${project.*}` and `${*}` expressions in `site.xml` have changed to be consistent with equivalent feature in Maven `pom.xml`: interpolation is now done _after_ inheritance. For `site.xml`, this may lead to failures on urls \(often on `${project.url}` expression\), that are expected to be rebased during inheritance: a new _early interpolation_ feature has been added in Maven Site Plugin 3\.5\.1 throught `${this.*}` expressions \(see [ Doxia Integration Tools reference d [...]
+
+## From 2\.x to 3\.x
+
+- Version 3 of the plugin requires at least **Maven 2\.2\.0** to run.
+- If you use **Maven 3** please read the [Maven 3](./maven-3.html) guide about relevant issues.
+
+## From 2\.2\.x to 2\.3\.x
+
+- The `site:stage` and `site:stage-deploy` goals have been decoupled from site generation. Executing these goals without generating the site first will lead to a build failure.
+
+## From 2\.1\.x to 2\.2\.x
+
+- The plugin now requires at least **Maven 2\.2\.0** to run, you cannot use it with older Maven versions.
+- The plugin now requires at least **Java 5** to run, you cannot use it with older Java versions.
+
+## From 2\.0\.x to 2\.1\.x
+
+- The plugin now requires at least **Maven 2\.1** to run, you cannot use it with older Maven versions.
+- The plugin has been upgraded to use **Doxia 1\.1**, which has seen a lot of major changes itself. If you experience unexpected behavior, please read these resources:
+    - [Doxia: what&apos;s new in 1\.1?](/doxia/whatsnew-1.1.html)
+    - [Doxia: Enhancements to the APT format](/doxia/references/doxia-apt.html)
+    - [Doxia: Issues &amp; Gotchas](/doxia/issues/index.html)
+    - [Doxia: Frequently Asked Questions](/doxia/faq.html)
diff --git a/src/site/markdown/usage.md b/src/site/markdown/usage.md
index 553ffa6d..4c30802c 100644
--- a/src/site/markdown/usage.md
+++ b/src/site/markdown/usage.md
@@ -1,77 +1,54 @@
- ------
- Usage
- ------
- Vincent Siveton
- <vi...@gmail.com>
- Maria Odea Ching
- ------
- 2012-01-12
- ------
-
- ~~ 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
-
- You can put additional content (e.g. documentation, resources, etc.) in your
- site. See {{{./examples/creating-content.html}Creating Content}} for more
- information on this. If you want to change the menus, breadcrumbs, links or
- logos on your pages you need to add and configure a
- {{{./examples/sitedescriptor.html}site descriptor}}. If you like, you also can
- let Maven generate some {{{./examples/configuring-reports.html}reports}} for you,
- based on the contents of your POM.
-
-%{toc|section=1|fromDepth=2|toDepth=3}
-
-* Generating a Site
-
-  To generate the project's site and reports, execute:
-
-+-----+
+---
+title: Usage
+author: 
+  - Vincent Siveton
+  - _vincent.siveton@gmail.com_
+  - Maria Odea Ching
+date: 2012-01-12
+---
+
+<!-- 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
+
+You can put additional content \(e.g. documentation, resources, etc.\) in your site. See [Creating Content](./examples/creating-content.html) for more information on this. If you want to change the menus, breadcrumbs, links or logos on your pages you need to add and configure a [site descriptor](./examples/sitedescriptor.html). If you like, you also can let Maven generate some [reports](./examples/configuring-reports.html) for you, based on the contents of your POM.
+
+<!-- MACRO{toc|section=1|fromDepth=2|toDepth=3} -->
+
+## Generating a Site
+
+To generate the project&apos;s site and reports, execute:
+
+```unknown
 mvn site
-+-----+
+```
 
-  By default, the resulting site will be in the <<<target/site/>>> directory.
+By default, the resulting site will be in the `target/site/` directory.
 
-  <<Note:>> If you have a multi module project, then the links between the
-  parent and child modules will <not> work when you use <<<mvn site>>> or
-  <<<mvn site:site>>>. If you want to use those links, you should use
-  <<<mvn site:stage>>> instead. You can read more about that goal further down on
-  this page in the section called '<Staging a Site>'.
+**Note:** If you have a multi module project, then the links between the parent and child modules will _not_ work when you use `mvn site` or `mvn site:site`. If you want to use those links, you should use `mvn site:stage` instead. You can read more about that goal further down on this page in the section called &apos;_Staging a Site_&apos;.
 
-  <<Note:>> For performance reasons, Maven compares the timestamps of generated
-  files and corresponding source documents, and only regenerates documents
-  that have changed since the last build.
-  However, this only applies to documentation source documents (apt, xdoc,...).
-  If you change anything in your <<<site.xml>>>, any relevant sections in your
-  pom, or any relevant properties or resource files, you should generate the
-  site from scratch to make sure all references and links are correct.
+**Note:** For performance reasons, Maven compares the timestamps of generated files and corresponding source documents, and only regenerates documents that have changed since the last build. However, this only applies to documentation source documents \(apt, xdoc,...\). If you change anything in your `site.xml`, any relevant sections in your pom, or any relevant properties or resource files, you should generate the site from scratch to make sure all references and links are correct.
 
-* Deploying a Site
+## Deploying a Site
 
-  To be able to deploy the site, you must first specify where the site will be
-  deployed. This is set in the <<<\<distributionManagement\>>>> element of the
-  POM as shown below.
+To be able to deploy the site, you must first specify where the site will be deployed. This is set in the `<distributionManagement>` element of the POM as shown below.
 
-+-----+
+```unknown
 <project>
   ...
   <distributionManagement>
@@ -82,107 +59,69 @@ mvn site
   </distributionManagement>
   ...
 </project>
-+-----+
+```
 
-  The <<<\<id\>>>> element identifies the repository, so that you can attach
-  credentials to it in your <<<settings.xml>>> file using the
-  {{{/ref/current/maven-settings/settings.html#Servers}<<<\<servers\>>>> element}}
-  as you would for any other repository.
+The `<id>` element identifies the repository, so that you can attach credentials to it in your `settings.xml` file using the [`<servers>` element](/ref/current/maven-settings/settings.html#Servers) as you would for any other repository.
 
-  The <<<\<url\>>>> gives the location to deploy to. In the example above we
-  copy to the host <<<www.mycompany.com>>> using the path
-  <<</www/docs/project/>>> over the <<<scp>>> protocol. You can read more about
-  which protocols are supported on
-  {{{./examples/adding-deploy-protocol.html}this page}}. If
-  subprojects inherit the site URL from a parent POM, they will automatically
-  append their <<<\<artifactId\>>>> to form their effective deployment location.
+The `<url>` gives the location to deploy to. In the example above we copy to the host `www.mycompany.com` using the path `/www/docs/project/` over the `scp` protocol. You can read more about which protocols are supported on [this page](./examples/adding-deploy-protocol.html). If subprojects inherit the site URL from a parent POM, they will automatically append their `<artifactId>` to form their effective deployment location.
 
-  Now you can execute the <<<{{{./deploy-mojo.html}site:deploy}}>>> goal from
-  your project directory.
+Now you can execute the [`site:deploy`](./deploy-mojo.html) goal from your project directory.
 
-  <<Note:>> A site must be generated first before executing <<<site:deploy>>>.
+**Note:** A site must be generated first before executing `site:deploy`.
 
-+-----+
+```unknown
 mvn site:deploy
-+-----+
+```
 
-  If you want to generate the site <and> deploy it in one go, you can utilize
-  the <<<site-deploy>>> phase of the site lifecycle. To do this, just execute:
+If you want to generate the site _and_ deploy it in one go, you can utilize the `site-deploy` phase of the site lifecycle. To do this, just execute:
 
-+-----+
+```unknown
 mvn site-deploy
-+-----+
+```
 
-* Staging a Site
+## Staging a Site
 
-  To review/test the generated web site before an official deploy, you can stage the site in
-  a specific directory. It will use the <<<\<distributionManagement\>>>> element or the project hierarchy to link the
-  project and its modules.
+To review/test the generated web site before an official deploy, you can stage the site in a specific directory. It will use the `<distributionManagement>` element or the project hierarchy to link the project and its modules.
 
-  Just execute the <<<{{{./stage-mojo.html}site:stage}}>>> goal from your project
+Just execute the [`site:stage`](./stage-mojo.html) goal from your project
 
-+-----+
+```unknown
 mvn site:stage
-+-----+
+```
 
-  <<Note:>> A site must be generated first before executing <<<site:stage>>>.
+**Note:** A site must be generated first before executing `site:stage`.
 
-  By default, the site will be staged in a directory <<<target/staging/>>>.
-  A different staging location can be chosen
-  with the <<<stagingDirectory>>> parameter as shown below:
+By default, the site will be staged in a directory `target/staging/`. A different staging location can be chosen with the `stagingDirectory` parameter as shown below:
 
-+-----+
+```unknown
 mvn site:stage -DstagingDirectory=C:\fullsite
-+-----+
-
-  <<Note:>> <<<stagingDirectory>>> cannot be dynamic, i.e. <<<stagingDirectory=$\{basedir\}\fullsite>>>
-
-  To stage a site and deploy it, execute the
-  <<<{{{./stage-deploy-mojo.html}site:stage-deploy}}>>> goal from your project
-  with the required parameters.
-  The <<<site:stage-deploy>>> goal will use the value of <<<distributionManagement.site.id>>> as default id
-  to lookup the server section in your <<<settings.xml>>>;
-  unless this is not defined, then the String <<<stagingSite>>> will be used as id.
-  So if you need to add your username or password separately for stage-deploy in <<<settings.xml>>>,
-  you should use <<<\<id\>stagingSite\</id\>>>> for that <<<\<server\>>>> section.
-  See the
-  {{{/guides/mini/guide-deployment-security-settings.html}Guide to Deployment and Security Settings}}
-  for more information on this.
-
-  By default, the site will be stage-deployed to <<<${distributionManagement.site.url}/staging/>>>.
-  A different location can be chosen with the <<<stagingSiteURL>>> parameter as shown below:
-
-+-----+
+```
+
+**Note:** `stagingDirectory` cannot be dynamic, i.e. `stagingDirectory=${basedir}\fullsite`
+
+To stage a site and deploy it, execute the [`site:stage-deploy`](./stage-deploy-mojo.html) goal from your project with the required parameters. The `site:stage-deploy` goal will use the value of `distributionManagement.site.id` as default id to lookup the server section in your `settings.xml`; unless this is not defined, then the String `stagingSite` will be used as id. So if you need to add your username or password separately for stage-deploy in `settings.xml`, you should use `<id>stag [...]
+
+By default, the site will be stage-deployed to `${distributionManagement.site.url}/staging/`. A different location can be chosen with the `stagingSiteURL` parameter as shown below:
+
+```unknown
 mvn site:stage-deploy -DstagingSiteURL=scp://www.mycompany.com/www/project/
-+-----+
+```
 
-  <<Note:>>A site must be generated first before executing <<<site:stage-deploy>>>.
+**Note:** A site must be generated first before executing `site:stage-deploy`.
 
-* Running a Site
+## Running a Site
 
-  The Site Plugin can also be used to start up the site in Jetty. To do this,
-  execute:
+The Site Plugin can also be used to start up the site in Jetty. To do this, execute:
 
-+-----+
+```unknown
 mvn site:run
-+-----+
-
-  The server will, by default, be started on <<<http://localhost:8080/>>>. See
-  {{{https://www.eclipse.org/jetty/}https://www.eclipse.org/jetty/}} for more information about
-  the Jetty server.
-
-  <<Note:>> Running a site only works for single-module sites.
-  To preview a multi-module site one should use <<<site:stage>>>.
-
-* Rebuilding a Published (Released) Site
-
-  In general, site documentation is published as part of a release. This means that changes
-  to the documentation depend on a new release before being visible <or> you must accept
-  that the documentation refers to a snapshot version instead of the latest release version.
-  To solve that problem, you first need to configure your project for reproducibility
-  by setting the <<<project.build.outputTimestamp>>> model property. Then branch off from the
-  SCM tag you want to modify, perform the changes, commit them and then rebuild, finally
-  publish updated site. The underlying Maven Doxia Sitetools will automatically inject that
-  property as <<<publishDate>>> Velocity context property into the site and the skin won't
-  render a newer (current) date, but use this one. Checkout the <<<publishDate>>> IT for
-  configuration details.
+```
+
+The server will, by default, be started on `http://localhost:8080/`. See [https://www.eclipse.org/jetty/](https://www.eclipse.org/jetty/) for more information about the Jetty server.
+
+**Note:** Running a site only works for single-module sites. To preview a multi-module site one should use `site:stage`.
+
+## Rebuilding a Published \(Released\) Site
+
+In general, site documentation is published as part of a release. This means that changes to the documentation depend on a new release before being visible _or_ you must accept that the documentation refers to a snapshot version instead of the latest release version. To solve that problem, you first need to configure your project for reproducibility by setting the `project.build.outputTimestamp` model property. Then branch off from the SCM tag you want to modify, perform the changes, com [...]
+


(maven-site-plugin) 01/02: Move to match target converter format MARKDOWN with doxia-converter

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

kwin pushed a commit to branch feature/apt-to-markdown
in repository https://gitbox.apache.org/repos/asf/maven-site-plugin.git

commit 21f1a8a53e42f9f5dcca8517bc92d6136daf956b
Author: Konrad Windszus <kw...@apache.org>
AuthorDate: Thu Apr 16 16:32:19 2026 +0200

    Move to match target converter format MARKDOWN with doxia-converter
---
 .../examples/adding-deploy-protocol.md.vm}                                | 0
 .../configuring-reports.apt => markdown/examples/configuring-reports.md}  | 0
 .../creating-content.apt.vm => markdown/examples/creating-content.md.vm}  | 0
 .../examples/creatingskins.apt => markdown/examples/creatingskins.md}     | 0
 .../examples/inheritance-site-distribution-management.md}                 | 0
 .../moduleexcludes.apt.vm => markdown/examples/moduleexcludes.md.vm}      | 0
 .../{apt/examples/multimodule.apt => markdown/examples/multimodule.md}    | 0
 .../examples/site-deploy-to-sourceforge.net.md}                           | 0
 .../examples/sitedescriptor.apt => markdown/examples/sitedescriptor.md}   | 0
 src/site/{apt/examples/siterun.apt.vm => markdown/examples/siterun.md.vm} | 0
 src/site/{apt/history.apt => markdown/history.md}                         | 0
 src/site/{apt/index.apt.vm => markdown/index.md.vm}                       | 0
 src/site/{apt/migrate.apt => markdown/migrate.md}                         | 0
 src/site/{apt/usage.apt => markdown/usage.md}                             | 0
 14 files changed, 0 insertions(+), 0 deletions(-)

diff --git a/src/site/apt/examples/adding-deploy-protocol.apt.vm b/src/site/markdown/examples/adding-deploy-protocol.md.vm
similarity index 100%
rename from src/site/apt/examples/adding-deploy-protocol.apt.vm
rename to src/site/markdown/examples/adding-deploy-protocol.md.vm
diff --git a/src/site/apt/examples/configuring-reports.apt b/src/site/markdown/examples/configuring-reports.md
similarity index 100%
rename from src/site/apt/examples/configuring-reports.apt
rename to src/site/markdown/examples/configuring-reports.md
diff --git a/src/site/apt/examples/creating-content.apt.vm b/src/site/markdown/examples/creating-content.md.vm
similarity index 100%
rename from src/site/apt/examples/creating-content.apt.vm
rename to src/site/markdown/examples/creating-content.md.vm
diff --git a/src/site/apt/examples/creatingskins.apt b/src/site/markdown/examples/creatingskins.md
similarity index 100%
rename from src/site/apt/examples/creatingskins.apt
rename to src/site/markdown/examples/creatingskins.md
diff --git a/src/site/apt/examples/inheritance-site-distribution-management.apt b/src/site/markdown/examples/inheritance-site-distribution-management.md
similarity index 100%
rename from src/site/apt/examples/inheritance-site-distribution-management.apt
rename to src/site/markdown/examples/inheritance-site-distribution-management.md
diff --git a/src/site/apt/examples/moduleexcludes.apt.vm b/src/site/markdown/examples/moduleexcludes.md.vm
similarity index 100%
rename from src/site/apt/examples/moduleexcludes.apt.vm
rename to src/site/markdown/examples/moduleexcludes.md.vm
diff --git a/src/site/apt/examples/multimodule.apt b/src/site/markdown/examples/multimodule.md
similarity index 100%
rename from src/site/apt/examples/multimodule.apt
rename to src/site/markdown/examples/multimodule.md
diff --git a/src/site/apt/examples/site-deploy-to-sourceforge.net.apt b/src/site/markdown/examples/site-deploy-to-sourceforge.net.md
similarity index 100%
rename from src/site/apt/examples/site-deploy-to-sourceforge.net.apt
rename to src/site/markdown/examples/site-deploy-to-sourceforge.net.md
diff --git a/src/site/apt/examples/sitedescriptor.apt b/src/site/markdown/examples/sitedescriptor.md
similarity index 100%
rename from src/site/apt/examples/sitedescriptor.apt
rename to src/site/markdown/examples/sitedescriptor.md
diff --git a/src/site/apt/examples/siterun.apt.vm b/src/site/markdown/examples/siterun.md.vm
similarity index 100%
rename from src/site/apt/examples/siterun.apt.vm
rename to src/site/markdown/examples/siterun.md.vm
diff --git a/src/site/apt/history.apt b/src/site/markdown/history.md
similarity index 100%
rename from src/site/apt/history.apt
rename to src/site/markdown/history.md
diff --git a/src/site/apt/index.apt.vm b/src/site/markdown/index.md.vm
similarity index 100%
rename from src/site/apt/index.apt.vm
rename to src/site/markdown/index.md.vm
diff --git a/src/site/apt/migrate.apt b/src/site/markdown/migrate.md
similarity index 100%
rename from src/site/apt/migrate.apt
rename to src/site/markdown/migrate.md
diff --git a/src/site/apt/usage.apt b/src/site/markdown/usage.md
similarity index 100%
rename from src/site/apt/usage.apt
rename to src/site/markdown/usage.md