From a249baa92f189f9d1d08625d0d635736c663e81c Mon Sep 17 00:00:00 2001
From: Sylwester Lachiewicz <slachiewicz@apache.org>
Date: Sat, 8 Aug 2026 21:37:22 +0200
Subject: [PATCH 1/2] Rename the site documents ahead of converting them

Git records a rename plus a rewrite in one commit as a delete and an
add, which stops 'git log --follow'. Splitting the rename out keeps the
history across 65 files. Please merge or rebase rather than squash.
---
 .../index.apt => markdown/guides/component-programming/index.md}  | 0
 .../guides/developer-guide/advanced-topics/index.md}              | 0
 .../developer-guide/advanced-topics/plexus-class-loading.md}      | 0
 .../advanced-topics/programmatic-container-configuration.md}      | 0
 .../guides/developer-guide/appendices/javadoc-tags-reference.md}  | 0
 .../developer-guide/appendices/plexus-maven-plugin-reference.md}  | 0
 .../guides/developer-guide/building-applications/cdc.md}          | 0
 .../guides/developer-guide/building-applications/index.md}        | 0
 .../developer-guide/building-applications/runtime-builder.md}     | 0
 .../developer-guide/building-components/component-identity.md}    | 0
 .../developer-guide/building-components/component-testing.md}     | 0
 .../guides/developer-guide/building-components/index.md}          | 0
 .../building-components/instantiation-strategies.md}              | 0
 .../guides/developer-guide/building-pars.md}                      | 0
 .../guides/developer-guide/configuration/component-descriptor.md} | 0
 .../guides/developer-guide/configuration/index.md}                | 0
 .../developer-guide/configuration/plexus-auto-configuration.md}   | 0
 .../guides/developer-guide/deploying-pars.md}                     | 0
 .../guides/developer-guide/developing-components.md}              | 0
 .../index.apt => markdown/guides/developer-guide/index.md}        | 0
 .../guides/developer-guide/introduction-to-components.md}         | 0
 .../guides/developer-guide/introduction.md}                       | 0
 .../guides/developer-guide/lifecycle.md}                          | 0
 .../guides/developer-guide/personalities/avalon-personality.md}   | 0
 .../guides/developer-guide/personalities/index.md}                | 0
 .../guides/developer-guide/personalities/pico-personality.md}     | 0
 .../guides/developer-guide/personalities/plexus-personality.md}   | 0
 .../guides/developer-guide/personalities/spring-personality.md}   | 0
 .../guides/developer-guide/plexus-application-server.md}          | 0
 .../services.apt => markdown/guides/developer-guide/services.md}  | 0
 .../guides/plexus-web-applications/01_preparing_for_project.md}   | 0
 .../guides/plexus-web-applications/index.md}                      | 0
 .../guides/quick-start/component-descriptor-creator.md}           | 0
 .../embedder.apt => markdown/guides/quick-start/embedder.md}      | 0
 .../guides/quick-start/getting-started.md}                        | 0
 .../guides/quick-start/one-minute-tutorial.md}                    | 0
 .../guides/trails/index.apt => markdown/guides/trails/index.md}   | 0
 .../guides/writing-components/00_index.md}                        | 0
 .../guides/writing-components/01_preparing_for_project.md}        | 0
 .../guides/writing-components/02_diving_in.md}                    | 0
 .../guides/writing-components/03_joys_of_tdd.md}                  | 0
 .../guides/writing-components/04_more_bells_n_whistles.md}        | 0
 .../writing-components/05_01_custom_logging_implementation.md}    | 0
 .../guides/writing-components/05_configuring_to_get_it_right.md}  | 0
 .../guides/writing-components/06_we_have_a_component.md}          | 0
 .../guides/writing-components/07_01_configuring_monitor_mojo.md}  | 0
 .../guides/writing-components/07_01_from_a_maven_mojo.md}         | 0
 .../guides/writing-components/07_01_implementing_monitor_mojo.md} | 0
 .../writing-components/07_01_setting_up_mojo_unit_tests.md}       | 0
 .../guides/writing-components/07_02_from_a_plexus_application.md} | 0
 .../07_02_plexus_embedder_and_component_integration.md}           | 0
 .../guides/writing-components/07_03_from_a_web_application.md}    | 0
 .../writing-components/07_03_setting_up_a_web_application.md}     | 0
 .../guides/writing-components/07_04_from_a_soap_webservice.md}    | 0
 .../guides/writing-components/07_05_from_an_xmlrpc_service.md}    | 0
 .../guides/writing-components/07_component_usage_scenarios.md}    | 0
 .../guides/writing-components/08_packaging_up.md}                 | 0
 src/site/{apt/index.apt => markdown/index.md}                     | 0
 .../new-container-gotchas.md}                                     | 0
 .../ref/component-configuration.md}                               | 0
 .../feature-comparison.apt => markdown/ref/feature-comparison.md} | 0
 .../plexus-descriptor.apt => markdown/ref/plexus-descriptor.md}   | 0
 .../ref/plexus-services.apt => markdown/ref/plexus-services.md}   | 0
 .../technical-articles.apt => markdown/ref/technical-articles.md} | 0
 .../why-use-components.apt => markdown/ref/why-use-components.md} | 0
 65 files changed, 0 insertions(+), 0 deletions(-)
 rename src/site/{apt/guides/component-programming/index.apt => markdown/guides/component-programming/index.md} (100%)
 rename src/site/{apt/guides/developer-guide/advanced-topics/index.apt => markdown/guides/developer-guide/advanced-topics/index.md} (100%)
 rename src/site/{apt/guides/developer-guide/advanced-topics/plexus-class-loading.apt => markdown/guides/developer-guide/advanced-topics/plexus-class-loading.md} (100%)
 rename src/site/{apt/guides/developer-guide/advanced-topics/programmatic-container-configuration.apt => markdown/guides/developer-guide/advanced-topics/programmatic-container-configuration.md} (100%)
 rename src/site/{apt/guides/developer-guide/appendices/javadoc-tags-reference.apt => markdown/guides/developer-guide/appendices/javadoc-tags-reference.md} (100%)
 rename src/site/{apt/guides/developer-guide/appendices/plexus-maven-plugin-reference.apt => markdown/guides/developer-guide/appendices/plexus-maven-plugin-reference.md} (100%)
 rename src/site/{apt/guides/developer-guide/building-applications/cdc.apt => markdown/guides/developer-guide/building-applications/cdc.md} (100%)
 rename src/site/{apt/guides/developer-guide/building-applications/index.apt => markdown/guides/developer-guide/building-applications/index.md} (100%)
 rename src/site/{apt/guides/developer-guide/building-applications/runtime-builder.apt => markdown/guides/developer-guide/building-applications/runtime-builder.md} (100%)
 rename src/site/{apt/guides/developer-guide/building-components/component-identity.apt => markdown/guides/developer-guide/building-components/component-identity.md} (100%)
 rename src/site/{apt/guides/developer-guide/building-components/component-testing.apt => markdown/guides/developer-guide/building-components/component-testing.md} (100%)
 rename src/site/{apt/guides/developer-guide/building-components/index.apt => markdown/guides/developer-guide/building-components/index.md} (100%)
 rename src/site/{apt/guides/developer-guide/building-components/instantiation-strategies.apt => markdown/guides/developer-guide/building-components/instantiation-strategies.md} (100%)
 rename src/site/{apt/guides/developer-guide/building-pars.apt => markdown/guides/developer-guide/building-pars.md} (100%)
 rename src/site/{apt/guides/developer-guide/configuration/component-descriptor.apt => markdown/guides/developer-guide/configuration/component-descriptor.md} (100%)
 rename src/site/{apt/guides/developer-guide/configuration/index.apt => markdown/guides/developer-guide/configuration/index.md} (100%)
 rename src/site/{apt/guides/developer-guide/configuration/plexus-auto-configuration.apt => markdown/guides/developer-guide/configuration/plexus-auto-configuration.md} (100%)
 rename src/site/{apt/guides/developer-guide/deploying-pars.apt => markdown/guides/developer-guide/deploying-pars.md} (100%)
 rename src/site/{apt/guides/developer-guide/developing-components.apt => markdown/guides/developer-guide/developing-components.md} (100%)
 rename src/site/{apt/guides/developer-guide/index.apt => markdown/guides/developer-guide/index.md} (100%)
 rename src/site/{apt/guides/developer-guide/introduction-to-components.apt => markdown/guides/developer-guide/introduction-to-components.md} (100%)
 rename src/site/{apt/guides/developer-guide/introduction.apt => markdown/guides/developer-guide/introduction.md} (100%)
 rename src/site/{apt/guides/developer-guide/lifecycle.apt => markdown/guides/developer-guide/lifecycle.md} (100%)
 rename src/site/{apt/guides/developer-guide/personalities/avalon-personality.apt => markdown/guides/developer-guide/personalities/avalon-personality.md} (100%)
 rename src/site/{apt/guides/developer-guide/personalities/index.apt => markdown/guides/developer-guide/personalities/index.md} (100%)
 rename src/site/{apt/guides/developer-guide/personalities/pico-personality.apt => markdown/guides/developer-guide/personalities/pico-personality.md} (100%)
 rename src/site/{apt/guides/developer-guide/personalities/plexus-personality.apt => markdown/guides/developer-guide/personalities/plexus-personality.md} (100%)
 rename src/site/{apt/guides/developer-guide/personalities/spring-personality.apt => markdown/guides/developer-guide/personalities/spring-personality.md} (100%)
 rename src/site/{apt/guides/developer-guide/plexus-application-server.apt => markdown/guides/developer-guide/plexus-application-server.md} (100%)
 rename src/site/{apt/guides/developer-guide/services.apt => markdown/guides/developer-guide/services.md} (100%)
 rename src/site/{apt/guides/plexus-web-applications/01_preparing_for_project.apt => markdown/guides/plexus-web-applications/01_preparing_for_project.md} (100%)
 rename src/site/{apt/guides/plexus-web-applications/index.apt => markdown/guides/plexus-web-applications/index.md} (100%)
 rename src/site/{apt/guides/quick-start/component-descriptor-creator.apt => markdown/guides/quick-start/component-descriptor-creator.md} (100%)
 rename src/site/{apt/guides/quick-start/embedder.apt => markdown/guides/quick-start/embedder.md} (100%)
 rename src/site/{apt/guides/quick-start/getting-started.apt => markdown/guides/quick-start/getting-started.md} (100%)
 rename src/site/{apt/guides/quick-start/one-minute-tutorial.apt => markdown/guides/quick-start/one-minute-tutorial.md} (100%)
 rename src/site/{apt/guides/trails/index.apt => markdown/guides/trails/index.md} (100%)
 rename src/site/{apt/guides/writing-components/00_index.apt => markdown/guides/writing-components/00_index.md} (100%)
 rename src/site/{apt/guides/writing-components/01_preparing_for_project.apt => markdown/guides/writing-components/01_preparing_for_project.md} (100%)
 rename src/site/{apt/guides/writing-components/02_diving_in.apt => markdown/guides/writing-components/02_diving_in.md} (100%)
 rename src/site/{apt/guides/writing-components/03_joys_of_tdd.apt => markdown/guides/writing-components/03_joys_of_tdd.md} (100%)
 rename src/site/{apt/guides/writing-components/04_more_bells_n_whistles.apt => markdown/guides/writing-components/04_more_bells_n_whistles.md} (100%)
 rename src/site/{apt/guides/writing-components/05_01_custom_logging_implementation.apt => markdown/guides/writing-components/05_01_custom_logging_implementation.md} (100%)
 rename src/site/{apt/guides/writing-components/05_configuring_to_get_it_right.apt => markdown/guides/writing-components/05_configuring_to_get_it_right.md} (100%)
 rename src/site/{apt/guides/writing-components/06_we_have_a_component.apt => markdown/guides/writing-components/06_we_have_a_component.md} (100%)
 rename src/site/{apt/guides/writing-components/07_01_configuring_monitor_mojo.apt => markdown/guides/writing-components/07_01_configuring_monitor_mojo.md} (100%)
 rename src/site/{apt/guides/writing-components/07_01_from_a_maven_mojo.apt => markdown/guides/writing-components/07_01_from_a_maven_mojo.md} (100%)
 rename src/site/{apt/guides/writing-components/07_01_implementing_monitor_mojo.apt => markdown/guides/writing-components/07_01_implementing_monitor_mojo.md} (100%)
 rename src/site/{apt/guides/writing-components/07_01_setting_up_mojo_unit_tests.apt => markdown/guides/writing-components/07_01_setting_up_mojo_unit_tests.md} (100%)
 rename src/site/{apt/guides/writing-components/07_02_from_a_plexus_application.apt => markdown/guides/writing-components/07_02_from_a_plexus_application.md} (100%)
 rename src/site/{apt/guides/writing-components/07_02_plexus_embedder_and_component_integration.apt => markdown/guides/writing-components/07_02_plexus_embedder_and_component_integration.md} (100%)
 rename src/site/{apt/guides/writing-components/07_03_from_a_web_application.apt => markdown/guides/writing-components/07_03_from_a_web_application.md} (100%)
 rename src/site/{apt/guides/writing-components/07_03_setting_up_a_web_application.apt => markdown/guides/writing-components/07_03_setting_up_a_web_application.md} (100%)
 rename src/site/{apt/guides/writing-components/07_04_from_a_soap_webservice.apt => markdown/guides/writing-components/07_04_from_a_soap_webservice.md} (100%)
 rename src/site/{apt/guides/writing-components/07_05_from_an_xmlrpc_service.apt => markdown/guides/writing-components/07_05_from_an_xmlrpc_service.md} (100%)
 rename src/site/{apt/guides/writing-components/07_component_usage_scenarios.apt => markdown/guides/writing-components/07_component_usage_scenarios.md} (100%)
 rename src/site/{apt/guides/writing-components/08_packaging_up.apt => markdown/guides/writing-components/08_packaging_up.md} (100%)
 rename src/site/{apt/index.apt => markdown/index.md} (100%)
 rename src/site/{apt/new-container-gotchas.apt => markdown/new-container-gotchas.md} (100%)
 rename src/site/{apt/ref/component-configuration.apt => markdown/ref/component-configuration.md} (100%)
 rename src/site/{apt/ref/feature-comparison.apt => markdown/ref/feature-comparison.md} (100%)
 rename src/site/{apt/ref/plexus-descriptor.apt => markdown/ref/plexus-descriptor.md} (100%)
 rename src/site/{apt/ref/plexus-services.apt => markdown/ref/plexus-services.md} (100%)
 rename src/site/{apt/ref/technical-articles.apt => markdown/ref/technical-articles.md} (100%)
 rename src/site/{apt/ref/why-use-components.apt => markdown/ref/why-use-components.md} (100%)

diff --git a/src/site/apt/guides/component-programming/index.apt b/src/site/markdown/guides/component-programming/index.md
similarity index 100%
rename from src/site/apt/guides/component-programming/index.apt
rename to src/site/markdown/guides/component-programming/index.md
diff --git a/src/site/apt/guides/developer-guide/advanced-topics/index.apt b/src/site/markdown/guides/developer-guide/advanced-topics/index.md
similarity index 100%
rename from src/site/apt/guides/developer-guide/advanced-topics/index.apt
rename to src/site/markdown/guides/developer-guide/advanced-topics/index.md
diff --git a/src/site/apt/guides/developer-guide/advanced-topics/plexus-class-loading.apt b/src/site/markdown/guides/developer-guide/advanced-topics/plexus-class-loading.md
similarity index 100%
rename from src/site/apt/guides/developer-guide/advanced-topics/plexus-class-loading.apt
rename to src/site/markdown/guides/developer-guide/advanced-topics/plexus-class-loading.md
diff --git a/src/site/apt/guides/developer-guide/advanced-topics/programmatic-container-configuration.apt b/src/site/markdown/guides/developer-guide/advanced-topics/programmatic-container-configuration.md
similarity index 100%
rename from src/site/apt/guides/developer-guide/advanced-topics/programmatic-container-configuration.apt
rename to src/site/markdown/guides/developer-guide/advanced-topics/programmatic-container-configuration.md
diff --git a/src/site/apt/guides/developer-guide/appendices/javadoc-tags-reference.apt b/src/site/markdown/guides/developer-guide/appendices/javadoc-tags-reference.md
similarity index 100%
rename from src/site/apt/guides/developer-guide/appendices/javadoc-tags-reference.apt
rename to src/site/markdown/guides/developer-guide/appendices/javadoc-tags-reference.md
diff --git a/src/site/apt/guides/developer-guide/appendices/plexus-maven-plugin-reference.apt b/src/site/markdown/guides/developer-guide/appendices/plexus-maven-plugin-reference.md
similarity index 100%
rename from src/site/apt/guides/developer-guide/appendices/plexus-maven-plugin-reference.apt
rename to src/site/markdown/guides/developer-guide/appendices/plexus-maven-plugin-reference.md
diff --git a/src/site/apt/guides/developer-guide/building-applications/cdc.apt b/src/site/markdown/guides/developer-guide/building-applications/cdc.md
similarity index 100%
rename from src/site/apt/guides/developer-guide/building-applications/cdc.apt
rename to src/site/markdown/guides/developer-guide/building-applications/cdc.md
diff --git a/src/site/apt/guides/developer-guide/building-applications/index.apt b/src/site/markdown/guides/developer-guide/building-applications/index.md
similarity index 100%
rename from src/site/apt/guides/developer-guide/building-applications/index.apt
rename to src/site/markdown/guides/developer-guide/building-applications/index.md
diff --git a/src/site/apt/guides/developer-guide/building-applications/runtime-builder.apt b/src/site/markdown/guides/developer-guide/building-applications/runtime-builder.md
similarity index 100%
rename from src/site/apt/guides/developer-guide/building-applications/runtime-builder.apt
rename to src/site/markdown/guides/developer-guide/building-applications/runtime-builder.md
diff --git a/src/site/apt/guides/developer-guide/building-components/component-identity.apt b/src/site/markdown/guides/developer-guide/building-components/component-identity.md
similarity index 100%
rename from src/site/apt/guides/developer-guide/building-components/component-identity.apt
rename to src/site/markdown/guides/developer-guide/building-components/component-identity.md
diff --git a/src/site/apt/guides/developer-guide/building-components/component-testing.apt b/src/site/markdown/guides/developer-guide/building-components/component-testing.md
similarity index 100%
rename from src/site/apt/guides/developer-guide/building-components/component-testing.apt
rename to src/site/markdown/guides/developer-guide/building-components/component-testing.md
diff --git a/src/site/apt/guides/developer-guide/building-components/index.apt b/src/site/markdown/guides/developer-guide/building-components/index.md
similarity index 100%
rename from src/site/apt/guides/developer-guide/building-components/index.apt
rename to src/site/markdown/guides/developer-guide/building-components/index.md
diff --git a/src/site/apt/guides/developer-guide/building-components/instantiation-strategies.apt b/src/site/markdown/guides/developer-guide/building-components/instantiation-strategies.md
similarity index 100%
rename from src/site/apt/guides/developer-guide/building-components/instantiation-strategies.apt
rename to src/site/markdown/guides/developer-guide/building-components/instantiation-strategies.md
diff --git a/src/site/apt/guides/developer-guide/building-pars.apt b/src/site/markdown/guides/developer-guide/building-pars.md
similarity index 100%
rename from src/site/apt/guides/developer-guide/building-pars.apt
rename to src/site/markdown/guides/developer-guide/building-pars.md
diff --git a/src/site/apt/guides/developer-guide/configuration/component-descriptor.apt b/src/site/markdown/guides/developer-guide/configuration/component-descriptor.md
similarity index 100%
rename from src/site/apt/guides/developer-guide/configuration/component-descriptor.apt
rename to src/site/markdown/guides/developer-guide/configuration/component-descriptor.md
diff --git a/src/site/apt/guides/developer-guide/configuration/index.apt b/src/site/markdown/guides/developer-guide/configuration/index.md
similarity index 100%
rename from src/site/apt/guides/developer-guide/configuration/index.apt
rename to src/site/markdown/guides/developer-guide/configuration/index.md
diff --git a/src/site/apt/guides/developer-guide/configuration/plexus-auto-configuration.apt b/src/site/markdown/guides/developer-guide/configuration/plexus-auto-configuration.md
similarity index 100%
rename from src/site/apt/guides/developer-guide/configuration/plexus-auto-configuration.apt
rename to src/site/markdown/guides/developer-guide/configuration/plexus-auto-configuration.md
diff --git a/src/site/apt/guides/developer-guide/deploying-pars.apt b/src/site/markdown/guides/developer-guide/deploying-pars.md
similarity index 100%
rename from src/site/apt/guides/developer-guide/deploying-pars.apt
rename to src/site/markdown/guides/developer-guide/deploying-pars.md
diff --git a/src/site/apt/guides/developer-guide/developing-components.apt b/src/site/markdown/guides/developer-guide/developing-components.md
similarity index 100%
rename from src/site/apt/guides/developer-guide/developing-components.apt
rename to src/site/markdown/guides/developer-guide/developing-components.md
diff --git a/src/site/apt/guides/developer-guide/index.apt b/src/site/markdown/guides/developer-guide/index.md
similarity index 100%
rename from src/site/apt/guides/developer-guide/index.apt
rename to src/site/markdown/guides/developer-guide/index.md
diff --git a/src/site/apt/guides/developer-guide/introduction-to-components.apt b/src/site/markdown/guides/developer-guide/introduction-to-components.md
similarity index 100%
rename from src/site/apt/guides/developer-guide/introduction-to-components.apt
rename to src/site/markdown/guides/developer-guide/introduction-to-components.md
diff --git a/src/site/apt/guides/developer-guide/introduction.apt b/src/site/markdown/guides/developer-guide/introduction.md
similarity index 100%
rename from src/site/apt/guides/developer-guide/introduction.apt
rename to src/site/markdown/guides/developer-guide/introduction.md
diff --git a/src/site/apt/guides/developer-guide/lifecycle.apt b/src/site/markdown/guides/developer-guide/lifecycle.md
similarity index 100%
rename from src/site/apt/guides/developer-guide/lifecycle.apt
rename to src/site/markdown/guides/developer-guide/lifecycle.md
diff --git a/src/site/apt/guides/developer-guide/personalities/avalon-personality.apt b/src/site/markdown/guides/developer-guide/personalities/avalon-personality.md
similarity index 100%
rename from src/site/apt/guides/developer-guide/personalities/avalon-personality.apt
rename to src/site/markdown/guides/developer-guide/personalities/avalon-personality.md
diff --git a/src/site/apt/guides/developer-guide/personalities/index.apt b/src/site/markdown/guides/developer-guide/personalities/index.md
similarity index 100%
rename from src/site/apt/guides/developer-guide/personalities/index.apt
rename to src/site/markdown/guides/developer-guide/personalities/index.md
diff --git a/src/site/apt/guides/developer-guide/personalities/pico-personality.apt b/src/site/markdown/guides/developer-guide/personalities/pico-personality.md
similarity index 100%
rename from src/site/apt/guides/developer-guide/personalities/pico-personality.apt
rename to src/site/markdown/guides/developer-guide/personalities/pico-personality.md
diff --git a/src/site/apt/guides/developer-guide/personalities/plexus-personality.apt b/src/site/markdown/guides/developer-guide/personalities/plexus-personality.md
similarity index 100%
rename from src/site/apt/guides/developer-guide/personalities/plexus-personality.apt
rename to src/site/markdown/guides/developer-guide/personalities/plexus-personality.md
diff --git a/src/site/apt/guides/developer-guide/personalities/spring-personality.apt b/src/site/markdown/guides/developer-guide/personalities/spring-personality.md
similarity index 100%
rename from src/site/apt/guides/developer-guide/personalities/spring-personality.apt
rename to src/site/markdown/guides/developer-guide/personalities/spring-personality.md
diff --git a/src/site/apt/guides/developer-guide/plexus-application-server.apt b/src/site/markdown/guides/developer-guide/plexus-application-server.md
similarity index 100%
rename from src/site/apt/guides/developer-guide/plexus-application-server.apt
rename to src/site/markdown/guides/developer-guide/plexus-application-server.md
diff --git a/src/site/apt/guides/developer-guide/services.apt b/src/site/markdown/guides/developer-guide/services.md
similarity index 100%
rename from src/site/apt/guides/developer-guide/services.apt
rename to src/site/markdown/guides/developer-guide/services.md
diff --git a/src/site/apt/guides/plexus-web-applications/01_preparing_for_project.apt b/src/site/markdown/guides/plexus-web-applications/01_preparing_for_project.md
similarity index 100%
rename from src/site/apt/guides/plexus-web-applications/01_preparing_for_project.apt
rename to src/site/markdown/guides/plexus-web-applications/01_preparing_for_project.md
diff --git a/src/site/apt/guides/plexus-web-applications/index.apt b/src/site/markdown/guides/plexus-web-applications/index.md
similarity index 100%
rename from src/site/apt/guides/plexus-web-applications/index.apt
rename to src/site/markdown/guides/plexus-web-applications/index.md
diff --git a/src/site/apt/guides/quick-start/component-descriptor-creator.apt b/src/site/markdown/guides/quick-start/component-descriptor-creator.md
similarity index 100%
rename from src/site/apt/guides/quick-start/component-descriptor-creator.apt
rename to src/site/markdown/guides/quick-start/component-descriptor-creator.md
diff --git a/src/site/apt/guides/quick-start/embedder.apt b/src/site/markdown/guides/quick-start/embedder.md
similarity index 100%
rename from src/site/apt/guides/quick-start/embedder.apt
rename to src/site/markdown/guides/quick-start/embedder.md
diff --git a/src/site/apt/guides/quick-start/getting-started.apt b/src/site/markdown/guides/quick-start/getting-started.md
similarity index 100%
rename from src/site/apt/guides/quick-start/getting-started.apt
rename to src/site/markdown/guides/quick-start/getting-started.md
diff --git a/src/site/apt/guides/quick-start/one-minute-tutorial.apt b/src/site/markdown/guides/quick-start/one-minute-tutorial.md
similarity index 100%
rename from src/site/apt/guides/quick-start/one-minute-tutorial.apt
rename to src/site/markdown/guides/quick-start/one-minute-tutorial.md
diff --git a/src/site/apt/guides/trails/index.apt b/src/site/markdown/guides/trails/index.md
similarity index 100%
rename from src/site/apt/guides/trails/index.apt
rename to src/site/markdown/guides/trails/index.md
diff --git a/src/site/apt/guides/writing-components/00_index.apt b/src/site/markdown/guides/writing-components/00_index.md
similarity index 100%
rename from src/site/apt/guides/writing-components/00_index.apt
rename to src/site/markdown/guides/writing-components/00_index.md
diff --git a/src/site/apt/guides/writing-components/01_preparing_for_project.apt b/src/site/markdown/guides/writing-components/01_preparing_for_project.md
similarity index 100%
rename from src/site/apt/guides/writing-components/01_preparing_for_project.apt
rename to src/site/markdown/guides/writing-components/01_preparing_for_project.md
diff --git a/src/site/apt/guides/writing-components/02_diving_in.apt b/src/site/markdown/guides/writing-components/02_diving_in.md
similarity index 100%
rename from src/site/apt/guides/writing-components/02_diving_in.apt
rename to src/site/markdown/guides/writing-components/02_diving_in.md
diff --git a/src/site/apt/guides/writing-components/03_joys_of_tdd.apt b/src/site/markdown/guides/writing-components/03_joys_of_tdd.md
similarity index 100%
rename from src/site/apt/guides/writing-components/03_joys_of_tdd.apt
rename to src/site/markdown/guides/writing-components/03_joys_of_tdd.md
diff --git a/src/site/apt/guides/writing-components/04_more_bells_n_whistles.apt b/src/site/markdown/guides/writing-components/04_more_bells_n_whistles.md
similarity index 100%
rename from src/site/apt/guides/writing-components/04_more_bells_n_whistles.apt
rename to src/site/markdown/guides/writing-components/04_more_bells_n_whistles.md
diff --git a/src/site/apt/guides/writing-components/05_01_custom_logging_implementation.apt b/src/site/markdown/guides/writing-components/05_01_custom_logging_implementation.md
similarity index 100%
rename from src/site/apt/guides/writing-components/05_01_custom_logging_implementation.apt
rename to src/site/markdown/guides/writing-components/05_01_custom_logging_implementation.md
diff --git a/src/site/apt/guides/writing-components/05_configuring_to_get_it_right.apt b/src/site/markdown/guides/writing-components/05_configuring_to_get_it_right.md
similarity index 100%
rename from src/site/apt/guides/writing-components/05_configuring_to_get_it_right.apt
rename to src/site/markdown/guides/writing-components/05_configuring_to_get_it_right.md
diff --git a/src/site/apt/guides/writing-components/06_we_have_a_component.apt b/src/site/markdown/guides/writing-components/06_we_have_a_component.md
similarity index 100%
rename from src/site/apt/guides/writing-components/06_we_have_a_component.apt
rename to src/site/markdown/guides/writing-components/06_we_have_a_component.md
diff --git a/src/site/apt/guides/writing-components/07_01_configuring_monitor_mojo.apt b/src/site/markdown/guides/writing-components/07_01_configuring_monitor_mojo.md
similarity index 100%
rename from src/site/apt/guides/writing-components/07_01_configuring_monitor_mojo.apt
rename to src/site/markdown/guides/writing-components/07_01_configuring_monitor_mojo.md
diff --git a/src/site/apt/guides/writing-components/07_01_from_a_maven_mojo.apt b/src/site/markdown/guides/writing-components/07_01_from_a_maven_mojo.md
similarity index 100%
rename from src/site/apt/guides/writing-components/07_01_from_a_maven_mojo.apt
rename to src/site/markdown/guides/writing-components/07_01_from_a_maven_mojo.md
diff --git a/src/site/apt/guides/writing-components/07_01_implementing_monitor_mojo.apt b/src/site/markdown/guides/writing-components/07_01_implementing_monitor_mojo.md
similarity index 100%
rename from src/site/apt/guides/writing-components/07_01_implementing_monitor_mojo.apt
rename to src/site/markdown/guides/writing-components/07_01_implementing_monitor_mojo.md
diff --git a/src/site/apt/guides/writing-components/07_01_setting_up_mojo_unit_tests.apt b/src/site/markdown/guides/writing-components/07_01_setting_up_mojo_unit_tests.md
similarity index 100%
rename from src/site/apt/guides/writing-components/07_01_setting_up_mojo_unit_tests.apt
rename to src/site/markdown/guides/writing-components/07_01_setting_up_mojo_unit_tests.md
diff --git a/src/site/apt/guides/writing-components/07_02_from_a_plexus_application.apt b/src/site/markdown/guides/writing-components/07_02_from_a_plexus_application.md
similarity index 100%
rename from src/site/apt/guides/writing-components/07_02_from_a_plexus_application.apt
rename to src/site/markdown/guides/writing-components/07_02_from_a_plexus_application.md
diff --git a/src/site/apt/guides/writing-components/07_02_plexus_embedder_and_component_integration.apt b/src/site/markdown/guides/writing-components/07_02_plexus_embedder_and_component_integration.md
similarity index 100%
rename from src/site/apt/guides/writing-components/07_02_plexus_embedder_and_component_integration.apt
rename to src/site/markdown/guides/writing-components/07_02_plexus_embedder_and_component_integration.md
diff --git a/src/site/apt/guides/writing-components/07_03_from_a_web_application.apt b/src/site/markdown/guides/writing-components/07_03_from_a_web_application.md
similarity index 100%
rename from src/site/apt/guides/writing-components/07_03_from_a_web_application.apt
rename to src/site/markdown/guides/writing-components/07_03_from_a_web_application.md
diff --git a/src/site/apt/guides/writing-components/07_03_setting_up_a_web_application.apt b/src/site/markdown/guides/writing-components/07_03_setting_up_a_web_application.md
similarity index 100%
rename from src/site/apt/guides/writing-components/07_03_setting_up_a_web_application.apt
rename to src/site/markdown/guides/writing-components/07_03_setting_up_a_web_application.md
diff --git a/src/site/apt/guides/writing-components/07_04_from_a_soap_webservice.apt b/src/site/markdown/guides/writing-components/07_04_from_a_soap_webservice.md
similarity index 100%
rename from src/site/apt/guides/writing-components/07_04_from_a_soap_webservice.apt
rename to src/site/markdown/guides/writing-components/07_04_from_a_soap_webservice.md
diff --git a/src/site/apt/guides/writing-components/07_05_from_an_xmlrpc_service.apt b/src/site/markdown/guides/writing-components/07_05_from_an_xmlrpc_service.md
similarity index 100%
rename from src/site/apt/guides/writing-components/07_05_from_an_xmlrpc_service.apt
rename to src/site/markdown/guides/writing-components/07_05_from_an_xmlrpc_service.md
diff --git a/src/site/apt/guides/writing-components/07_component_usage_scenarios.apt b/src/site/markdown/guides/writing-components/07_component_usage_scenarios.md
similarity index 100%
rename from src/site/apt/guides/writing-components/07_component_usage_scenarios.apt
rename to src/site/markdown/guides/writing-components/07_component_usage_scenarios.md
diff --git a/src/site/apt/guides/writing-components/08_packaging_up.apt b/src/site/markdown/guides/writing-components/08_packaging_up.md
similarity index 100%
rename from src/site/apt/guides/writing-components/08_packaging_up.apt
rename to src/site/markdown/guides/writing-components/08_packaging_up.md
diff --git a/src/site/apt/index.apt b/src/site/markdown/index.md
similarity index 100%
rename from src/site/apt/index.apt
rename to src/site/markdown/index.md
diff --git a/src/site/apt/new-container-gotchas.apt b/src/site/markdown/new-container-gotchas.md
similarity index 100%
rename from src/site/apt/new-container-gotchas.apt
rename to src/site/markdown/new-container-gotchas.md
diff --git a/src/site/apt/ref/component-configuration.apt b/src/site/markdown/ref/component-configuration.md
similarity index 100%
rename from src/site/apt/ref/component-configuration.apt
rename to src/site/markdown/ref/component-configuration.md
diff --git a/src/site/apt/ref/feature-comparison.apt b/src/site/markdown/ref/feature-comparison.md
similarity index 100%
rename from src/site/apt/ref/feature-comparison.apt
rename to src/site/markdown/ref/feature-comparison.md
diff --git a/src/site/apt/ref/plexus-descriptor.apt b/src/site/markdown/ref/plexus-descriptor.md
similarity index 100%
rename from src/site/apt/ref/plexus-descriptor.apt
rename to src/site/markdown/ref/plexus-descriptor.md
diff --git a/src/site/apt/ref/plexus-services.apt b/src/site/markdown/ref/plexus-services.md
similarity index 100%
rename from src/site/apt/ref/plexus-services.apt
rename to src/site/markdown/ref/plexus-services.md
diff --git a/src/site/apt/ref/technical-articles.apt b/src/site/markdown/ref/technical-articles.md
similarity index 100%
rename from src/site/apt/ref/technical-articles.apt
rename to src/site/markdown/ref/technical-articles.md
diff --git a/src/site/apt/ref/why-use-components.apt b/src/site/markdown/ref/why-use-components.md
similarity index 100%
rename from src/site/apt/ref/why-use-components.apt
rename to src/site/markdown/ref/why-use-components.md

From e9a6d45d5a3a5e0679fdfcabc24b236504493de7 Mon Sep 17 00:00:00 2001
From: Sylwester Lachiewicz <slachiewicz@apache.org>
Date: Sat, 8 Aug 2026 21:56:58 +0200
Subject: [PATCH 2/2] Convert the site documents from APT to Markdown

65 pages, converted with doxia-converter and then cleaned up. The
converter has several defects that are invisible in the Markdown and
only appear in the generated HTML, so each was found by building the
site before and after and diffing the normalised pages.

Multiple authors were the worst: an APT header may list several, and
the converter emits the first inline after 'author:' and the rest on
bare continuation lines. A parser that stops at the second author loses
everything after it, including the date, which then renders as body
text. Ten pages were affected. Repeated YAML keys do not work either -
the last wins - so multiple authors are emitted as a list.

Other defects repaired: front matter emitted without its fences,
headings shifted down a level, source indentation left in place so
prose became code blocks, APT ordered lists emitted as '1 Item' with no
period so they rendered as literal text, self-referential anchor links
losing both their label and their leading '#', emphasis emitted with
padding so it rendered as literal asterisks, and backslash escapes left
inside code spans and in front of characters that are not markup.

URLs are unchanged: an .apt and a .md of the same name both produce the
same .html.

66 of 73 pages are byte-identical after normalisation, metadata
included. The seven that differ are described in the pull request; none
loses content. Internal link checking finds the same five pre-existing
broken links as before, and no new ones.
---
 .../guides/component-programming/index.md     |  26 +--
 .../developer-guide/advanced-topics/index.md  |  14 +-
 .../advanced-topics/plexus-class-loading.md   |  14 +-
 .../programmatic-container-configuration.md   |  14 +-
 .../appendices/javadoc-tags-reference.md      |  97 +++-----
 .../plexus-maven-plugin-reference.md          |  18 +-
 .../building-applications/cdc.md              | 140 +++++------
 .../building-applications/index.md            | 212 ++++++++---------
 .../building-applications/runtime-builder.md  |  20 +-
 .../building-components/component-identity.md |  74 +++---
 .../building-components/component-testing.md  | 217 +++++++-----------
 .../building-components/index.md              |  15 +-
 .../instantiation-strategies.md               |  17 +-
 .../guides/developer-guide/building-pars.md   |  14 +-
 .../configuration/component-descriptor.md     | 206 ++++++-----------
 .../developer-guide/configuration/index.md    | 126 +++++-----
 .../plexus-auto-configuration.md              | 140 ++++++-----
 .../guides/developer-guide/deploying-pars.md  |  14 +-
 .../developer-guide/developing-components.md  |  14 +-
 .../markdown/guides/developer-guide/index.md  |  78 +++----
 .../introduction-to-components.md             |  55 ++---
 .../guides/developer-guide/introduction.md    |  14 +-
 .../guides/developer-guide/lifecycle.md       |  14 +-
 .../personalities/avalon-personality.md       |  54 ++---
 .../developer-guide/personalities/index.md    | 100 +++-----
 .../personalities/pico-personality.md         |  75 ++----
 .../personalities/plexus-personality.md       |  89 +++----
 .../personalities/spring-personality.md       |  16 +-
 .../plexus-application-server.md              |  14 +-
 .../guides/developer-guide/services.md        |  14 +-
 .../01_preparing_for_project.md               | 152 ++++++------
 .../guides/plexus-web-applications/index.md   |  23 +-
 .../component-descriptor-creator.md           | 125 +++++-----
 .../markdown/guides/quick-start/embedder.md   |  26 +--
 .../guides/quick-start/getting-started.md     | 119 ++++------
 .../guides/quick-start/one-minute-tutorial.md |  24 +-
 src/site/markdown/guides/trails/index.md      |  53 ++---
 .../guides/writing-components/00_index.md     |  79 +++----
 .../01_preparing_for_project.md               | 137 +++++------
 .../guides/writing-components/02_diving_in.md |  92 ++++----
 .../writing-components/03_joys_of_tdd.md      |  39 ++--
 .../04_more_bells_n_whistles.md               |  29 +--
 .../05_01_custom_logging_implementation.md    |  56 ++---
 .../05_configuring_to_get_it_right.md         |  53 ++---
 .../06_we_have_a_component.md                 |  17 +-
 .../07_01_configuring_monitor_mojo.md         |  77 +++----
 .../07_01_from_a_maven_mojo.md                |  68 +++---
 .../07_01_implementing_monitor_mojo.md        |  83 +++----
 .../07_01_setting_up_mojo_unit_tests.md       | 120 ++++------
 .../07_02_from_a_plexus_application.md        | 153 ++++++------
 ...exus_embedder_and_component_integration.md |  77 +++----
 .../07_03_from_a_web_application.md           | 119 ++++------
 .../07_03_setting_up_a_web_application.md     | 121 ++++------
 .../07_04_from_a_soap_webservice.md           |  16 +-
 .../07_05_from_an_xmlrpc_service.md           |  16 +-
 .../07_component_usage_scenarios.md           |  16 +-
 .../writing-components/08_packaging_up.md     |  22 +-
 src/site/markdown/index.md                    | 124 ++++------
 src/site/markdown/new-container-gotchas.md    |  45 ++--
 .../markdown/ref/component-configuration.md   |  91 ++++----
 src/site/markdown/ref/feature-comparison.md   |  76 ++----
 src/site/markdown/ref/plexus-descriptor.md    |  16 +-
 src/site/markdown/ref/plexus-services.md      |  85 +++----
 src/site/markdown/ref/technical-articles.md   |  16 +-
 src/site/markdown/ref/why-use-components.md   | 183 ++++++---------
 65 files changed, 1816 insertions(+), 2647 deletions(-)

diff --git a/src/site/markdown/guides/component-programming/index.md b/src/site/markdown/guides/component-programming/index.md
index 6e879da..29300f1 100644
--- a/src/site/markdown/guides/component-programming/index.md
+++ b/src/site/markdown/guides/component-programming/index.md
@@ -1,21 +1,17 @@
- ------
- User Guide - Component-oriented Programming
- ------
- Rahul Thakur
- ------
-2006-06-17
- ------
+---
+title: User Guide - Component-oriented Programming
+author: Rahul Thakur
+date: 2006-06-17
+---
 
-What is a Component? 
+# What is a Component?
 
-  TODO 
+TODO
 
+# What is Component-oriented Programming (COP) all about?
 
-What is Component-oriented Programming (COP) all about? 
+TODO
 
-  TODO
+# Where does Plexus fit into picture?
 
-
-Where does Plexus fit into picture? 
-
-  TODO
+TODO
diff --git a/src/site/markdown/guides/developer-guide/advanced-topics/index.md b/src/site/markdown/guides/developer-guide/advanced-topics/index.md
index 6cb6b1d..6c6de76 100644
--- a/src/site/markdown/guides/developer-guide/advanced-topics/index.md
+++ b/src/site/markdown/guides/developer-guide/advanced-topics/index.md
@@ -1,9 +1,7 @@
- ------
- Developer Guide - Advanced Topics
- ------
- Rahul Thakur
- ------
-2006-06-17
- ------
+---
+title: Developer Guide - Advanced Topics
+author: Rahul Thakur
+date: 2006-06-17
+---
 
-Advanced Plexus Topics
+# Advanced Plexus Topics
diff --git a/src/site/markdown/guides/developer-guide/advanced-topics/plexus-class-loading.md b/src/site/markdown/guides/developer-guide/advanced-topics/plexus-class-loading.md
index 4175d97..a08ad71 100644
--- a/src/site/markdown/guides/developer-guide/advanced-topics/plexus-class-loading.md
+++ b/src/site/markdown/guides/developer-guide/advanced-topics/plexus-class-loading.md
@@ -1,9 +1,7 @@
- ------
- Developer Guide - Advanced Topics - Plexus Class Loading
- ------
- Rahul Thakur
- ------
-2006-06-17
- ------
+---
+title: Developer Guide - Advanced Topics - Plexus Class Loading
+author: Rahul Thakur
+date: 2006-06-17
+---
 
-Class Loading in Plexus
+# Class Loading in Plexus
diff --git a/src/site/markdown/guides/developer-guide/advanced-topics/programmatic-container-configuration.md b/src/site/markdown/guides/developer-guide/advanced-topics/programmatic-container-configuration.md
index 898a268..311bfaa 100644
--- a/src/site/markdown/guides/developer-guide/advanced-topics/programmatic-container-configuration.md
+++ b/src/site/markdown/guides/developer-guide/advanced-topics/programmatic-container-configuration.md
@@ -1,9 +1,7 @@
- ------
- Developer Guide - Advanced Topics - Programmatic Container Configuration
- ------
- Rahul Thakur
- ------
-2006-06-17
- ------
+---
+title: Developer Guide - Advanced Topics - Programmatic Container Configuration
+author: Rahul Thakur
+date: 2006-06-17
+---
 
-Configuring the Plexus Container Programmatically
+# Configuring the Plexus Container Programmatically
diff --git a/src/site/markdown/guides/developer-guide/appendices/javadoc-tags-reference.md b/src/site/markdown/guides/developer-guide/appendices/javadoc-tags-reference.md
index 15e4f50..27c664b 100644
--- a/src/site/markdown/guides/developer-guide/appendices/javadoc-tags-reference.md
+++ b/src/site/markdown/guides/developer-guide/appendices/javadoc-tags-reference.md
@@ -1,77 +1,48 @@
- ------
- Developer Guide - Appendix I: Plexus Javadoc Tags Reference
- ------
- Rahul Thakur
- Emmanuel Venisse
-------
-2006-07-09
- ------
+---
+title: Developer Guide - Appendix I: Plexus Javadoc Tags Reference
+author:
+  - Rahul Thakur
+  - Emmanuel Venisse
+date: 2006-07-09
+---
 
- <<<The contents of this document are a work in progress>>>
+`The contents of this document are a work in progress`
 
-Javadoc Tags used by Plexus tools
+# Javadoc Tags used by Plexus tools
 
- Here is a reference of the Javadoc annotations that can be used to 'decorate' 
- the Java sources to allow Plexus tools like Component Descriptor Creator (CDC)
- to generate Component Descriptors.
+Here is a reference of the Javadoc annotations that can be used to 'decorate' the Java sources to allow Plexus tools like Component Descriptor Creator (CDC) to generate Component Descriptors.
 
-*-----+------+------+------+
-|<<Tag/Annotation>>|<<Available on>>|<<Required>>|<<Descriptor Element>>|
-*-----*------*------*------*
-| {{{#@plexus.component}@plexus.component}} | Class | Yes | Indicate to Plexus CDC that the class is a component |
-*-----*------*------*------*
-| {{{#@plexus.configuration}@plexus.configuration}} | Field | No | Tell Plexus CDC that this item should be configured through the <<<components.xml>>> |
-*-----*------*------*------*
-| {{{#@plexus.requirement}@plexus.requirement}} | Field | No | Indicate to Plexus CDC that the field is required by the component |
-*-----*------*------*------*
+|**Tag/Annotation**|**Available on**|**Required**|**Descriptor Element**|
+|---|---|---|---|
+|[@plexus.component](#@plexus.component)|Class|Yes|Indicate to Plexus CDC that the class is a component|
+|[@plexus.configuration](#@plexus.configuration)|Field|No|Tell Plexus CDC that this item should be configured through the `components.xml`|
+|[@plexus.requirement](#@plexus.requirement)|Field|No|Indicate to Plexus CDC that the field is required by the component|
 
-{@plexus.component}
+# @plexus.component
 
-  The <<<@plexus.component>>> tag is used to show that the class it annotates
-is a plexus component. This will add a <<<<component>>>> element to the
-<<<<components>>>> in components.xml. The following parameters are available,
-but remember the <<<role>>> is required.
-  The text in the javadoc tag describing this class is copied into the
-component's <<<<description>>>> tag.
+The `@plexus.component` tag is used to show that the class it annotates is a plexus component. This will add a `<component`\> element to the `<components`\> in components.xml. The following parameters are available, but remember the `role` is required. The text in the javadoc tag describing this class is copied into the component's `<description`\> tag.
 
-*-----+------+------+
-|<<Parameter>>|<<Required>>|<<Description>>|
-*-----*------*------*
-| role | Yes | The role that this class provides an implementation for (usually the class name of an implemented Interface |
-*-----*------*------*
-| role-hint | No | The hints are used to differentiate multiple implementations of the same role |
-*-----*------*------*
-| version | No | Set the version of the component |
-*-----*------*------*
+|**Parameter**|**Required**|**Description**|
+|---|---|---|
+|role|Yes|The role that this class provides an implementation for (usually the class name of an implemented Interface|
+|role-hint|No|The hints are used to differentiate multiple implementations of the same role|
+|version|No|Set the version of the component|
 
-{@plexus.configuration}
+# @plexus.configuration
 
-  The <<<@plexus.configuration>>> tags are used to mark fields in a class for
-configuration through the <<<components.xml>>>.
+The `@plexus.configuration` tags are used to mark fields in a class for configuration through the `components.xml`.
 
-*-----+------+------+
-|<<Parameter>>|<<Required>>|<<Description>>|
-*-----*------*------*
-| default-value | Currently | The default values are currently required for the <<<<configuration>>>> tag to be written to <<<components.xml>>>.
-*-----*------*------*
+|**Parameter**|**Required**|**Description**|
+|---|---|---|
+|default-value|Currently|The default values are currently required for the `<configuration`> tag to be written to `components.xml`.|
 
-{@plexus.requirement}
+# @plexus.requirement
 
-  Tagging a field with <<<@plexus.requirement>>> will tell plexus to inject
-the required component or list of components before the component itself is
-started. Fields can be of the type of the Interface defining the component you
-wish to be injected or of type <<<java.util.List>>> or <<<java.util.Map>>>.
+Tagging a field with `@plexus.requirement` will tell plexus to inject the required component or list of components before the component itself is started. Fields can be of the type of the Interface defining the component you wish to be injected or of type `java.util.List` or `java.util.Map`.
 
-  Fields of type <<<java.lang.List>>> will have a list of components injected
-whereas a field of type <<<java.lang.Map>>> will have a mapping in the form of
-<<<role-hint -> component>>>. The <<<role>>> parameter is required if using a
-<<<List>>> or <<<Map>>> whereas a role-hint is not allowed.
-
-*-----+------+------+
-|<<Parameter>>|<<Required>>|<<Description>>|
-*-----*------*------*
-| role | No. Yes if the field is a <<<List>>> or a <<<Map>>> | The role parameter is used to tell plexus what Component role you are interested in. For singleton fields their type is used as a default.
-*-----*------*------*
-| role-hint | No. Not allowed if the field is a <<<List>>> or a <<<Map>>> | Links to the role-hint defined by a component when looking up a component. Not allowed with <<<List>>> or <<<Map>>> fields, as they return all <<<role-hint>>>s.
-*-----*------*------*
+Fields of type `java.lang.List` will have a list of components injected whereas a field of type `java.lang.Map` will have a mapping in the form of `role-hint -> component`. The `role` parameter is required if using a `List` or `Map` whereas a role-hint is not allowed.
 
+|**Parameter**|**Required**|**Description**|
+|---|---|---|
+|role|No. Yes if the field is a `List` or a `Map`|The role parameter is used to tell plexus what Component role you are interested in. For singleton fields their type is used as a default.|
+|role-hint|No. Not allowed if the field is a `List` or a `Map`|Links to the role-hint defined by a component when looking up a component. Not allowed with `List` or `Map` fields, as they return all `role-hint`s.|
diff --git a/src/site/markdown/guides/developer-guide/appendices/plexus-maven-plugin-reference.md b/src/site/markdown/guides/developer-guide/appendices/plexus-maven-plugin-reference.md
index 00d0663..13231f3 100644
--- a/src/site/markdown/guides/developer-guide/appendices/plexus-maven-plugin-reference.md
+++ b/src/site/markdown/guides/developer-guide/appendices/plexus-maven-plugin-reference.md
@@ -1,13 +1,11 @@
- ------
- Developer Guide - Appendix II: Plexus Maven Plugin
- ------
- Rahul Thakur
-------
-2006-07-09
- ------
+---
+title: Developer Guide - Appendix II: Plexus Maven Plugin
+author: Rahul Thakur
+date: 2006-07-09
+---
 
- <<<The contents of this document are a work in progress>>>
+`The contents of this document are a work in progress`
 
-Plexus Maven Plugin 
+# Plexus Maven Plugin
 
-  ~~TODO: Discuss the use with some example of Mojos available under Plexus Maven plugin
+<!-- TODO: Discuss the use with some example of Mojos available under Plexus Maven plugin -->
diff --git a/src/site/markdown/guides/developer-guide/building-applications/cdc.md b/src/site/markdown/guides/developer-guide/building-applications/cdc.md
index 6c44cb2..d80d8f1 100644
--- a/src/site/markdown/guides/developer-guide/building-applications/cdc.md
+++ b/src/site/markdown/guides/developer-guide/building-applications/cdc.md
@@ -1,47 +1,36 @@
- ------
- Developer Guide - The Component Descriptor Creator
- ------
- Trygve Laugst\xF8l
- Emmanuel Venisse
- ------
-2006-07-09
- ------
-
- <<<The contents of this document are a work in progress>>>
-
-Plexus Component Descriptor Creator
-
- <<NOTE: This document and the CDC itself is currently a work in progress.>>
-
- The Component Descriptor Creator (or CDC for short) is a tool that will create
- the <<<components.xml>>> file from your Java code. It uses JavaDoc tags to
- gather the information it needs to create the component descriptor.
-
- There is a tag for marking components, requirements and configuration. Each of
- the tags can have parameters as documented below.
-
-* Component Tag Parameters
-
-*------------------------*--------------*---------------------------------------------*
-| <<Tag>>                | <<Required>> | <<Description>>                             |
-*------------------------*---*--------------------------------------------------------*
-| role                   | y | The role of the component.                             |
-*------------------------*---*--------------------------------------------------------*
-| role-hint              | n | The role-hint of the component.                        |
-*------------------------*---*--------------------------------------------------------*
-| version                | n | The component version.                                 |
-*------------------------*---*--------------------------------------------------------*
-| lifecycle-handler      | n | The lifecycle handler of the component.                |
-|                        |   | <TODO: link to the different lifecycle handlers>       |
-*------------------------*---*--------------------------------------------------------*
-| instantiation-strategy | n | The instantiation strategy of the component.           |
-|                        |   | <TODO: link to the different instantiation strategies> |
-*------------------------*---*--------------------------------------------------------*
-~~ TODO: This line will be incorrectly render the *name* of the table as well
-~~       as the caption
-~~ [plexus-component-tags] Plexus Component Tag Parameters
-
-+---+
+---
+title: Developer Guide - The Component Descriptor Creator
+author:
+  - Trygve Laugstøl
+  - Emmanuel Venisse
+date: 2006-07-09
+---
+
+`The contents of this document are a work in progress`
+
+# Plexus Component Descriptor Creator
+
+**NOTE: This document and the CDC itself is currently a work in progress.**
+
+The Component Descriptor Creator (or CDC for short) is a tool that will create the `components.xml` file from your Java code. It uses JavaDoc tags to gather the information it needs to create the component descriptor.
+
+There is a tag for marking components, requirements and configuration. Each of the tags can have parameters as documented below.
+
+## Component Tag Parameters
+
+|**Tag**|**Required**|**Description**|
+|---|---|---|
+|role|y|The role of the component.|
+|role-hint|n|The role-hint of the component.|
+|version|n|The component version.|
+|lifecycle-handler|n|The lifecycle handler of the component. _TODO: link to the different lifecycle handlers_|
+|instantiation-strategy|n|The instantiation strategy of the component. _TODO: link to the different instantiation strategies_|
+
+<!--  TODO: This line will be incorrectly render the *name* of the table as well -->
+<!--        as the caption -->
+<!--  [plexus-component-tags] Plexus Component Tag Parameters -->
+
+```
 package org.foo;
 
 /**
@@ -53,44 +42,40 @@ public class DefaultActionManager
     extends AbstractLogEnabled
     implements ActionManager, Serviceable
 {
-+---+
-~~ [example-class-tags] Example Component Tag
+```
 
- This will be generated in component.xml:
+<!--  [example-class-tags] Example Component Tag -->
+This will be generated in component.xml:
 
-+---+
+```
 <component>
   <role>org.foo.ActionManager</role>
   <implementation>org.foo.DefaultActionManager</implementation>
   <lifecycle-handler>plexus-configurable</lifecycle-handler>
 </component>
-+---+
+```
 
-* Requirement Tag Parameters
+## Requirement Tag Parameters
 
- These tags are used on fields to state requirements. TODO: it should be
- possible to override the role for a normal field.
+These tags are used on fields to state requirements. TODO: it should be possible to override the role for a normal field.
 
-*-----------------------*----------------*----------------------------------------------------------------------*
-| <<Tag>>               | <<Required>> | <<Description>>                                                        |
-*-----------------------*-----*---------------------------------------------------------------------------------*
-| role                  | y/n | The role of the component. Only required if the field is a List or Map          |
-*-----------------------*-----*---------------------------------------------------------------------------------*
-| role-hint             | n   | The role-hint of the component.                                                 |
-*-----------------------*-----*---------------------------------------------------------------------------------*
+|**Tag**|**Required**|**Description**|
+|---|---|---|
+|role|y/n|The role of the component. Only required if the field is a List or Map|
+|role-hint|n|The role-hint of the component.|
 
-+---+
+```
 /**
  * @plexus.requirement
  *  role-hint="foo"
  */
 private ActionManager actionManager;
-+---+
-~~ [example-requirement-tags] Example Requirement Tag
+```
 
- This will be generated in component.xml:
+<!--  [example-requirement-tags] Example Requirement Tag -->
+This will be generated in component.xml:
 
-+---+
+```
 <component>
   <role>org.foo.MyComponent</role>
   <implementation>org.foo.MyComponentImplementation</implementation>
@@ -102,31 +87,28 @@ private ActionManager actionManager;
     </requirement>
   </requirements>
 </component>
-+---+
+```
 
-* Configuration Tag Parameters
+## Configuration Tag Parameters
 
- Note that the default value tag won't be required in the future when these
- tags will be used to generate a separate configuration declaration section.
+Note that the default value tag won't be required in the future when these tags will be used to generate a separate configuration declaration section.
 
-*-----------------------*--------------*---------------------------------------------*
-| <<Tag>>               | <<Required>> | <<Description>>                             |
-*-----------------------*---*--------------------------------------------------------*
-| default-value         | y | Sets the default value for the configuration field     |
-*-----------------------*---*--------------------------------------------------------*
+|**Tag**|**Required**|**Description**|
+|---|---|---|
+|default-value|y|Sets the default value for the configuration field|
 
-+---+
+```
 /**
  * @plexus.configuration
  *  default-value="Trygve"
  */
 private String name;
-+---+
-~~ [example-requirement-tags] Example Configuration Tag
+```
 
- This will be generated in component.xml:
+<!--  [example-requirement-tags] Example Configuration Tag -->
+This will be generated in component.xml:
 
-+---+
+```
 <component>
   <role>org.foo.MyComponent</role>
   <implementation>org.foo.MyComponentImplementation</implementation>
@@ -134,4 +116,4 @@ private String name;
     <name>Trygve</name>
   </configuration>
 </component>
-+---+
+```
diff --git a/src/site/markdown/guides/developer-guide/building-applications/index.md b/src/site/markdown/guides/developer-guide/building-applications/index.md
index 115adb9..ca5e9bf 100644
--- a/src/site/markdown/guides/developer-guide/building-applications/index.md
+++ b/src/site/markdown/guides/developer-guide/building-applications/index.md
@@ -1,41 +1,38 @@
- ------
- Developer Guide - Building Plexus Applications
- ------
- Trygve Laugstol
- Emmanuel Venisse 
- ------
-2006-06-17
- ------
+---
+title: Developer Guide - Building Plexus Applications
+author:
+  - Trygve Laugstol
+  - Emmanuel Venisse
+date: 2006-06-17
+---
 
-Building Plexus Applications and Runtimes
+# Building Plexus Applications and Runtimes
 
- To be able to build Plexus applications and runtimes you'll need:
+To be able to build Plexus applications and runtimes you'll need:
 
- * The Plexus mojo
+- The Plexus mojo
 
- * The Plexus application archetype
+- The Plexus application archetype
 
- * The Plexus runtime archetype
+- The Plexus runtime archetype
 
- <<<TODO: Make a link to the maven site that explains what a archetype is.>>>
+`TODO: Make a link to the maven site that explains what a archetype is.`
 
-Introduction
+# Introduction
 
- Some stub directories will be created:
+Some stub directories will be created:
 
- [<<</my-component>>>] - Here we'll make a Plexus component
+[`/my-component`] - Here we'll make a Plexus component
 
- [<<</my-application>>>] - Here we'll make an application
+[`/my-application`] - Here we'll make an application
 
- [<<</my-runtime>>>] - Here we'll make a runtime that will host your
-  application.  This runtime will contain startup scripts for Unix, Windows and
-  OS X and will be completly standalone.
+[`/my-runtime`] - Here we'll make a runtime that will host your application. This runtime will contain startup scripts for Unix, Windows and OS X and will be completly standalone.
 
-Creating a Simple Plexus Component
+# Creating a Simple Plexus Component
 
-* Making the Component Stub
+## Making the Component Stub
 
-+-----------------------------------------------------------------------------+
+```
 $ mvn archetype:create \
      -DarchetypeGroupId=org.codehaus.plexus \
      -DarchetypeArtifactId=plexus-archetype-component-simple \
@@ -44,23 +41,23 @@ $ mvn archetype:create \
      -DartifactId=my-component \
      -Dversion=1.0-SNAPSHOT \
      -Dpackage=my.component
-+-----------------------------------------------------------------------------+
+```
 
-* Building the Plexus Component
+## Building the Plexus Component
 
- To build the component simply type in <<</my-component>>>:
+To build the component simply type in `/my-component`:
 
-+-----------------------------------------------------------------------------+
+```
 $ mvn install
-+-----------------------------------------------------------------------------+
+```
 
- You should now have a packaged Plexus component in <<<target/my-component-1.0-SNAPSHOT.jar>>>
+You should now have a packaged Plexus component in `target/my-component-1.0-SNAPSHOT.jar`
 
-Creating a Simple Plexus Application
+# Creating a Simple Plexus Application
 
-* Making the Application Stub
+## Making the Application Stub
 
-+-----------------------------------------------------------------------------+
+```
 $ mvn archetype:create \
      -DarchetypeGroupId=org.codehaus.plexus \
      -DarchetypeArtifactId=plexus-archetype-application \
@@ -69,71 +66,63 @@ $ mvn archetype:create \
      -DartifactId=my-application \
      -Dversion=1.0-SNAPSHOT \
      -Dpackage=my.app
-+-----------------------------------------------------------------------------+
+```
 
-* Adding the Plexus Component dependency
+## Adding the Plexus Component dependency
 
- You need to add the following dependency in <<</my-application>>> pom:
+You need to add the following dependency in `/my-application` pom:
 
-+-----------------------------------------------------------------------------+
+```
     <dependency>
       <groupId>mygroup</groupId>
       <artifactId>my-component</artifactId>
       <version>1.0-SNAPSHOT</version>
     </dependency>
-+-----------------------------------------------------------------------------+
+```
 
- and in <<<src/conf/application.xml>>>, add this so the Plexus component will be
- loaded at startup:
+and in `src/conf/application.xml`, add this so the Plexus component will be loaded at startup:
 
-+-----------------------------------------------------------------------------+
+```
   <load-on-start>
     <component>
       <role>mygroup.HelloWorld</role>
     </component>
   </load-on-start>
-+-----------------------------------------------------------------------------+
+```
 
-* Building the Plexus Application
+## Building the Plexus Application
 
- To build the application simply type in <<</my-application>>>:
+To build the application simply type in `/my-application`:
 
-+-----------------------------------------------------------------------------+
+```
 $ mvn plexus-appserver:assemble-app
-+-----------------------------------------------------------------------------+
+```
 
- and you should have a application in <<<target/plexus-application>>>. Inside
- the exploded application there will be two directories: <<<conf>>> and
- <<<lib>>>. The <<<conf>>> directory contains the configuration file for your
- application and <<<lib>>> contains all the dependencies the application has.
+and you should have a application in `target/plexus-application`. Inside the exploded application there will be two directories: `conf` and `lib`. The `conf` directory contains the configuration file for your application and `lib` contains all the dependencies the application has.
 
- If you want to do some extra processing on these files or possibly add your
- own files you can have a plugin with a post goal on <<<plexus:app>>> and it
- would be invoked before the application was packaged.
+If you want to do some extra processing on these files or possibly add your own files you can have a plugin with a post goal on `plexus:app` and it would be invoked before the application was packaged.
 
- If you now run the <<<plexus-appserver:package-app>>> goal:
+If you now run the `plexus-appserver:package-app` goal:
 
-+-----------------------------------------------------------------------------+
+```
 $ mvn plexus-appserver:package-app
-+-----------------------------------------------------------------------------+
+```
 
- the resulting JAR file will be ready for deployment in a Plexus runtime. Our
- example application JAR will be
- <<<target/my-application-1.0-SNAPSHOT.jar>>>.
+the resulting JAR file will be ready for deployment in a Plexus runtime. Our example application JAR will be `target/my-application-1.0-SNAPSHOT.jar`.
 
- you can run the above commands in one:
+you can run the above commands in one:
 
-+-----------------------------------------------------------------------------+
+```
 $ mvn install
-+-----------------------------------------------------------------------------+
+```
 
-Creating the Runtime
+# Creating the Runtime
 
-* Making the Runtime Stub
+## Making the Runtime Stub
 
- Creating the stub runtime is as easy as creating the application:
+Creating the stub runtime is as easy as creating the application:
 
-+-----------------------------------------------------------------------------+
+```
 $ mvn archetype:create \
      -DarchetypeGroupId=org.codehaus.plexus \
      -DarchetypeArtifactId=plexus-archetype-runtime \
@@ -142,109 +131,94 @@ $ mvn archetype:create \
      -DartifactId=my-runtime \
      -Dversion=1.0-SNAPSHOT \
      -Dpackage=my.runtime
-+-----------------------------------------------------------------------------+
+```
 
-* Building the Runtime
+## Building the Runtime
 
-+-----------------------------------------------------------------------------+
+```
 $ mvn package
-+-----------------------------------------------------------------------------+
+```
 
- You should now have a usable runtime in <<<target/plexus-runtime>>> and a
- packaged runtime in <<<target/my-runtime-1.0-SNAPSHOT.jar>>>. Now lets copy
- over the application:
+You should now have a usable runtime in `target/plexus-runtime` and a packaged runtime in `target/my-runtime-1.0-SNAPSHOT.jar`. Now lets copy over the application:
 
-+-----------------------------------------------------------------------------+
+```
 $ cp ../my-application/target/my-application-1.0-SNAPSHOT.jar \
      target/plexus-app-runtime/apps
-+-----------------------------------------------------------------------------+
+```
 
- You can also add a dependency on my-application in the my-runtime pom, so it won't
- be necessary to copy the application manually in the runtime.
+You can also add a dependency on my-application in the my-runtime pom, so it won't be necessary to copy the application manually in the runtime.
 
-+-----------------------------------------------------------------------------+
+```
     <dependency>
       <groupId>mygroup</groupId>
       <artifactId>my-application</artifactId>
       <version>1.0-SNAPSHOT</version>
       <type>plexus-application</type>
     </dependency>
-+-----------------------------------------------------------------------------+
+```
 
- Now you have a working Plexus runtime with your application installed. To
- start it run:
+Now you have a working Plexus runtime with your application installed. To start it run:
 
-+-----------------------------------------------------------------------------+
+```
 $ sh target/plexus-app-runtime/bin/plexus.sh
-+-----------------------------------------------------------------------------+
+```
 
- Hopefully you should now have a runtime running with. The message "Starting Hello Component."
- sended by <<<my-component>>> at startup must appears in logs.
+Hopefully you should now have a runtime running with. The message "Starting Hello Component." sended by `my-component` at startup must appears in logs.
 
-Getting fancy: Adding a Shared Servlet Container
+# Getting fancy: Adding a Shared Servlet Container
 
- Plexus runtimes can have a set of services thats shared between the applications.
- One very useful service is a servlet container. This enables several isolated applications
- to share the same Jetty instance without the need for complicated Apache HTTPD proxy
- setups. The servlet container service will all the web in a configured
- directory. The application contains a commented out configuration section for
- the servlet container which you must uncomment so the service would be
- enabled.
+Plexus runtimes can have a set of services thats shared between the applications. One very useful service is a servlet container. This enables several isolated applications to share the same Jetty instance without the need for complicated Apache HTTPD proxy setups. The servlet container service will all the web in a configured directory. The application contains a commented out configuration section for the servlet container which you must uncomment so the service would be enabled.
 
- <<<NOTE: This example assumes that you have the runtime that was created in the last section.>>>
+`NOTE: This example assumes that you have the runtime that was created in the last section.`
 
- First add the service dependency into the runtime:
+First add the service dependency into the runtime:
 
-+-----------------------------------------------------------------------------+
+```
     <dependency>
       <groupId>org.codehaus.plexus</groupId>
       <artifactId>plexus-appserver-service-jetty</artifactId>
       <version>2.0-alpha-1</version>
       <type>plexus-service</type>
     </dependency>
-+-----------------------------------------------------------------------------+
+```
 
- Now we need to add a web application to the application.  As a simple web
- application we're using the Jetty JavaDocs. Add this in <<<my-application>>> pom:
+Now we need to add a web application to the application. As a simple web application we're using the Jetty JavaDocs. Add this in `my-application` pom:
 
-+-----------------------------------------------------------------------------+
+```
     <dependency>
       <groupId>jetty</groupId>
       <artifactId>javadoc</artifactId>
       <version>4.2.23RC0</version>
       <type>war</type>
     </dependency>
-+-----------------------------------------------------------------------------+
+```
 
- Now we need to configure the servlet container service so it knows where to
- find the web applications. In <<<src/conf/application.xml>>> uncomment the servlet
- container section. Now bundle the application again:
+Now we need to configure the servlet container service so it knows where to find the web applications. In `src/conf/application.xml` uncomment the servlet container section. Now bundle the application again:
 
-+-----------------------------------------------------------------------------+
+```
 $ mvn install
-+-----------------------------------------------------------------------------+
+```
 
- We suppose there you added <<<my-application>>> dependency in <<<my-runtime>>> pom.
- Execute this commands from <<</my-runtime>>>
+We suppose there you added `my-application` dependency in `my-runtime` pom. Execute this commands from `/my-runtime`
 
-+-----------------------------------------------------------------------------+
+```
 $ mvn package
-+-----------------------------------------------------------------------------+
+```
 
- Now when the application server is started again it should
+Now when the application server is started again it should
 
- * Deploy the servlet container.
+- Deploy the servlet container.
 
- * Boot Jetty.
+- Boot Jetty.
 
- * Deploy the application.
+- Deploy the application.
 
- * The servlet container will detect that a new application was deployed and deploy the JavaDoc WAR.
+- The servlet container will detect that a new application was deployed and deploy the JavaDoc WAR.
 
- So lets start it:
+So lets start it:
 
-+-----------------------------------------------------------------------------+
+```
 $ sh target/plexus-app-runtime/bin/plexus.sh
-+-----------------------------------------------------------------------------+
+```
 
- And open your browser to http://localhost:8080/
+And open your browser to http://localhost:8080/
diff --git a/src/site/markdown/guides/developer-guide/building-applications/runtime-builder.md b/src/site/markdown/guides/developer-guide/building-applications/runtime-builder.md
index 3e99831..1daff10 100644
--- a/src/site/markdown/guides/developer-guide/building-applications/runtime-builder.md
+++ b/src/site/markdown/guides/developer-guide/building-applications/runtime-builder.md
@@ -1,15 +1,13 @@
- ------
- Developer Guide - Plexus Runtime builder
- ------
- Rahul Thakur
- ------
-2006-06-17
- ------
+---
+title: Developer Guide - Plexus Runtime builder
+author: Rahul Thakur
+date: 2006-06-17
+---
 
- <<<The contents of this document are a work in progress>>>
+`The contents of this document are a work in progress`
 
-Plexus Runtime Builder
+# Plexus Runtime Builder
 
-  Plexus runtime acts as a scaffolding that allows running Plexus applications. For instance Continuum. 
+Plexus runtime acts as a scaffolding that allows running Plexus applications. For instance Continuum.
 
-  ~~TODO Expand on this
+<!-- TODO Expand on this -->
diff --git a/src/site/markdown/guides/developer-guide/building-components/component-identity.md b/src/site/markdown/guides/developer-guide/building-components/component-identity.md
index f701aa8..df2ac9e 100644
--- a/src/site/markdown/guides/developer-guide/building-components/component-identity.md
+++ b/src/site/markdown/guides/developer-guide/building-components/component-identity.md
@@ -1,47 +1,27 @@
- ------
- Developer Guide - Component Identity
- ------
-Michal Maczka
- Rahul Thakur
- ------
-2006-06-17
- ------
- 
- 
- 
-Component Identity
- 
- In order to perform a "lookup" operation and connect components together we 
- need to have a means of selecting them in an unambiguous way. This means each
- deployed instance of the component object must be distinguishable from any 
- other component, that is visible within the container. So each installed 
- component object must have some sort of unique identifier attached to it, the 
- 'component identifier'.
-
-
- There are at least two situations when a component identifier is need:
-
-  * component assembler (human) must use it to connect components together
-    (a "wiring process")
-
-  * for dynamic component lookup operations while the application is running.
- 
-
-
- In Plexus, component identity is defined by the component descriptors and
- is the same for both situations mentioned above.
-
- At the moment the two attributes of the component descriptor are: <role> and
- <role-hint>.
-
-
- <role> attribute is mandatory - every component descriptor must have it,
- <role-hint> is used as differentiator between components in situations when 
- more then one component is able to play a given role in component assembly.
- 
- The component key is plexus = ( <role>, <role-hint> ), if <role-hint> is not
- given it is ( <role>, null )
- 
- In the future this may be extended. For example a <version> attribute of the
- component descriptor would be used or there may be the possibility of
- defining aliases for components.
+---
+title: Developer Guide - Component Identity
+author:
+  - Michal Maczka
+  - Rahul Thakur
+date: 2006-06-17
+---
+
+# Component Identity
+
+In order to perform a "lookup" operation and connect components together we need to have a means of selecting them in an unambiguous way. This means each deployed instance of the component object must be distinguishable from any other component, that is visible within the container. So each installed component object must have some sort of unique identifier attached to it, the 'component identifier'.
+
+There are at least two situations when a component identifier is need:
+
+- component assembler (human) must use it to connect components together (a "wiring process")
+
+- for dynamic component lookup operations while the application is running.
+
+In Plexus, component identity is defined by the component descriptors and is the same for both situations mentioned above.
+
+At the moment the two attributes of the component descriptor are: _role_ and _role-hint_.
+
+_role_ attribute is mandatory - every component descriptor must have it, _role-hint_ is used as differentiator between components in situations when more then one component is able to play a given role in component assembly.
+
+The component key is plexus \= ( _role_, _role-hint_ ), if _role-hint_ is not given it is ( _role_, null )
+
+In the future this may be extended. For example a _version_ attribute of the component descriptor would be used or there may be the possibility of defining aliases for components.
diff --git a/src/site/markdown/guides/developer-guide/building-components/component-testing.md b/src/site/markdown/guides/developer-guide/building-components/component-testing.md
index 40667b5..a2ab2a0 100644
--- a/src/site/markdown/guides/developer-guide/building-components/component-testing.md
+++ b/src/site/markdown/guides/developer-guide/building-components/component-testing.md
@@ -1,58 +1,30 @@
- ------
- Developer Guide - Testing Plexus Components
- ------
- Michal Maczka
- ------
-2006-06-17
- ------
-
- <<<The contents of this document are a work in progress>>>
-
-Testing Plexus Components
-
- If you are using Plexus you are going to use and most likely write your own
- components.  In the second case you will need to be able to test them. Plexus
- container uses quite a rare approach for testing components: components are
- tested inside the container.
-
- Like a fish needs water, a component by its [definition] needs a container.
- Fish should be only lifted from the water - its natural environment - for a
- short time, as fish needs water to breathe and water supports the weight of
- the fish.  Keep the fish in water; keep the component in its natural
- environment - the container.  As there are fishes, which are hard to catch,
- there are components, which are hard to test outside the container. And as
- there are some fishes, which can be never caught, there are some components,
- which practically cannot be tested outside the container.
-
- Important remark: *component testing* is not exactly the same thing as *class
- testing*.  In case of Plexus a component in the simplest possible case is a
- java class plus the component descriptor.  Traditional unit testing allows you
- to test java classes, but you should be able to test if component as a whole
- is error free and ready to be used.  It means that component's metadata must
- also be validated - you want to be sure that component definition was written
- properly, component's requirements were stated properly, correct component
- profile was chosen etc.
-
- Another thing, which is so appealing about this approach is the fact that
- testing environment and production environment are exactly the same - this
- eliminates some surprises which otherwise would appear only when component was
- deployed.
-
- Last but not least  -although it might be counter-intuitive such approach is
- really making testing easier!  Plexus and other lightweight containers have
- proven to *be a perfect mock infrastructure*: the container is used for
- "plumbing" components with its depended components. That is why a container is
- a perfect tool for injecting Mock implementation during test time and real
- implementation at the runtime.
-
- Note that Plexus is quite "lightweight" and it usually can be embedded a
- couple of times per second.
-
-* Example
-
- Component Interface
-
-+---+
+---
+title: Developer Guide - Testing Plexus Components
+author: Michal Maczka
+date: 2006-06-17
+---
+
+`The contents of this document are a work in progress`
+
+# Testing Plexus Components
+
+If you are using Plexus you are going to use and most likely write your own components. In the second case you will need to be able to test them. Plexus container uses quite a rare approach for testing components: components are tested inside the container.
+
+Like a fish needs water, a component by its \[definition\] needs a container. Fish should be only lifted from the water - its natural environment - for a short time, as fish needs water to breathe and water supports the weight of the fish. Keep the fish in water; keep the component in its natural environment - the container. As there are fishes, which are hard to catch, there are components, which are hard to test outside the container. And as there are some fishes, which can be never caught, there are some components, which practically cannot be tested outside the container.
+
+Important remark: \*component testing\* is not exactly the same thing as \*class testing\*. In case of Plexus a component in the simplest possible case is a java class plus the component descriptor. Traditional unit testing allows you to test java classes, but you should be able to test if component as a whole is error free and ready to be used. It means that component's metadata must also be validated - you want to be sure that component definition was written properly, component's requirements were stated properly, correct component profile was chosen etc.
+
+Another thing, which is so appealing about this approach is the fact that testing environment and production environment are exactly the same - this eliminates some surprises which otherwise would appear only when component was deployed.
+
+Last but not least -although it might be counter-intuitive such approach is really making testing easier! Plexus and other lightweight containers have proven to \*be a perfect mock infrastructure\*: the container is used for "plumbing" components with its depended components. That is why a container is a perfect tool for injecting Mock implementation during test time and real implementation at the runtime.
+
+Note that Plexus is quite "lightweight" and it usually can be embedded a couple of times per second.
+
+## Example
+
+Component Interface
+
+```
 package org.codehaus.plexus.tutorial.lesson2;
 
 public interface HelloWorld
@@ -61,11 +33,11 @@ public interface HelloWorld
 
     String getGreeting();
 }
-+---+
+```
 
- Component Implementation:
+Component Implementation:
 
-+---+
+```
 package org.codehaus.plexus.tutorial.lesson2;
 
 public class DefaultHelloWorld  implements HelloWorld
@@ -75,11 +47,11 @@ public class DefaultHelloWorld  implements HelloWorld
         return "Hello World!";
     }
 }
-+---+
+```
 
- Component Test Case:
+Component Test Case:
 
-+---+
+```
 package org.codehaus.plexus.tutorial.lesson2;
 
 import org.codehaus.plexus.PlexusTestCase;
@@ -95,20 +67,15 @@ public class DefaultHelloWorldTest
         assertEquals( "Hello World!", helloWorld.getGreeting() );
     }
 }
-+---+
+```
 
- Normal [component discovery] is performed during the initialization of the
- test case.  It means that if your component descriptor was alraedy added to
- /META-INF/plexus/components.xml file it will be visible during tests.
+Normal \[component discovery\] is performed during the initialization of the test case. It means that if your component descriptor was alraedy added to /META-INF/plexus/components.xml file it will be visible during tests.
 
- In case when you want to override the deafults the only thing you have to do
- is to create new xml file having the name which matches the class name but
- with extentinon ".xml". This file must be placed in the same package as the
- class and be visible in the unit test's classpath.
+In case when you want to override the deafults the only thing you have to do is to create new xml file having the name which matches the class name but with extentinon ".xml". This file must be placed in the same package as the class and be visible in the unit test's classpath.
 
- In case of DefaultHelloWorldTest the file should be names DefaultHelloWorldTest.xml
+In case of DefaultHelloWorldTest the file should be names DefaultHelloWorldTest.xml
 
-+---+
+```
 <plexus>
   <components>
     <component>
@@ -117,48 +84,42 @@ public class DefaultHelloWorldTest
     </component>
   </components>
 </plexus>
-+---+
-
-* Container Driven Testing
+```
 
- Now we will show an example how container can help in component testing and
- how it can be used for providing "mock components" during tests.
+## Container Driven Testing
 
- As exmplained above plexus provides a possiblity of perform lightning-fast
- component tests. which directly which takes place inside container.  As Plexus
- suports IoC paradigm and it's Dependecy Injection in particular the container
- is a perfect envinroment for providing mock implementation of component's
- requirements.
+Now we will show an example how container can help in component testing and how it can be used for providing "mock components" during tests.
 
-~~!component-tesing-1.gif!
+As exmplained above plexus provides a possiblity of perform lightning-fast component tests. which directly which takes place inside container. As Plexus suports IoC paradigm and it's Dependecy Injection in particular the container is a perfect envinroment for providing mock implementation of component's requirements.
 
-** Implementation:
+<!-- !component-tesing-1.gif! -->
+### Implementation:
 
-+---+
+```
 src\main\java\org\codehaus\plexus\example\CheeseConnoisseur.java
                                                                  \Cheese.java
                                                                  \DefaultCheeseFinder.java
                                                                  \CheeseFinder.java
                                                                  \CheeseEater.java
 src\main\resources\META-INF\plexus\components.xml
-+---+
+```
 
-** Tests:
+### Tests:
 
-+---+
+```
 $root\src\main\test\org\codehaus\plexus\example\
                                                                    MockCheeseFinder.java
                                                                    CheeseConnoisseurTest.java
                                                                    CheeseConnoisseurTest.xml
-+---+
+```
 
- Now file by file we will explain what is inside of each of files:
+Now file by file we will explain what is inside of each of files:
 
-+---+
+```
 $root\src\main\java\org\codehaus\plexus\example\Cheese.java
-+---+
+```
 
-+---+
+```
 package org.codehaus.plexus.example;
 
 public class Cheese
@@ -194,16 +155,15 @@ public class Cheese
         this.price = price;
     }
 }
-+---+
+```
 
-+---+
+```
 $root\src\main\java\org\codehaus\plexus\example\CheeseEater.java
-+---+
+```
 
-+---+
+```
 package org.codehaus.plexus.example;
 
-
 public interface CheeseEater
 {
     String ROLE = CheeseEater.class.getName();
@@ -211,13 +171,13 @@ public interface CheeseEater
     Cheese chooseCheese();
 
 }
-+---+
+```
 
-+---+
+```
 $root\src\main\java\org\codehaus\plexus\example\CheeseFinder.java
-+---+
+```
 
-+---+
+```
 package org.codehaus.plexus.example;
 
 import java.util.List;
@@ -228,13 +188,13 @@ public interface CheeseFinder
 
     List getAllCheeses();
 }
-+---+
+```
 
-+---+
+```
 $root\src\main\java\org\codehaus\plexus\example\DefaultCheeseFinder.java
-+---+
+```
 
-+---+
+```
 package org.codehaus.plexus.example;
 
 import java.util.List;
@@ -252,19 +212,18 @@ public class DefaultCheeseFinder implements CheeseFinder
 
     }
 }
-+---+
+```
 
-+---+
+```
 $root\src\main\java\org\codehaus\plexus\example\CheeseConnoisseur.java
-+---+
+```
 
-+---+
+```
 package org.codehaus.plexus.example;
 
 import java.util.Iterator;
 import java.util.List;
 
-
 public class CheeseConnoisseur  implements CheeseEater
 {
     /**
@@ -297,14 +256,13 @@ public class CheeseConnoisseur  implements CheeseEater
         return retValue;
     }
 }
-+---+
+```
 
-
-+---+
+```
 $root\src\main\resources\META-INF\plexus\components.xml
-+---+
+```
 
-+---+
+```
 <component-set>
     <components>
         <component>
@@ -318,15 +276,15 @@ $root\src\main\resources\META-INF\plexus\components.xml
         </component>
     </components>
 </component-set>
-+---+
+```
 
-** Test Code:
+### Test Code:
 
-+---+
+```
 $root\src\test\java\org\codehaus\plexus\example\CheeseConnoisseurTest.java
-+---+
+```
 
-+---+
+```
 package org.codehaus.plexus.example;
 
 import org.codehaus.plexus.PlexusTestCase;
@@ -336,7 +294,6 @@ public class CheeseConnoisseurTest extends PlexusTestCase
 
     private CheeseEater connoisseur;
 
-
     protected void setUp() throws Exception
     {
         super.setUp();
@@ -351,13 +308,13 @@ public class CheeseConnoisseurTest extends PlexusTestCase
        assertEquals( "Gruyere", cheese.getName() );
     }
 }
-+---+
+```
 
-+---+
+```
 $root\src\test\java\org\codehaus\plexus\example\MockCheeseFinder.java
-+---+
+```
 
-+---+
+```
 package org.codehaus.plexus.example;
 
 import java.util.List;
@@ -386,13 +343,13 @@ public class MockCheeseFinder implements CheeseFinder
 
     }
 }
-+---+
+```
 
-+---+
+```
 $root\src\test\java\org\codehaus\plexus\example\CheeseConnoisseurTest.xml
-+---+
+```
 
-+---+
+```
 <plexus>
     <components>
         <!-- We will use mock component for testing-->
@@ -402,4 +359,4 @@ $root\src\test\java\org\codehaus\plexus\example\CheeseConnoisseurTest.xml
         </component>
     </components>
 </plexus>
-+---+
+```
diff --git a/src/site/markdown/guides/developer-guide/building-components/index.md b/src/site/markdown/guides/developer-guide/building-components/index.md
index 4f648df..a55f464 100644
--- a/src/site/markdown/guides/developer-guide/building-components/index.md
+++ b/src/site/markdown/guides/developer-guide/building-components/index.md
@@ -1,10 +1,7 @@
- ------
- Developer Guide - Building Components
- ------
- Rahul Thakur
- ------
-2006-06-17
- ------
-
-Building Components
+---
+title: Developer Guide - Building Components
+author: Rahul Thakur
+date: 2006-06-17
+---
 
+# Building Components
diff --git a/src/site/markdown/guides/developer-guide/building-components/instantiation-strategies.md b/src/site/markdown/guides/developer-guide/building-components/instantiation-strategies.md
index 464f74e..64f3d6e 100644
--- a/src/site/markdown/guides/developer-guide/building-components/instantiation-strategies.md
+++ b/src/site/markdown/guides/developer-guide/building-components/instantiation-strategies.md
@@ -1,12 +1,9 @@
- ------
- Developer Guide - Component Instantiation Strategies
- ------
- Rahul Thakur
- ------
-2006-06-17
- ------
+---
+title: Developer Guide - Component Instantiation Strategies
+author: Rahul Thakur
+date: 2006-06-17
+---
 
-Component Instantiation Strategies
- 
- ~~TODO  Add notes on how different Component instantiation strategies work.
+# Component Instantiation Strategies
 
+<!-- TODO  Add notes on how different Component instantiation strategies work. -->
diff --git a/src/site/markdown/guides/developer-guide/building-pars.md b/src/site/markdown/guides/developer-guide/building-pars.md
index 4e610af..4fe7fff 100644
--- a/src/site/markdown/guides/developer-guide/building-pars.md
+++ b/src/site/markdown/guides/developer-guide/building-pars.md
@@ -1,9 +1,7 @@
- ------
- Developer Guide - Building Plexus Application Archicves
- ------
- Rahul Thakur
- ------
-2006-06-17
- ------
+---
+title: Developer Guide - Building Plexus Application Archicves
+author: Rahul Thakur
+date: 2006-06-17
+---
 
-Building PARs - Plexus Application Archives
+# Building PARs - Plexus Application Archives
diff --git a/src/site/markdown/guides/developer-guide/configuration/component-descriptor.md b/src/site/markdown/guides/developer-guide/configuration/component-descriptor.md
index 046b03b..c608c40 100644
--- a/src/site/markdown/guides/developer-guide/configuration/component-descriptor.md
+++ b/src/site/markdown/guides/developer-guide/configuration/component-descriptor.md
@@ -1,28 +1,20 @@
- ------
- Developer Guide - Plexus Component Descriptor
- ------
- Rahul Thakur
- ------
-2006-06-17
- ------
+---
+title: Developer Guide - Plexus Component Descriptor
+author: Rahul Thakur
+date: 2006-06-17
+---
 
- <<<The contents of this document are a work in progress>>>
+`The contents of this document are a work in progress`
 
-Plexus Component Descriptor
+# Plexus Component Descriptor
 
- We are discussing the component descriptors for components which are
- compatible  with {{{../personalities/plexus-personality.html}Plexus Personality}}. We show a
- limited picture of what can be done with components and component descriptors
- in Plexus.
+We are discussing the component descriptors for components which are compatible with [Plexus Personality](../personalities/plexus-personality.html). We show a limited picture of what can be done with components and component descriptors in Plexus.
 
- Nevertheless what you learn here should be sufficient to write even a large
- Plexus application!
+Nevertheless what you learn here should be sufficient to write even a large Plexus application!
 
- A component descriptor describes the properties of a component required by the
- container in order to manage the lifecycle of that component. Let's take a
- look at the simplest example of a component descriptor:
+A component descriptor describes the properties of a component required by the container in order to manage the lifecycle of that component. Let's take a look at the simplest example of a component descriptor:
 
-+------------------------------------------+
+```
 <component-sets>
   <components>
     <component>
@@ -31,21 +23,13 @@ Plexus Component Descriptor
     </component>
   </components>
 </component-sets>
-+------------------------------------------+
+```
 
- It starts off with a <<<component>>> tag, then values for the <<<role>>> and
- <<<implementation>>> tags are defined.  The <<<role>>> tag defines the
- interface provided by this component. It is usually the name of the Java
- interface.  Names of the classes (including abstract) are also allowed. You are
- not allowed to use arbitrary strings.  The <<<implementation>>> tag tells
- Plexus what you want to use to implement the specified <<<role>>>. In a normal case
- you will have to specify the name of the java class (<<<foo.DefaultFoo>>> in
- the example above), which implements the given interface (role).
+It starts off with a `component` tag, then values for the `role` and `implementation` tags are defined. The `role` tag defines the interface provided by this component. It is usually the name of the Java interface. Names of the classes (including abstract) are also allowed. You are not allowed to use arbitrary strings. The `implementation` tag tells Plexus what you want to use to implement the specified `role`. In a normal case you will have to specify the name of the java class (`foo.DefaultFoo` in the example above), which implements the given interface (role).
 
- If there is more than one component which provides an implementation of a given role
- you can differentiate them with the help of the <<<role-hint>>> attribute:
+If there is more than one component which provides an implementation of a given role you can differentiate them with the help of the `role-hint` attribute:
 
-+------------------------------------------+
+```
 ...
 <component>
   <role>foo.SomeComponent</role>
@@ -59,17 +43,11 @@ Plexus Component Descriptor
   <implementation>foo.FooB</implementation>
 <component>
 ...
-+------------------------------------------+
+```
 
- The <<<role>>> and the <<<role-hint>>> are what defines 
- {{{../building-components/component-identity.html}component identity}} and what you use to look up your
- component from Plexus.  The <<<role-hint>>> tag is optional.  It serves
- as an extra id qualifier that allows you to differentiate components of the same type
- (role).  You can use any arbitrary string you like as the value of the <<<role-hint>>>
- attribute. Note that you can deploy the same implementation of the component
- two or more times with different <<<role-hint>>>s e.g.:
+The `role` and the `role-hint` are what defines [component identity](../building-components/component-identity.html) and what you use to look up your component from Plexus. The `role-hint` tag is optional. It serves as an extra id qualifier that allows you to differentiate components of the same type (role). You can use any arbitrary string you like as the value of the `role-hint` attribute. Note that you can deploy the same implementation of the component two or more times with different `role-hint`s e.g.:
 
-+------------------------------------------+
+```
 ...
 <component>
   <role>foo.SomeComponent</role>
@@ -83,25 +61,17 @@ Plexus Component Descriptor
   <implementation>foo.FooA</implementation>
 <component>
 ...
-+------------------------------------------+
+```
 
-* Requirements
+## Requirements
 
- Components aren't very useful as isolated entities nor are they always ready
- to use standalone.  They become useful when we connect them together with
- other components and provide configuration settings to them.  There are
- several different ways to compose your system from components.
+Components aren't very useful as isolated entities nor are they always ready to use standalone. They become useful when we connect them together with other components and provide configuration settings to them. There are several different ways to compose your system from components.
 
- The default, and the simplest of them, is a part of
-  {{{../personalities/plexus-personality.html}Plexus Personality}} This uses a strategy called
- 'field injection' for wiring components. This means that Plexus takes selected
- objects and assigns them to fields of component objects.
+The default, and the simplest of them, is a part of [Plexus Personality](../personalities/plexus-personality.html) This uses a strategy called 'field injection' for wiring components. This means that Plexus takes selected objects and assigns them to fields of component objects.
 
- How does Plexus know into which fields requirements should be injected and
- what those requirements are?  There is a <<<requirements>>> section in the
- component descriptor where you declare what components you depend on:
+How does Plexus know into which fields requirements should be injected and what those requirements are? There is a `requirements` section in the component descriptor where you declare what components you depend on:
 
-+------------------------------------------+
+```
 ...
 <component>
   ...
@@ -115,38 +85,34 @@ Plexus Component Descriptor
   </requirements>
 </component>
 ...
-+------------------------------------------+
+```
 
- In a simple case the declaration of a dependency looks like this:
+In a simple case the declaration of a dependency looks like this:
 
-+------------------------------------------+
+```
   ...
   <requirement>
     <role>org.codehaus.plexus.ComponentA</role>
   </requirement>
   ...
-+------------------------------------------+
+```
 
- In the case when you want to declare a dependecy on a component which has
- specified both <<<role>>> and <<<role-hint>>> attributes you use:
+In the case when you want to declare a dependecy on a component which has specified both `role` and `role-hint` attributes you use:
 
-+------------------------------------------+
+```
   ...
   <requirement>
     <role>org.codehaus.plexus.ComponentB</role>
     <role-hint>foo</role-hint>
   </requirement>
   ...
-+------------------------------------------+
+```
 
- In any case Component Composer will try to find a matching field and property
- for the given requirements.  In the standard case the component composer will try
- to find a field in the component class (this is usually a private field),
- which has a type which matches the requirement's <<<role>>>.
+In any case Component Composer will try to find a matching field and property for the given requirements. In the standard case the component composer will try to find a field in the component class (this is usually a private field), which has a type which matches the requirement's `role`.
 
- For example in the case of this Java class:
+For example in the case of this Java class:
 
-+------------------------------------------+
+```
 package foo;
 public class SomeComponentImpl
 {
@@ -156,12 +122,11 @@ public class SomeComponentImpl
      // this is ordinary field
      int  b;
 }
-+------------------------------------------+
+```
 
-  You will need to prepare the following component descriptor which lists
-  ComponentA as a requirement:
+You will need to prepare the following component descriptor which lists ComponentA as a requirement:
 
-+------------------------------------------+
+```
 ...
 <component>
   <role>foo.SomeComponent</role>
@@ -173,28 +138,25 @@ public class SomeComponentImpl
   </requirements>
 <component>
 ...
-+------------------------------------------+
+```
 
-** Collections
+### Collections
 
- Plexus can also inject Maps, List or arrays of dependent components.  In the
- case of arrays of components the same approach is applied as in the case of
- "singular" dependencies. The only difference is that all visible
- implementations of a given role will be used.
+Plexus can also inject Maps, List or arrays of dependent components. In the case of arrays of components the same approach is applied as in the case of "singular" dependencies. The only difference is that all visible implementations of a given role will be used.
 
- Java:
+Java:
 
-+------------------------------------------+
+```
 package foo;
 public class SomeComponentImpl
 {
      org.codehaus.plexus.ComponentA  a[];
 }
-+------------------------------------------+
+```
 
- XML Descriptor:
+XML Descriptor:
 
-+------------------------------------------+
+```
 ...
 <component>
   <role>foo.SomeComponent</role>
@@ -219,14 +181,13 @@ public class SomeComponentImpl
   ...
 </component>
 ...
-+------------------------------------------+
+```
 
- In case of a <<<List>>>, or a <<<Map>>> you must explicitly define where dependencies should be
- injected. You can do this with the help of the <<<field-name>>> tag:
+In case of a `List`, or a `Map` you must explicitly define where dependencies should be injected. You can do this with the help of the `field-name` tag:
 
- XML Descriptor:
+XML Descriptor:
 
-+------------------------------------------+
+```
 ...
 <component>
   ...
@@ -244,28 +205,26 @@ public class SomeComponentImpl
   </requirements>
 </component>
 ...
-+------------------------------------------+
+```
 
- Java:
+Java:
 
-+------------------------------------------+
+```
 package foo;
 public class SomeComponentImpl
 {
        private Map mapA;
        private List listB;
 }
-+------------------------------------------+
+```
 
- <<Note>> that when using a Map the value of a component's <<<role-hint>>> is used as
- the key and the component instance is used as the value.
+**Note** that when using a Map the value of a component's `role-hint` is used as the key and the component instance is used as the value.
 
+You can also use the `field` tag for a "singular" component's requirements.
 
- You can also use the <<<field>>> tag for a "singular" component's requirements.
+XML Descriptor:
 
- XML Descriptor:
-
-+------------------------------------------+
+```
 ...
 <component>
   ...
@@ -283,11 +242,11 @@ public class SomeComponentImpl
   </requirements>
 <component>
 ...
-+------------------------------------------+
+```
 
-  Java:
+Java:
 
-+------------------------------------------+
+```
 package foo;
 public class SomeComponentImpl
 {
@@ -297,18 +256,15 @@ public class SomeComponentImpl
     //(component with role-hint = "bar" will be injected here)
     org.codehaus.plexus.ComponentB  b2;
 }
-+------------------------------------------+
+```
+
+Explicit specification into which field dependencies should be injected is considered to be a good pattern and might even be required in future versions of Plexus.
 
- Explicit specification into which field dependencies should be injected is
- considered to be a good pattern and might even be required in future versions
- of Plexus.
+### Configuration
 
-** Configuration
- 
- Lastly, there is an optional configuration section which is used to configure
- your component.
+Lastly, there is an optional configuration section which is used to configure your component.
 
-+------------------------------------------+
+```
 ...
 <component>
   ...
@@ -321,23 +277,13 @@ public class SomeComponentImpl
   </configuration>
 <component>
 ...
-+------------------------------------------+
-
- You may read more about it {{{./plexus-auto-configuration.html}here}}.
-
- And that's all you need to know about component configuration to
- get you started!
-
- <<Important remark>>: Component configuration and component requirements
- (definition of dependencies on some other components) are separated in Plexus.
- In some popular containers like Spring this is not the case. The reason
- for this is that component requirements are constant - components always needs
- to use the same set of services provided by other components in order to
- function properly. But configuration of a component is more dynamic.  For
- example components which provide an implementation of a jdbc database connection pool
- must always be configured in each application which uses it.
-
-~~ TODO The link in the following paragraph is broken
- 
- If you want to learn more about more advanced options you can read
- {{{./component-descriptor-specification.xml}Component Descriptor}}.
+```
+
+You may read more about it [here](./plexus-auto-configuration.html).
+
+And that's all you need to know about component configuration to get you started!
+
+**Important remark**: Component configuration and component requirements (definition of dependencies on some other components) are separated in Plexus. In some popular containers like Spring this is not the case. The reason for this is that component requirements are constant - components always needs to use the same set of services provided by other components in order to function properly. But configuration of a component is more dynamic. For example components which provide an implementation of a jdbc database connection pool must always be configured in each application which uses it.
+
+<!--  TODO The link in the following paragraph is broken -->
+If you want to learn more about more advanced options you can read [Component Descriptor](./component-descriptor-specification.xml).
diff --git a/src/site/markdown/guides/developer-guide/configuration/index.md b/src/site/markdown/guides/developer-guide/configuration/index.md
index c6d2583..7e68153 100644
--- a/src/site/markdown/guides/developer-guide/configuration/index.md
+++ b/src/site/markdown/guides/developer-guide/configuration/index.md
@@ -1,73 +1,61 @@
-  ------
-  Developer Guide - Introduction to Plexus Configuration
-  ------
-  Rahul Thakur
-  ------
-2006-06-17
-  ------
- 
- 
-<<The contents of this document are a work in progress>>
- 
-Configuration files
- 
-* Plexus is using the following configuration files
- 
-  * plexus.xml
-
-  * plexus.properties
-
-  * components.xml files stored in jars
- 
-
- !plexus-configuration-files.gif!
- 
- 
- All components which can be used by plexus must have a {{{./component-descriptor.html}Component Descriptor}}.
-
- 
- Component Descriptors can be declared in two places:  <<plexus.xml>> and in <<components.xml>> files which are kept in jars (META-INF/plexus/components.xml).
- 
- 
- <<plexus.xml>> files allows you to configure the following aspects of application:
- 
-  * Define new component descriptors
-
-  * Override component descriptors which are defined in components.xml files
-
-  * Set up LoggerManager for the Application.
-
-  * Choose which component should be loaded on startup
-
- ~~TODO Explain Component repository
-  * Location of {{{#}component repository}}
- 
- Plexus component descriptor contains many pieces which must be provided only once. For example componet requiremnets, profile
- etc are pratically constant.
- 
- That's why it is profitable to put such information into jar files and reuse it.
- 
- 
- <<plexus.properties>> file is used for seeding {{{/404.html}plexus context}} which is then used for interpolation of variables in xml configuration files
- (see the explanation below)
- 
- 
-* Component configuration through <<</META-INF/plexus/components.xml>>>
-
- When starting up Plexus will start discovering components. The default configuration uses the {{{http://svn.plexus.codehaus.org/plexus/trunk/plexus-container/src/java/org/codehaus/plexus/component/discovery/DefaultComponentDiscoverer.java?rev=HEAD&view=auto}DefaultComponentDiscoverer}} to discover components.
- 
- The {{{/404.html}DefaultComponentDiscoverer}} will look for <<</META-INF/plexus/components.xml>>>
- files using {{{http://java.sun.com/j2se/1.4.2/docs/api/java/lang/ClassLoader.html#getResources(java.lang.String)}ClassLoader.getResources()}}. For getting your components picked up by plexus all you need is to have the {{{/404.html}components.xml}} file in your jar.
- 
- 
-* Interpolation of configuration files
-
- Plexus will interpolate all the variables that are strings in the plexus context in the configuration file.  For instance, the "plexus.home" is a context variable that tells you the location of the Plexus install.  To use that in your configuration, you would do something like this:
-
-+-------------------------+
+---
+title: Developer Guide - Introduction to Plexus Configuration
+author: Rahul Thakur
+date: 2006-06-17
+---
+
+# **The contents of this document are a work in progress**
+
+# Configuration files
+
+## Plexus is using the following configuration files
+
+- plexus.xml
+
+- plexus.properties
+
+- components.xml files stored in jars
+
+!plexus-configuration-files.gif!
+
+All components which can be used by plexus must have a [Component Descriptor](./component-descriptor.html).
+
+Component Descriptors can be declared in two places: **plexus.xml**and in**components.xml** files which are kept in jars (META-INF/plexus/components.xml).
+
+**plexus.xml** files allows you to configure the following aspects of application:
+
+- Define new component descriptors
+
+- Override component descriptors which are defined in components.xml files
+
+- Set up LoggerManager for the Application.
+
+- Choose which component should be loaded on startup
+
+<!-- TODO Explain Component repository -->
+
+- Location of [component repository]()
+
+Plexus component descriptor contains many pieces which must be provided only once. For example componet requiremnets, profile etc are pratically constant.
+
+That's why it is profitable to put such information into jar files and reuse it.
+
+**plexus.properties** file is used for seeding [plexus context](/404.html) which is then used for interpolation of variables in xml configuration files (see the explanation below)
+
+## Component configuration through `/META-INF/plexus/components.xml`
+
+When starting up Plexus will start discovering components. The default configuration uses the [DefaultComponentDiscoverer](http://svn.plexus.codehaus.org/plexus/trunk/plexus-container/src/java/org/codehaus/plexus/component/discovery/DefaultComponentDiscoverer.java?rev\=HEAD&view\=auto) to discover components.
+
+The [DefaultComponentDiscoverer](/404.html) will look for `/META-INF/plexus/components.xml` files using [ClassLoader.getResources()](http://java.sun.com/j2se/1.4.2/docs/api/java/lang/ClassLoader.html#getResources(java.lang.String)). For getting your components picked up by plexus all you need is to have the [components.xml](/404.html) file in your jar.
+
+## Interpolation of configuration files
+
+Plexus will interpolate all the variables that are strings in the plexus context in the configuration file. For instance, the "plexus.home" is a context variable that tells you the location of the Plexus install. To use that in your configuration, you would do something like this:
+
+```
  <configuration>
    <directory>${plexus.home}/directory</directory>
  </configuration>
-+-------------------------+
+```
 
- This would automatically be expanded to the full directory name when you configure your component.
+This would automatically be expanded to the full directory name when you configure your component.
diff --git a/src/site/markdown/guides/developer-guide/configuration/plexus-auto-configuration.md b/src/site/markdown/guides/developer-guide/configuration/plexus-auto-configuration.md
index 60f6fad..107a445 100644
--- a/src/site/markdown/guides/developer-guide/configuration/plexus-auto-configuration.md
+++ b/src/site/markdown/guides/developer-guide/configuration/plexus-auto-configuration.md
@@ -1,25 +1,22 @@
- ------
- How auto-configuration works
- ------
- Michal Maczka
- ------
-2004-10-13
- ------
+---
+title: How auto-configuration works
+author: Michal Maczka
+date: 2004-10-13
+---
 
- <<<The contents of this document are a work in progress>>>
+`The contents of this document are a work in progress`
 
-Plexus Auto Configuration
+# Plexus Auto Configuration
 
-* Auto configuration is ...
+## Auto configuration is ...
 
-    If you are familiar with libraries like {{{http://xstream.codehaus.org}xstream}} you will feel at home. If not, it's simple enough anyway.
+If you are familiar with libraries like [xstream](http://xstream.codehaus.org) you will feel at home. If not, it's simple enough anyway.
 
-    The best way to understand how the plexus ComponentConfigurator functions is by example.
-    Assuming that the auto-configuration mechanism is applied to class:
+The best way to understand how the plexus ComponentConfigurator functions is by example. Assuming that the auto-configuration mechanism is applied to class:
 
-    <<com.MyComponent>>
+**com.MyComponent**
 
-+-----------------------------------------------------------------------------+
+```
 class com.MyComponent implements com.SomeInterface
 {
    private String propertyA;
@@ -28,11 +25,11 @@ class com.MyComponent implements com.SomeInterface
 
    ...
 }
-+-----------------------------------------------------------------------------+
+```
 
-    with a plexus configuration like so:
+with a plexus configuration like so:
 
-+-----------------------------------------------------------------------------+
+```
 <component>
   <role>com.SomeInterface</role>
   <implementation>com.MyComponent</implementation>
@@ -41,58 +38,55 @@ class com.MyComponent implements com.SomeInterface
         <propertyB>1</propertyA>
     </configuration>
 </component>
-+-----------------------------------------------------------------------------+
+```
 
-    The actions the plexus ComponentConfigurator would perform on
-    the instance of component would be something like this:
+The actions the plexus ComponentConfigurator would perform on the instance of component would be something like this:
 
-+-----------------------------------------------------------------------------+
+```
 com.SomeInterface component = new com.MyComponent();
 
 component.propertyA = "foo";
 
 component.propertyB = 1;
-+-----------------------------------------------------------------------------+
+```
 
+### Types Supported by Autoconfiguration
 
+#### Basic
 
-** Types Supported by Autoconfiguration
+- java.lang.Boolean & boolean
 
-***   Basic
+- java.lang.Byte & byte
 
-        * java.lang.Boolean & boolean
+- java.lang.Character & char
 
-        * java.lang.Byte & byte
+- java.lang.Double & double
 
-        * java.lang.Character & char
+- java.lang.Float & float
 
-        * java.lang.Double & double
+- java.lang.Integer & int
 
-        * java.lang.Float & float
+- java.lang.Long & long
 
-        * java.lang.Integer & int
+- java.lang.Short & short
 
-        * java.lang.Long & long
+- java.lang.StringBuffer
 
-        * java.lang.Short & short
+- java.lang.String
 
-        * java.lang.StringBuffer
+- java.util.Date (todo: document supported patterns)
 
-        * java.lang.String
+- java.math.BigDecimal
 
-        * java.util.Date (todo: document supported patterns)
+- java.math.BigInteger
 
-        * java.math.BigDecimal
+#### Composite types (Object properties)
 
-        * java.math.BigInteger
+- **Object with properties**
 
-***   Composite types (Object properties)
+_Component implementation:_
 
-        * <<Object with properties>>
-
-            <Component implementation:>
-
-+-----------------------------------------------------------------------------+
+```
 class com.MyComponent
 {
    private Person person;
@@ -108,51 +102,49 @@ class com.Person
 
    ...
 }
-+-----------------------------------------------------------------------------+
+```
 
-            <Component configuration :>
+_Component configuration :_
 
-+-----------------------------------------------------------------------------+
+```
 <configuration>
    <person>
        <firstname>Baltzar<firstname>
        <lastname>Gabka</lastname>
    </person>
 </configuration>
-+-----------------------------------------------------------------------------+
-
+```
 
-            <Actions taken by Component Configurator:>
+_Actions taken by Component Configurator:_
 
-+-----------------------------------------------------------------------------+
+```
 Person person = new Person();
 
 person.firstname = "Baltazar";
 person.lastname = "Gabka";
 
 component.person = person;
-+-----------------------------------------------------------------------------+
+```
 
+- **Collections**
 
-        * <<Collections>>
+TODO: Collections example.
 
-            TODO: Collections example.
+- **java.lang.Properties**
 
-        * <<java.lang.Properties>>
+_Component implementation:_
 
-            <Component implementation:>
-
-+-----------------------------------------------------------------------------+
+```
 class com.MyComponent
 {
    private Properties propertiesA;
    ...
 }
-+-----------------------------------------------------------------------------+
+```
 
-            <Component configuration :>
+_Component configuration :_
 
-+-----------------------------------------------------------------------------+
+```
 <configuration>
    <propertiesA>
       <property>
@@ -165,11 +157,11 @@ class com.MyComponent
       </property>
    </propertiesA>
 </configuration>
-+-----------------------------------------------------------------------------+
+```
 
-            <Actions taken by Component Configurator:>
+_Actions taken by Component Configurator:_
 
-+-----------------------------------------------------------------------------+
+```
 
 com.MyComponent component;
 
@@ -183,26 +175,24 @@ setFieldValue( component, "propertiesA", properties );
 
 component.propertiesA = properties;
 
-+-----------------------------------------------------------------------------+
-        []
-
-*** Advanced mapping
+```
 
-    ~~michal: Doesn't this belong in the Collection's section?
+#### Advanced mapping
 
-    ~~TODO: Flesh out...
+<!-- michal: Doesn't this belong in the Collection's section? -->
+<!-- TODO: Flesh out... -->
 
-+-----------------------------------------------------------------------------+
+```
 <foos elements="java.lang.String"/>
     <id>ala</id>
     <id>ala</id>
     <id>ala</id>
 </foos>
-+-----------------------------------------------------------------------------+
+```
 
-        or possibly (pending implementation)
+or possibly (pending implementation)
 
-+-----------------------------------------------------------------------------+
+```
 <foos elements="com.MyBean" implementation="java.util.LinkedList"/>
     <bean>
         <id>foo</id>
@@ -211,4 +201,4 @@ component.propertiesA = properties;
         </id>ala</id>
     </bean>
 </foos>
-+-----------------------------------------------------------------------------+
+```
diff --git a/src/site/markdown/guides/developer-guide/deploying-pars.md b/src/site/markdown/guides/developer-guide/deploying-pars.md
index 2682675..5757f65 100644
--- a/src/site/markdown/guides/developer-guide/deploying-pars.md
+++ b/src/site/markdown/guides/developer-guide/deploying-pars.md
@@ -1,9 +1,7 @@
- ------
- Developer Guide - Plexus Application Server - Deploying PARs
- ------
- Rahul Thakur
- ------
-2006-06-17
- ------
+---
+title: Developer Guide - Plexus Application Server - Deploying PARs
+author: Rahul Thakur
+date: 2006-06-17
+---
 
-Deploying PARs on a Plexus Applicaton Server instance
+# Deploying PARs on a Plexus Applicaton Server instance
diff --git a/src/site/markdown/guides/developer-guide/developing-components.md b/src/site/markdown/guides/developer-guide/developing-components.md
index 4d98777..d6ca3ba 100644
--- a/src/site/markdown/guides/developer-guide/developing-components.md
+++ b/src/site/markdown/guides/developer-guide/developing-components.md
@@ -1,9 +1,7 @@
- ------
- Developer Guide - Developing Plexus Components
- ------
- Rahul Thakur
- ------
-2006-06-17
- ------
+---
+title: Developer Guide - Developing Plexus Components
+author: Rahul Thakur
+date: 2006-06-17
+---
 
-Developing Plexus Components
+# Developing Plexus Components
diff --git a/src/site/markdown/guides/developer-guide/index.md b/src/site/markdown/guides/developer-guide/index.md
index 4faa375..4319b5c 100644
--- a/src/site/markdown/guides/developer-guide/index.md
+++ b/src/site/markdown/guides/developer-guide/index.md
@@ -1,69 +1,67 @@
- ------
- Developer Guide - Table of Contents
- ------
- Michal Maczka
- Rahul Thakur
- ------
-2006-06-17
- ------
+---
+title: Developer Guide - Table of Contents
+author:
+  - Michal Maczka
+  - Rahul Thakur
+date: 2006-06-17
+---
 
- <<<The contents of this document are a work in progress>>>
+`The contents of this document are a work in progress`
 
-Table of Contents 
+# Table of Contents
 
-  * {{{./introduction.html}Introduction to Plexus}}
+- [Introduction to Plexus](./introduction.html)
 
-  * {{{./developing-components.html}Developing Components}}
+- [Developing Components](./developing-components.html)
 
-    * {{{./introduction-to-components.html}Introduction To Components}}
+- [Introduction To Components](./introduction-to-components.html)
 
-    * {{{./lifecycle.html}Lifecycle}}
+- [Lifecycle](./lifecycle.html)
 
-    * {{{./personalities/index.html}Personalities}}
+- [Personalities](./personalities/index.html)
 
-      * {{{./personalities/plexus-personality.html}Plexus Personality}}
+- [Plexus Personality](./personalities/plexus-personality.html)
 
-      * {{{./personalities/avalon-personality.html}Avalon Personality}}
+- [Avalon Personality](./personalities/avalon-personality.html)
 
-      * {{{./personalities/pico-personality.html}Pico Personality}}
+- [Pico Personality](./personalities/pico-personality.html)
 
-      * {{{./personalities/spring-personality.html}Spring Personality}}
+- [Spring Personality](./personalities/spring-personality.html)
 
-    * {{{./configuration/index.html}Configuration files}}
+- [Configuration files](./configuration/index.html)
 
-      * {{{./configuration/component-descriptor.html}Component Descriptor}}
+- [Component Descriptor](./configuration/component-descriptor.html)
 
-      * {{{./configuration/plexus-auto-configuration.html}Component auto-configuration}}
+- [Component auto-configuration](./configuration/plexus-auto-configuration.html)
 
-    * {{{./building-components/index.html}Building Components}}
+- [Building Components](./building-components/index.html)
 
-      * {{{./building-components/component-identity.html}Component Identity}}
+- [Component Identity](./building-components/component-identity.html)
 
-      * {{{./building-components/component-testing.html}Component Testing}}
+- [Component Testing](./building-components/component-testing.html)
 
-  * {{{./building-applications/index.html}Developing Applications}}
+- [Developing Applications](./building-applications/index.html)
 
-    * {{{./building-applications/runtime-builder.html}Runtime Builder}}
+- [Runtime Builder](./building-applications/runtime-builder.html)
 
-    * {{{./building-applications/cdc.html}Component Descriptor Creator (CDC)}}
+- [Component Descriptor Creator (CDC)](./building-applications/cdc.html)
 
-  * {{{./plexus-application-server.html}Plexus Application Server}}
+- [Plexus Application Server](./plexus-application-server.html)
 
-    * {{{./building-pars.html}Building PARs}}
+- [Building PARs](./building-pars.html)
 
-    * {{{./deploying-pars.html}Deploying PARs}}
+- [Deploying PARs](./deploying-pars.html)
 
-    * {{{./services.html}Services}}
+- [Services](./services.html)
 
-  * {{{./advanced-topics/index.html}Advanced Topics}}
+- [Advanced Topics](./advanced-topics/index.html)
 
-    * {{{./advanced-topics/plexus-class-loading.html}Plexus Class Loading}}
+- [Plexus Class Loading](./advanced-topics/plexus-class-loading.html)
 
-    * {{{./advanced-topics/programmatic-container-configuration.html}Programmatic Configuration of Container}}
+- [Programmatic Configuration of Container](./advanced-topics/programmatic-container-configuration.html)
 
-  * Appendices 
- 
-    * {{{./appendices/javadoc-tags-reference.html}Appendix I: Javadoc tags reference for CDC}}
-    
-    * {{{./appendices/plexus-maven-plugin-reference.html}Appendix II: Plexus Maven Plugin}}
+- Appendices
 
+- [Appendix I: Javadoc tags reference for CDC](./appendices/javadoc-tags-reference.html)
+
+- [Appendix II: Plexus Maven Plugin](./appendices/plexus-maven-plugin-reference.html)
diff --git a/src/site/markdown/guides/developer-guide/introduction-to-components.md b/src/site/markdown/guides/developer-guide/introduction-to-components.md
index 750032e..32f1c5e 100644
--- a/src/site/markdown/guides/developer-guide/introduction-to-components.md
+++ b/src/site/markdown/guides/developer-guide/introduction-to-components.md
@@ -1,50 +1,39 @@
- ------
- Developer Guide - Introduction to Plexus Components
- ------
- Rahul Thakur
- ------
-2006-06-17
- ------
+---
+title: Developer Guide - Introduction to Plexus Components
+author: Rahul Thakur
+date: 2006-06-17
+---
 
-Introduction to Components
+# Introduction to Components
 
-* What are Components?
+## What are Components?
 
-  {{{http://www.amazon.com/exec/obidos/ASIN/0201745720/qid%3D1090125966/sr%3D11-1/ref%3Dsr%5F11%5F1/104-8989869-2491134} Szyperski}}
-  lists several characteristics of components: composition, units of deployment and resuability.
+[ Szyperski](http://www.amazon.com/exec/obidos/ASIN/0201745720/qid%3D1090125966/sr%3D11-1/ref%3Dsr%5F11%5F1/104-8989869-2491134) lists several characteristics of components: composition, units of deployment and resuability.
 
-  Other projects have also offered what a component may be:
+Other projects have also offered what a component may be:
 
-    * {{{http://picocontainer.codehaus.org/Components} PicoContainer}}
+- [ PicoContainer](http://picocontainer.codehaus.org/Components)
 
-    * {{{http://avalon.apache.org/central/cop/index.html} Avalon}}
+- [ Avalon](http://avalon.apache.org/central/cop/index.html)
 
-    * {{{http://c2.com/cgi/wiki?ComponentOrientedProgramming} C2 - Component Oriented Programming}}
+- [ C2 - Component Oriented Programming](http://c2.com/cgi/wiki?ComponentOrientedProgramming)
 
-  Some descriptions of a component are:
+Some descriptions of a component are:
 
-    * A nontrivial, nearly independent, and replaceable part of a system that fulfils a clear function in the context
-      of a well-defined architecture. A component conforms to and provides the physical realization of a set of
-      interfaces. (Philippe Krutchen, Rational Software)
+- A nontrivial, nearly independent, and replaceable part of a system that fulfils a clear function in the context of a well-defined architecture. A component conforms to and provides the physical realization of a set of interfaces. (Philippe Krutchen, Rational Software)
 
-    * A runtime software component is a dynamically bindable package of one or more programs managed as a unit and
-      accessed through documented interfaces that can be discovered at runtime. (Gartner Group)
+- A runtime software component is a dynamically bindable package of one or more programs managed as a unit and accessed through documented interfaces that can be discovered at runtime. (Gartner Group)
 
-    * A software component is a unit of composition with contractually specified interfaces and explicit context
-      dependencies only. A software component can be deployed independently and is subject to third-party
-      composition. (Clemens Szyperski, <"Component Software">)
+- A software component is a unit of composition with contractually specified interfaces and explicit context dependencies only. A software component can be deployed independently and is subject to third-party composition. (Clemens Szyperski, _"Component Software"_)
 
-    * A self-contained piece of software that can be independently deployed and plugged into an environment that
-      provides a compatible socket. It has well-defined run-time interfaces, and it can cooperate out of the box
-      with other components (Peter Herzum, Olivier Sims, <"Business Component Factory">)
+- A self-contained piece of software that can be independently deployed and plugged into an environment that provides a compatible socket. It has well-defined run-time interfaces, and it can cooperate out of the box with other components (Peter Herzum, Olivier Sims, _"Business Component Factory"_)
 
-* Criteria for Components
+## Criteria for Components
 
-  Meyer: {{{http://www.sdmagazine.com/documents/s=746/sdm0003k/0003k.htm} <"Seven Criteria for Components">}}
+Meyer: [ _"Seven Criteria for Components"_](http://www.sdmagazine.com/documents/s\=746/sdm0003k/0003k.htm)
 
-    * May be used by other software elements (clients).
+- May be used by other software elements (clients).
 
-    * May be used by clients without the intervention of the component's developers.
-
-    * Includes a specification of all dependencies (hardware and software platform, versions, other components).
+- May be used by clients without the intervention of the component's developers.
 
+- Includes a specification of all dependencies (hardware and software platform, versions, other components).
diff --git a/src/site/markdown/guides/developer-guide/introduction.md b/src/site/markdown/guides/developer-guide/introduction.md
index 1bbfb42..1287223 100644
--- a/src/site/markdown/guides/developer-guide/introduction.md
+++ b/src/site/markdown/guides/developer-guide/introduction.md
@@ -1,9 +1,7 @@
- ------
- Developer Guide - Introduction to Plexus
- ------
- Rahul Thakur
- ------
-2006-06-17
- ------
+---
+title: Developer Guide - Introduction to Plexus
+author: Rahul Thakur
+date: 2006-06-17
+---
 
-Introduction
+# Introduction
diff --git a/src/site/markdown/guides/developer-guide/lifecycle.md b/src/site/markdown/guides/developer-guide/lifecycle.md
index 43c4e50..efacc88 100644
--- a/src/site/markdown/guides/developer-guide/lifecycle.md
+++ b/src/site/markdown/guides/developer-guide/lifecycle.md
@@ -1,9 +1,7 @@
- ------
- Developer Guide - Plexus Lifecycle
- ------
- Rahul Thakur
- ------
-2006-06-17
- ------
+---
+title: Developer Guide - Plexus Lifecycle
+author: Rahul Thakur
+date: 2006-06-17
+---
 
-Lifecycle
+# Lifecycle
diff --git a/src/site/markdown/guides/developer-guide/personalities/avalon-personality.md b/src/site/markdown/guides/developer-guide/personalities/avalon-personality.md
index dce4da8..3812d7b 100644
--- a/src/site/markdown/guides/developer-guide/personalities/avalon-personality.md
+++ b/src/site/markdown/guides/developer-guide/personalities/avalon-personality.md
@@ -1,28 +1,24 @@
- ------
- Developer Guide - The 'Avalon' Personality
- ------
- Michal Maczka
- Rahul Thakur
- ------
-2006-06-17
- ------
+---
+title: Developer Guide - The 'Avalon' Personality
+author:
+  - Michal Maczka
+  - Rahul Thakur
+date: 2006-06-17
+---
 
- <<<The contents of this document are a work in progress>>>
+`The contents of this document are a work in progress`
 
-The 'Avalon' personality
+# The 'Avalon' personality
 
- A good overview of how avalon components work can be found on the Avalon
- website {{{http://avalon.apache.org/central/cop/basics.html}here}}. This should
- beneficial if you are programming components for the Plexus personality as
- well, since the Plexus personality is loosely based on the Avalon API.
+A good overview of how avalon components work can be found on the Avalon website [here](http://avalon.apache.org/central/cop/basics.html). This should beneficial if you are programming components for the Plexus personality as well, since the Plexus personality is loosely based on the Avalon API.
 
- * Enabling the Avalon Personality
+- Enabling the Avalon Personality
 
- You must do three things to enable the Avalon personality within Plexus:
+You must do three things to enable the Avalon personality within Plexus:
 
- [[1]] Add the avalon dependencies
+1. Add the avalon dependencies
 
-+---+
+```
 <dependency>
   <id>avalon-framework</id>
   <version>4.1.4</version>
@@ -34,11 +30,11 @@ The 'Avalon' personality
   <artifactId>plexus-avalon-personality</artifactId>
   <version>0.12</version>
 </dependency>
-+---+
+```
 
- [[1]] Add the lifecycle handler to the plexus configuration
+1. Add the lifecycle handler to the plexus configuration
 
-+---+
+```
 <component-repository implementation="org.codehaus.plexus.personality.avalon.AvalonComponentRepository">
     <composition-resolver implementation="org.codehaus.plexus.component.composition.DefaultCompositionResolver"/>
   </component-repository>
@@ -78,22 +74,20 @@ The 'Avalon' personality
       </lifecycle-handler>
     </lifecycle-handlers>
   </lifecycle-handler-manager>
-+---+
+```
 
- If you wish to have the Avalon personality be your <<default>> personality keep
- the line
+If you wish to have the Avalon personality be your **default** personality keep the line
 
-+---+
+```
 <default-lifecycle-handler-id>avalon</default-lifecycle-handler-id>
-+---+
+```
 
- in your code.  Otherwise remove it and add a tag to each avalon component
- configuration like so:
+in your code. Otherwise remove it and add a tag to each avalon component configuration like so:
 
-+---+
+```
 <component>
   <role>org.codehaus.plexus.jetty.ServletContainer</role>
   <implementation>org.codehaus.plexus.jetty.JettyServletContainer</implementation>
   <lifecycle-handler>avalon</lifecycle-handler>
 </component>
-+---+
+```
diff --git a/src/site/markdown/guides/developer-guide/personalities/index.md b/src/site/markdown/guides/developer-guide/personalities/index.md
index 705803f..368aff4 100644
--- a/src/site/markdown/guides/developer-guide/personalities/index.md
+++ b/src/site/markdown/guides/developer-guide/personalities/index.md
@@ -1,102 +1,70 @@
- ------
- Developer Guide - Introduction to Personalities
- ------
- Rahul Thakur
- ------
-2006-06-17
- ------
+---
+title: Developer Guide - Introduction to Personalities
+author: Rahul Thakur
+date: 2006-06-17
+---
 
- <<<The contents of this document are a work in progress>>>
+`The contents of this document are a work in progress`
 
-Overview
+# Overview
 
- Plexus personalities give you the capability to customize how your component
- lifecycle works.  You can mix and match personalities within Plexus to meet
- your needs.  There is the core Plexus personality for "Plexus Components" as
- well as personalities for {{{http://avalon.apache.org}Avalon}} and
- {{{http://picocontainer.codehaus.org}PicoContainer}}
+Plexus personalities give you the capability to customize how your component lifecycle works. You can mix and match personalities within Plexus to meet your needs. There is the core Plexus personality for "Plexus Components" as well as personalities for [Avalon](http://avalon.apache.org) and [PicoContainer](http://picocontainer.codehaus.org)
 
- Which personality you should use depends on your needs.  If you are just
- starting, you will most likely want to use the Plexus personality.  However,
- each personality has it's own pros and cons.
+Which personality you should use depends on your needs. If you are just starting, you will most likely want to use the Plexus personality. However, each personality has it's own pros and cons.
 
-*----------+--------------+----------------+
-|Personality | Pros | Cons |
-*----------*--------------*----------------*
-| Plexus| Dependency Injection, Auto-configuration| In flux/development|
-*----------*--------------*----------------*
-| Avalon| Components could work across containers, Stable API| Lacks sophisticated features|
-*----------*--------------*----------------*
-| Pico| Use pico components with other components| Weak support currently|
-*----------*--------------*----------------*
+|Personality|Pros|Cons|
+|---|---|---|
+|Plexus|Dependency Injection, Auto-configuration|In flux/development|
+|Avalon|Components could work across containers, Stable API|Lacks sophisticated features|
+|Pico|Use pico components with other components|Weak support currently|
 
- The natural question which might be asked: isn't this a bad idea to mix
- component personalities?  The answer is simple: it is usually better to use
- single component personality,, but sometimes you have no choice.  A component
- is not necesserly a simple class which you can write in 5 minutes.  There are
- much more complex components: LDAP servers, Servlet Containers, Embeddable
- databases etc.  For example Apache James (Java mail server) and quite a lot of
- other components which might be useful for someone were writen in accordance
- with Avalon API.  Plexus gives you as possiblity to reuse those components in
- your applications.  
+The natural question which might be asked: isn't this a bad idea to mix component personalities? The answer is simple: it is usually better to use single component personality,, but sometimes you have no choice. A component is not necesserly a simple class which you can write in 5 minutes. There are much more complex components: LDAP servers, Servlet Containers, Embeddable databases etc. For example Apache James (Java mail server) and quite a lot of other components which might be useful for someone were writen in accordance with Avalon API. Plexus gives you as possiblity to reuse those components in your applications.
 
-The Relation between Component Profile and Component Personality
+# The Relation between Component Profile and Component Personality
 
- ~~(Michal Here I am trying  to clarify some terms - any comments and better definitions are much appriciated):
+<!-- (Michal Here I am trying  to clarify some terms - any comments and better definitions are much appriciated): -->
+Component Personality is an implementation of the contract which must be fulfilled by the container in order to allow it to run components which were written in accordance to that contract (API).
 
- Component Personality is an implementation of the contract which must be
- fulfilled by the container in order to allow it to run components which were
- written in accordance to that contract (API).
+Component Profile provides more convinent, shorter syntax for declaring component descriptors
 
- Component Profile provides more convinent, shorter syntax for declaring component descriptors
+Each component profile will contain information about the following:
 
- Each component profile will contain information about the following:
+- component factory
 
- * component factory
+- component composer
 
- * component composer
+- lifecycle handler
 
- * lifecycle handler
+- manager
 
- * manager
+These are used for managing a given component inside the container. Implemenation of those services may already exist or be provided by an implementation of component personality. For example a list of component managers (instantiation strategies) provided by Plexus is quite complete and there is pratically no need for writing new component manager. But situation looks much different for component lifecycles. Avalon and Pico components have their own lifecycles and implemenation of phases of those lifecycles had to be made for Plexus.
 
- These are used for managing a given component inside the container.
- Implemenation of those services may already exist or be provided by an
- implementation of component personality.  For example a list of component
- managers (instantiation strategies) provided by Plexus is quite complete and
- there is pratically no need for writing new component manager.  But situation
- looks much different for component lifecycles.  Avalon and Pico components
- have their own lifecycles and implemenation of phases of those lifecycles had
- to be made for Plexus.
+Without component profile users will have to do:
 
- Without component profile users will have to do:
-
-+--+
+```
 <component>
   ....
   <component-factory>pico</component-factory>
   <component-composer>noop</component-composer>
   <lifecycle-handler>pico</lifecycle-handler>
 <component>
-+--+
+```
 
- with component profile:
+with component profile:
 
-+--+
+```
 <component>
   ....
   <profile>pico</profile>
 <component>
-+--+
+```
 
- It (will be) is possible to override default values of choosen attributes
- defined in component profile. For example for pico component which should
- have instaniation-strategy = "per-lookup" you can just do:
+It (will be) is possible to override default values of choosen attributes defined in component profile. For example for pico component which should have instaniation-strategy \= "per-lookup" you can just do:
 
-+--+
+```
 <component>
   ....
   <profile>pico</profile>
   <instantiation-strategy>per-lookup</instantiation-strategy>
 <component>
-+--+
+```
diff --git a/src/site/markdown/guides/developer-guide/personalities/pico-personality.md b/src/site/markdown/guides/developer-guide/personalities/pico-personality.md
index 39115f8..057373c 100644
--- a/src/site/markdown/guides/developer-guide/personalities/pico-personality.md
+++ b/src/site/markdown/guides/developer-guide/personalities/pico-personality.md
@@ -1,52 +1,23 @@
- ------
- Developer Guide - The 'Pico' Personality
- ------
- Michal Maczka
- Rahul Thakur
- ------
-2006-06-17
- ------
-
- <<<The contents of this document are a work in progress>>>
-
-The 'Pico' Personality
-	
- What characterizes Pico personality is the fact that for Pico components
- instantiation and composition phases are collapsed into one, single operation.
- This is due the fact that Pico components are written with accordance to  the
- type of dependency injection named *Constructor Injection*.  <<Constructor
- Injection>> simply means that dependencies are provided (injected) to the
- component via the constructor.
-
- For Plexus this type of dependency injection is not fundamentally different
- from other types of dependency injection, which are supported by plexus: Field
- Dependency Injection, Setter Dependency Injection, Contextualizable Lookup
- etc. The main differences between Plexus and Pico container is this that
- our "Pico" friends strongly believe that constructor dependency injection is
- is superior to anything else and that container can function (almost) without
- any metadata.
-
- We don't subscribe to this point of view. Plexus' native API promotes {{{/404.html}Field
- Dependency Injection}} and we are recommending using it as it clearly separates
- two concerns: component instantiation and resolution of component's
- dependencies.  This type of dependency injection makes the encapsulation even
- stronger as internals of component are not exposed via any public API.  
-
- But we leave the choice to users which type of the dependency injection is the
- most suitable for them.  Components are all about composition and composition
- takes place on meta level of the container and meta data is the glue which
- makes it possible.  We believe that any "serious" container must have rich
- enough metadata for effectively "plumbing" existing components.  We also
- believe that although we do require much more metadata then Pico, the usage of
- Plexus is almost as simple as usage of Pico but we provide more powerful
- options, which are eliminated by the lack of metadata in Pico container.  Note
- also that component testing is often even simpler in case of Plexus then in
- case of Pico due to the fact that we leverage container as mock infrastructure
- and we make a use of existing metadata so for example "requirements"
- (dependencies) of the component does not have to be listed specifically for
- unit tests.  This makes unit tests shorter hence simpler.
-	
- Plexus is probably more similar to Nano Container or most likely it is
- comparable to whatever future Micro Container might be.
-
-* How to use Pico Components inside Plexus
+---
+title: Developer Guide - The 'Pico' Personality
+author:
+  - Michal Maczka
+  - Rahul Thakur
+date: 2006-06-17
+---
+
+`The contents of this document are a work in progress`
+
+# The 'Pico' Personality
+
+What characterizes Pico personality is the fact that for Pico components instantiation and composition phases are collapsed into one, single operation. This is due the fact that Pico components are written with accordance to the type of dependency injection named \*Constructor Injection\*. **Constructor Injection** simply means that dependencies are provided (injected) to the component via the constructor.
+
+For Plexus this type of dependency injection is not fundamentally different from other types of dependency injection, which are supported by plexus: Field Dependency Injection, Setter Dependency Injection, Contextualizable Lookup etc. The main differences between Plexus and Pico container is this that our "Pico" friends strongly believe that constructor dependency injection is is superior to anything else and that container can function (almost) without any metadata.
+
+We don't subscribe to this point of view. Plexus' native API promotes [Field Dependency Injection](/404.html) and we are recommending using it as it clearly separates two concerns: component instantiation and resolution of component's dependencies. This type of dependency injection makes the encapsulation even stronger as internals of component are not exposed via any public API.
+
+But we leave the choice to users which type of the dependency injection is the most suitable for them. Components are all about composition and composition takes place on meta level of the container and meta data is the glue which makes it possible. We believe that any "serious" container must have rich enough metadata for effectively "plumbing" existing components. We also believe that although we do require much more metadata then Pico, the usage of Plexus is almost as simple as usage of Pico but we provide more powerful options, which are eliminated by the lack of metadata in Pico container. Note also that component testing is often even simpler in case of Plexus then in case of Pico due to the fact that we leverage container as mock infrastructure and we make a use of existing metadata so for example "requirements" (dependencies) of the component does not have to be listed specifically for unit tests. This makes unit tests shorter hence simpler.
+
+Plexus is probably more similar to Nano Container or most likely it is comparable to whatever future Micro Container might be.
+
+## How to use Pico Components inside Plexus
diff --git a/src/site/markdown/guides/developer-guide/personalities/plexus-personality.md b/src/site/markdown/guides/developer-guide/personalities/plexus-personality.md
index 24b7dee..6970726 100644
--- a/src/site/markdown/guides/developer-guide/personalities/plexus-personality.md
+++ b/src/site/markdown/guides/developer-guide/personalities/plexus-personality.md
@@ -1,73 +1,50 @@
- ------
- Developer Guide - 'Plexus' Personality
- ------
- Michal Maczka 
- Rahul Thakur
- ------
-2006-06-17
- ------
+---
+title: Developer Guide - 'Plexus' Personality
+author:
+  - Michal Maczka
+  - Rahul Thakur
+date: 2006-06-17
+---
 
- <<<The contents of this document are a work in progress>>>
+`The contents of this document are a work in progress`
 
-The 'Plexus' Personality
+# The 'Plexus' Personality
 
-* Overview
+## Overview
 
- The Plexus personality revolves around two segments.  The 'begin' and the 
- 'end' segments.  The 'begin' segment is run when your component is being 
- started up and the 'end' segment when it is being shut down.
+The Plexus personality revolves around two segments. The 'begin' and the 'end' segments. The 'begin' segment is run when your component is being started up and the 'end' segment when it is being shut down.
 
-** Begin Phase
+### Begin Phase
 
-*-----+------+------+
-| Phase | Interface | Description | 
-*-----*------*------*
-|  LogEnable | LogEnable | Passes a logger to your component.  You will most likely want to inherit AbstractLogEnabled instead | 
-*-----*------*------*
-|  Composition | (no interface) | Injects your dependencies (see below) | 
-*-----*------*------*
-|  Context | Contextualizable | Passes the Plexus context.  From here you can access the home directory, Plexus Container, and more.
-*-----*------*------*
-|  Configuration | PlexusConfigurable | Gives you access to the PlexusConfiguration to configure your application | 
-*-----*------*------*
-|  Intialization | Initializable | Initializes your component.
-*-----*------*------*
-|  Start | Startable | Starts your component | 
-*-----*------*------*
+|Phase|Interface|Description|
+|---|---|---|
+|LogEnable|LogEnable|Passes a logger to your component. You will most likely want to inherit AbstractLogEnabled instead|
+|Composition|(no interface)|Injects your dependencies (see below)|
+|Context|Contextualizable|Passes the Plexus context. From here you can access the home directory, Plexus Container, and more.|
+|Configuration|PlexusConfigurable|Gives you access to the PlexusConfiguration to configure your application|
+|Intialization|Initializable|Initializes your component.|
+|Start|Startable|Starts your component|
 
+### End Phase
 
-** End Phase
+|Phase|Interface|Description|
+|---|---|---|
+|Stop|Startable|Stops your component|
+|Dispose|Disposable|Allows you to dispose of the components you depend on and other resources.|
+|LogDisable|LogEnabled|Disables component logging|
 
-*-----+------+------+
-| Phase | Interface | Description | 
-*-----*------*------*
-|  Stop | Startable | Stops your component | 
-*-----*------*------*
-|  Dispose | Disposable | Allows you to dispose of the components you depend on and other resources. | 
-*-----*------*------*
-|  LogDisable | LogEnabled | Disables component logging | 
-*-----*------*------*
+### Dependency Injection
 
-** Dependency Injection
+Plexus has the ability to do automatic dependency injection. When your component is being composed it will automatically fill in the fields or setters with your components dependencies.
 
- Plexus has the ability to do automatic dependency injection.  When your
- component is being composed it will automatically fill in the fields or
- setters with your components dependencies.
+### Configuration
 
-** Configuration
+The Plexus personality can configure your component two ways. In the auto configuration mode, it matches the xml to fields and classes on your components using [XStream](http://xstream.codehaus.org). For example, if you have a String field named "cheese" on your component, then this would automatically set that field to "swiss".
 
- The Plexus personality can configure your component two ways.  In the auto
- configuration mode, it matches the xml to fields and classes on your
- components using {{{http://xstream.codehaus.org}XStream}}. For example, if you
- have a String field named "cheese" on your component, then this would
- automatically set that field to "swiss".
-
-+---+
+```
 <configuration>
   <cheese>swiss</cheese>
 </configuration>
-+---+
+```
 
- If this doesn't provide the needed flexibility you can implement the interface
- PlexusConfigurable and the PlexusConfiguration object for your component will
- be passed on to you.
+If this doesn't provide the needed flexibility you can implement the interface PlexusConfigurable and the PlexusConfiguration object for your component will be passed on to you.
diff --git a/src/site/markdown/guides/developer-guide/personalities/spring-personality.md b/src/site/markdown/guides/developer-guide/personalities/spring-personality.md
index 3fb2c9f..e48b470 100644
--- a/src/site/markdown/guides/developer-guide/personalities/spring-personality.md
+++ b/src/site/markdown/guides/developer-guide/personalities/spring-personality.md
@@ -1,11 +1,9 @@
- ------
- Developer Guide - The 'Spring' Personality
- ------
- Rahul Thakur
- ------
-2006-06-17
- ------
+---
+title: Developer Guide - The 'Spring' Personality
+author: Rahul Thakur
+date: 2006-06-17
+---
 
- <<<The contents of this document are a work in progress>>>
+`The contents of this document are a work in progress`
 
-The 'Spring' Personality
+# The 'Spring' Personality
diff --git a/src/site/markdown/guides/developer-guide/plexus-application-server.md b/src/site/markdown/guides/developer-guide/plexus-application-server.md
index 4bd94d7..cdd923c 100644
--- a/src/site/markdown/guides/developer-guide/plexus-application-server.md
+++ b/src/site/markdown/guides/developer-guide/plexus-application-server.md
@@ -1,9 +1,7 @@
- ------
- Developer Guide - Plexus Application Server
- ------
- Rahul Thakur
- ------
-2006-06-17
- ------
+---
+title: Developer Guide - Plexus Application Server
+author: Rahul Thakur
+date: 2006-06-17
+---
 
-Plexus Application Server
+# Plexus Application Server
diff --git a/src/site/markdown/guides/developer-guide/services.md b/src/site/markdown/guides/developer-guide/services.md
index 0fa9b50..4e293da 100644
--- a/src/site/markdown/guides/developer-guide/services.md
+++ b/src/site/markdown/guides/developer-guide/services.md
@@ -1,9 +1,7 @@
- ------
- Developer Guide - Plexus Application Server - Services
- ------
- Rahul Thakur
- ------
-2006-06-17
- ------
+---
+title: Developer Guide - Plexus Application Server - Services
+author: Rahul Thakur
+date: 2006-06-17
+---
 
-Services 
+# Services
diff --git a/src/site/markdown/guides/plexus-web-applications/01_preparing_for_project.md b/src/site/markdown/guides/plexus-web-applications/01_preparing_for_project.md
index 406dad2..3c1fa64 100644
--- a/src/site/markdown/guides/plexus-web-applications/01_preparing_for_project.md
+++ b/src/site/markdown/guides/plexus-web-applications/01_preparing_for_project.md
@@ -1,97 +1,80 @@
- -----
- Chapter 1 : Setting up a Web application project
- -----
- Rahul Thakur
- -----
-2006-07-10
- -----
+---
+title: Chapter 1 : Setting up a Web application project
+author: Rahul Thakur
+date: 2006-07-10
+---
 
-Overview
+# Overview
 
- The chapter explains how to set up a Plexus web application project.
+The chapter explains how to set up a Plexus web application project.
 
-* Pre-requisites
+## Pre-requisites
 
- The tutorial assumes you have Maven 2.0.x+ setup and have an internet 
- connection and are able to download required Maven artifacts from online 
- repositories.
+The tutorial assumes you have Maven 2.0.x\+ setup and have an internet connection and are able to download required Maven artifacts from online repositories.
 
- 
-* Set up a Web application project from an Archetype
+## Set up a Web application project from an Archetype
 
- We use Maven's Web application archetype to create a skeleton web application 
- project to get us started. 
+We use Maven's Web application archetype to create a skeleton web application project to get us started.
 
- From the command prompt, change directory to the location where you wish to 
- set up the new Plexus Component project.  Run the following command from the
- command line to setup an initial project structure
+From the command prompt, change directory to the location where you wish to set up the new Plexus Component project. Run the following command from the command line to setup an initial project structure
 
-+------------------------------------------+
+```
  mvn archetype:create -DarchetypeGroupId=org.apache.maven.archetype -DarchetypeArtifactId=maven-archetype-webapp -DarchetypeVersion=1.0-
 SNAPSHOT -DgroupId=org.codehaus.plexus.examples -DartifactId=plexus-example-webapp  -DpackageName=org.codehaus.plexus.tutorial -Dpackaging=war
-+------------------------------------------+ 
-
- This should create a blank web application project.
-
-** Archetype creation options explained
-
- More info on archetype creation and usage can be found here?
-
- The following table explains the options that we used above.
-
-*----------+--------------+----------------:
-| Commandline Option 	| Description 	| Required |
-*----------+--------------+----------------:
-| -DarchetypeGroupId 	| "groupId" for the archetype we want to use 	| Yes |
-*----------+--------------+----------------:
-| -DarchetypeArtifact 	| "artifactId" for the archetype we want to use |	Yes |
-*----------+--------------+----------------:
-| -DarchetypeVersion 	| "version" for the archetype we want to use 	| Yes| 
-*----------+--------------+----------------:
-| -DgroupId 	| "groupId" for the project to be generated 	| Yes |
-*----------+--------------+----------------:
-| -DartifactId | "artifactId" for the project to be generated |	Yes |
-*----------+--------------+----------------:
-| -DpackageName |	Base package name to be use for any Java sources being copied over 	| No|
-*----------+--------------+----------------:
- 
-* Generate a Project for your IDE.
-
-** For Eclipse.
- 
-   [[1]] Change directory to the newly created directory 'plexus-example-webapp'
-   
-   [[1]] Open up pom.xml and review the handful of dependencies setup there for version changes.
-
-   [[1]] Run the following command from command prompt to generate Eclipse project setting files.
-
-+------------------------------------------+
+```
+
+This should create a blank web application project.
+
+### Archetype creation options explained
+
+More info on archetype creation and usage can be found here?
+
+The following table explains the options that we used above.
+
+|Commandline Option|Description|Required|
+|---|---|---|
+|-DarchetypeGroupId|"groupId" for the archetype we want to use|Yes|
+|-DarchetypeArtifact|"artifactId" for the archetype we want to use|Yes|
+|-DarchetypeVersion|"version" for the archetype we want to use|Yes|
+|-DgroupId|"groupId" for the project to be generated|Yes|
+|-DartifactId|"artifactId" for the project to be generated|Yes|
+|-DpackageName|Base package name to be use for any Java sources being copied over|No|
+
+## Generate a Project for your IDE.
+
+### For Eclipse.
+
+1. Change directory to the newly created directory 'plexus-example-webapp'
+
+1. Open up pom.xml and review the handful of dependencies setup there for version changes.
+
+1. Run the following command from command prompt to generate Eclipse project setting files.
+
+```
  mvn eclipse:eclipse
-+------------------------------------------+
+```
+
+Eclipse project files should get generated succesfully at this point. If there were any unsatisfied dependencies (due to 2-1-3), update _version_ for dependencies in pom.xml to an available release version.
 
- Eclipse project files should get generated succesfully at this point. If there were any unsatisfied dependencies (due to 2-1-3), update <version> for dependencies in pom.xml to an available release version.
- 
-   [[1]] Fire up Eclipse and import the generated project into an Eclipse Workspace.
- 
-** Add sources/resources directories
+1. Fire up Eclipse and import the generated project into an Eclipse Workspace.
 
-  Create the following directories under the project root for our application resources:
+### Add sources/resources directories
 
-  [[1]] <<<src/main/java>>>
+Create the following directories under the project root for our application resources:
 
-  [[1]] <<<src/main/resources>>>
+1. `src/main/java`
 
-  [[1]] <<<src/test/java>>>
+1. `src/main/resources`
 
-  [[1]] <<<src/test/resources>>>
+1. `src/test/java`
 
+1. `src/test/resources`
 
-* Adding project dependencies
+## Adding project dependencies
 
-  We add project dependencies to the <<<pom.xml>>> located under project root. 
-  The <<<pom.xml>>> looks like below:
+We add project dependencies to the `pom.xml` located under project root. The `pom.xml` looks like below:
 
-+-------------+
+```
 <?xml version="1.0"?><project>
   <parent>
     <artifactId>plexus-examples</artifactId>
@@ -128,21 +111,18 @@ SNAPSHOT -DgroupId=org.codehaus.plexus.examples -DartifactId=plexus-example-weba
     </dependency>
   </dependencies>
 </project>
-+-------------+
+```
 
- Update Eclipse project dependencies for new library that we added above, to do this:  
+Update Eclipse project dependencies for new library that we added above, to do this:
 
-  [[1]] Open up a command prompt window
-  
-  [[2]] Change directory to the Website Monitor project's folder, and
-  
-  [[3]] Run the following command to update the Eclipse project dependencies.       
-   
-+------------------------------------------+
-mvn  eclipse:clean  eclipse:eclipse
-+------------------------------------------+
+1. Open up a command prompt window
+
+1. Change directory to the Website Monitor project's folder, and
 
+1. Run the following command to update the Eclipse project dependencies.
 
- Refresh the Eclipse project in the workspace to reflect the updated dependencies.
- 
+```
+mvn  eclipse:clean  eclipse:eclipse
+```
 
+Refresh the Eclipse project in the workspace to reflect the updated dependencies.
diff --git a/src/site/markdown/guides/plexus-web-applications/index.md b/src/site/markdown/guides/plexus-web-applications/index.md
index efb835b..cda6a06 100644
--- a/src/site/markdown/guides/plexus-web-applications/index.md
+++ b/src/site/markdown/guides/plexus-web-applications/index.md
@@ -1,18 +1,13 @@
- ------
- User Guide - Plexus in Web Application
- ------
- Rahul Thakur
- ------
-2006-07-07
- ------
+---
+title: User Guide - Plexus in Web Application
+author: Rahul Thakur
+date: 2006-07-07
+---
 
- <<<The contents of this document are a work in progress>>>
+`The contents of this document are a work in progress`
 
-About this trail
+# About this trail
 
-  This trail demonstrates how Plexus can be used in Web applications. 
+This trail demonstrates how Plexus can be used in Web applications.
 
-  * {{{./01_preparing_for_project.html}Setting up a Web Project}}
-
-
-  
+- [Setting up a Web Project](./01_preparing_for_project.html)
diff --git a/src/site/markdown/guides/quick-start/component-descriptor-creator.md b/src/site/markdown/guides/quick-start/component-descriptor-creator.md
index 0714b81..d35dede 100644
--- a/src/site/markdown/guides/quick-start/component-descriptor-creator.md
+++ b/src/site/markdown/guides/quick-start/component-descriptor-creator.md
@@ -1,47 +1,36 @@
- ------
- Component Descriptor Creator
- ------
- Trygve Laugst\xF8l
- Brett Porter
- ------
-2006-05-27
- ------
-
- <<<The contents of this document are a work in progress>>>
-
-Plexus Component Descriptor Creator
-
- <<NOTE: This document and the CDC itself is currently a work in progress.>>
-
- The Component Descriptor Creator (or CDC for short) is a tool that will create
- the <<<components.xml>>> file from your Java code. It uses JavaDoc tags to
- gather the information it needs to create the component descriptor.
-
- There is a tag for marking components, requirements and configuration. Each of
- the tags can have parameters as documented below.
-
-* Component Tag Parameters
-
-*-----------------------*--------------*---------------------------------------------*
-| <<Tag>>               | <<Required>> | <<Description>>                             |
-*-----------------------*---*--------------------------------------------------------*
-| role                  | y | The role of the component.                             |
-*-----------------------*---*--------------------------------------------------------*
-| role-hint             | y | The role-hint of the component.                        |
-*-----------------------*---*--------------------------------------------------------*
-| version               | n | The component version.                                 |
-*-----------------------*---*--------------------------------------------------------*
-| lifecycle-handler     | n | The lifecycle handler of the component.                |
-|                       |   | <TODO: link to the different lifecycle handlers>       |
-*-----------------------*---*--------------------------------------------------------*
-| instantiation-strategy | n | The instantiation strategy of the component.           |
-|                       |   | <TODO: link to the different instantiation strategies> |
-*-----------------------*---*--------------------------------------------------------*
-~~ TODO: This line will be incorrectly render the *name* of the table as well
-~~       as the caption
-~~ [plexus-component-tags] Plexus Component Tag Parameters
-
-+---+
+---
+title: Component Descriptor Creator
+author:
+  - Trygve Laugstøl
+  - Brett Porter
+date: 2006-05-27
+---
+
+`The contents of this document are a work in progress`
+
+# Plexus Component Descriptor Creator
+
+**NOTE: This document and the CDC itself is currently a work in progress.**
+
+The Component Descriptor Creator (or CDC for short) is a tool that will create the `components.xml` file from your Java code. It uses JavaDoc tags to gather the information it needs to create the component descriptor.
+
+There is a tag for marking components, requirements and configuration. Each of the tags can have parameters as documented below.
+
+## Component Tag Parameters
+
+|**Tag**|**Required**|**Description**|
+|---|---|---|
+|role|y|The role of the component.|
+|role-hint|y|The role-hint of the component.|
+|version|n|The component version.|
+|lifecycle-handler|n|The lifecycle handler of the component. _TODO: link to the different lifecycle handlers_|
+|instantiation-strategy|n|The instantiation strategy of the component. _TODO: link to the different instantiation strategies_|
+
+<!--  TODO: This line will be incorrectly render the *name* of the table as well -->
+<!--        as the caption -->
+<!--  [plexus-component-tags] Plexus Component Tag Parameters -->
+
+```
 /**
  * @plexus.component
  *   lifecycle-handler="plexus-configurable"
@@ -50,47 +39,43 @@ public class DefaultActionManager
     extends AbstractLogEnabled
     implements ActionManager, Serviceable
 {
-+---+
-~~ [example-class-tags] Example Component Tag
+```
 
-* Requirement Tag Parameters
+<!--  [example-class-tags] Example Component Tag -->
 
- These tags are used on fields to state requirements. TODO: it should be
- possible to override the role for a normal field.
+## Requirement Tag Parameters
 
-*-----------------------*----------------*-------------------------------------------*
-| <<Tag>>               | <<Required>> | <<Description>>                             |
-*-----------------------*-----*------------------------------------------------------*
-| role                  | y/n | Only required if the field is a List or Map          |
-*-----------------------*-----*------------------------------------------------------*
-| role-hint             | n   |                                                      |
-*-----------------------*-----*------------------------------------------------------*
+These tags are used on fields to state requirements. TODO: it should be possible to override the role for a normal field.
 
-+---+
+|**Tag**|**Required**|**Description**|
+|---|---|---|
+|role|y/n|Only required if the field is a List or Map|
+|role-hint|n||
+
+```
 /**
  * @plexus.requirement
  *  role-hint="foo"
  */
 private ActionManager actionManager;
-+---+
-~~ [example-requirement-tags] Example Requirement Tag
+```
+
+<!--  [example-requirement-tags] Example Requirement Tag -->
 
-* Configuration Tag Parameters
+## Configuration Tag Parameters
 
- Note that the default value tag won't be required in the future when these
- tags will be used to generate a separate configuration declaration section.
+Note that the default value tag won't be required in the future when these tags will be used to generate a separate configuration declaration section.
 
-*-----------------------*--------------*---------------------------------------------*
-| <<Tag>>               | <<Required>> | <<Description>>                             |
-*-----------------------*---*--------------------------------------------------------*
-| default-value         | y | Sets the default value for the configuration field     |
-*-----------------------*---*--------------------------------------------------------*
+|**Tag**|**Required**|**Description**|
+|---|---|---|
+|default-value|y|Sets the default value for the configuration field|
 
-+---+
+```
 /**
  * @plexus.configuration
  *  default-value="Trygve"
  */
 private String name;
-+---+
-~~ [example-requirement-tags] Example Configuration Tag
+```
+
+<!--  [example-requirement-tags] Example Configuration Tag -->
diff --git a/src/site/markdown/guides/quick-start/embedder.md b/src/site/markdown/guides/quick-start/embedder.md
index d1be625..1d6f0e4 100644
--- a/src/site/markdown/guides/quick-start/embedder.md
+++ b/src/site/markdown/guides/quick-start/embedder.md
@@ -1,20 +1,12 @@
- -----
- Plexus Embedder
- -----
- Rahul Thakur
- -----
-2006-06-17
- -----
-
-Plexus Embedder 
-
-* Overview 
-
-  ~~ Discuss need for Plexus embedder 
-
-  TODO 
-
-
+---
+title: Plexus Embedder
+author: Rahul Thakur
+date: 2006-06-17
+---
 
+# Plexus Embedder
 
+## Overview
 
+<!--  Discuss need for Plexus embedder  -->
+TODO
diff --git a/src/site/markdown/guides/quick-start/getting-started.md b/src/site/markdown/guides/quick-start/getting-started.md
index 7b3fcf6..11a4dae 100644
--- a/src/site/markdown/guides/quick-start/getting-started.md
+++ b/src/site/markdown/guides/quick-start/getting-started.md
@@ -1,40 +1,34 @@
- -----
- Plexus
- -----
- Brett Porter
- -----
-2006-05-26
- -----
+---
+title: Plexus
+author: Brett Porter
+date: 2006-05-26
+---
 
- <<<The contents of this document are a work in progress>>>
+`The contents of this document are a work in progress`
 
-Five Minute Tutorial
+# Five Minute Tutorial
 
-  In this tutorial, you will create a simple component, and use the Plexus to start a container.
+In this tutorial, you will create a simple component, and use the Plexus to start a container.
 
-  <<Note:>> If you are using Maven 2, you can obtain the full sample code, and then build and run it using the
-  following commands:
+**Note:** If you are using Maven 2, you can obtain the full sample code, and then build and run it using the following commands:
 
-----
+```
 mvn archetype:create \
     -DarchetypeVersion=1.0-SNAPSHOT\
     -DarchetypeGroupId=org.codehaus.plexus.examples -DarchetypeArtifactId=plexus-examples-tutorial \
     -DartifactId=tutorial -DgroupId=test -DremoteRepositories=http://snapshots.repository.codehaus.org/ 
 cd tutorial
 mvn package exec:java
-----
+```
 
- ~~TODO: this is not done
+<!-- TODO: this is not done -->
+## Creating a Component Interface
 
-* Creating a Component Interface
+The first task to creating a component is to define its _role_. In Java, this usually takes the form of defining an interface with the functionality the component will expose.
 
-  The first task to creating a component is to define its <role>. In Java, this usually takes the form of defining
-  an interface with the functionality the component will expose.
+**Note:** Plexus does not strictly require you use an interface to define the role, however it is strongly recommended to help improve your application design.
 
-  <<Note:>> Plexus does not strictly require you use an interface to define the role, however it is strongly recommended
-  to help improve your application design.
-
-----
+```
 package org.codehaus.plexus.examples.tutorial;
 
 public interface Cheese
@@ -54,21 +48,18 @@ public interface Cheese
      */
     String getAroma();
 }
-----
+```
 
-  The interface declares the <<<String>>> identifier for the role in the <<<ROLE>>> field. The name and value of this
-  field are simply a convention, and could possibly be any other value, as long as they are unique within the container.
-  Using the package and class name guarantees this.
-  ~~TODO: Plexus should have syntactic sugar that uses Cheese.class instead
+The interface declares the `String` identifier for the role in the `ROLE` field. The name and value of this field are simply a convention, and could possibly be any other value, as long as they are unique within the container. Using the package and class name guarantees this.
 
-  The other methods in the interface declare the functionality of the component: an ability to slice the cheese into a
-  given number of slices, and method to retrieve a description of the cheese's aroma.
+<!-- TODO: Plexus should have syntactic sugar that uses Cheese.class instead -->
+The other methods in the interface declare the functionality of the component: an ability to slice the cheese into a given number of slices, and method to retrieve a description of the cheese's aroma.
 
-* Creating a Component Implementation
+## Creating a Component Implementation
 
-  Once an interface is declared, you need to create one or more implementations of the functionality declared by it.
+Once an interface is declared, you need to create one or more implementations of the functionality declared by it.
 
-----
+```
 package org.codehaus.plexus.examples.tutorial;
 
 public class ParmesanCheese
@@ -84,17 +75,15 @@ public class ParmesanCheese
         return "strong";
     }
 }
-----
+```
 
-  The implementation of the <<<Cheese>>> interface above, <<<ParmesanCheese>>> provides the functionality for both the
-  <<<slice()>>> and <<<getAroma()>>> methods, making the component complete.
+The implementation of the `Cheese` interface above, `ParmesanCheese` provides the functionality for both the `slice()` and `getAroma()` methods, making the component complete.
 
-* Creating a Component Descriptor
+## Creating a Component Descriptor
 
-  The final step is to create a component descriptor file, located in <<<META-INF/plexus/components.xml>>> inside the
-  JAR or classloader that houses the component.
+The final step is to create a component descriptor file, located in `META-INF/plexus/components.xml` inside the JAR or classloader that houses the component.
 
-----
+```
 <component-set>
   <components>
     <component>
@@ -104,26 +93,21 @@ public class ParmesanCheese
     </component>
   </components>
 </component-set>
-----
+```
 
-  As you can see, the descriptor contains the single component, with the role declared earlier of <<<Cheese>>>.
-  The descriptor specifies what implementation is used for a given <role hint>. The hint is a mandatory field that
-  differentiates implementations of a given component, and is used when later referencing the component.
+As you can see, the descriptor contains the single component, with the role declared earlier of `Cheese`. The descriptor specifies what implementation is used for a given _role hint_. The hint is a mandatory field that differentiates implementations of a given component, and is used when later referencing the component.
 
-  <<Note:>> It is not necessary to create this descriptor, as the
-  {{{./component-descriptor-creator.html} Component Descriptor Creator}} can do it for you based on the
-  Java class definition and some additional Javadoc annotations.
+**Note:** It is not necessary to create this descriptor, as the [ Component Descriptor Creator](./component-descriptor-creator.html) can do it for you based on the Java class definition and some additional Javadoc annotations.
 
-* Executing the Plexus Application
+## Executing the Plexus Application
 
-  The final step is to execute the application that uses this component. In this example, you will use
-  an container from a standard Java class with a <<<main()>>> method.
+The final step is to execute the application that uses this component. In this example, you will use an container from a standard Java class with a `main()` method.
 
-** Creating the container
+### Creating the container
 
-  Creating the container is very simple:
+Creating the container is very simple:
 
-----
+```
 import org.codehaus.plexus.PlexusContainer;
 import org.codehaus.plexus.PlexusContainerException;
 
@@ -136,35 +120,30 @@ public class App
         container.dispose();
     }
 }
-----
+```
 
-  That's all there is to it: create the container, and start it. Defaults and the current classloader will be used,
-  however if you need a more advanced embedder container configuration, see {{{./embedder.html} Using the
-  embedder}}.
+That's all there is to it: create the container, and start it. Defaults and the current classloader will be used, however if you need a more advanced embedder container configuration, see [ Using the embedder](./embedder.html).
 
-** Retrieving the Component
+### Retrieving the Component
 
-  To retrieve the <<<Cheese>>> component from the container and execute it's <<<getAroma()>>> method, add the
-  following lines after those that start the container:
+To retrieve the `Cheese` component from the container and execute it's `getAroma()` method, add the following lines after those that start the container:
 
-----
+```
     Cheese cheese = (Cheese) container.lookup( Cheese.ROLE, "parmesan" );
     System.out.println( "Parmesan is " + cheese.getAroma() );
-----
+```
 
-  That's all there is to getting started with Plexus. Congratulations!
+That's all there is to getting started with Plexus. Congratulations!
 
-  If you are not familiar with component-oriented programming, you may be wondering why you wouldn't just do this:
+If you are not familiar with component-oriented programming, you may be wondering why you wouldn't just do this:
 
-----
+```
     Cheese cheese = new ParmesanCheese();
     System.out.println( "Parmesan is " + cheese.getAroma() );
-----
-
-  For answers to this question and more, see {{{/ref/why-use-components.html} Why Use Components?}}
-
-* Learning More
+```
 
-  To learn more about writing components, take the {{{/guides/writing-components/00_index.html} Component Tutorial}}.
+For answers to this question and more, see [ Why Use Components?](/ref/why-use-components.html)
 
+## Learning More
 
+To learn more about writing components, take the [ Component Tutorial](/guides/writing-components/00_index.html).
diff --git a/src/site/markdown/guides/quick-start/one-minute-tutorial.md b/src/site/markdown/guides/quick-start/one-minute-tutorial.md
index dac821f..28e18ae 100644
--- a/src/site/markdown/guides/quick-start/one-minute-tutorial.md
+++ b/src/site/markdown/guides/quick-start/one-minute-tutorial.md
@@ -1,15 +1,14 @@
- -----
- Plexus
- -----
- -----
+---
+title: Plexus
+---
 
-<<This is an old piece of documentation, yet to be integrated into the new site and removed>>
+# **This is an old piece of documentation, yet to be integrated into the new site and removed**
 
-...
+# ...
 
- [[1]] You must create your component implementation.
+1. You must create your component implementation.
 
-+---+
+```
 import org.codehaus.plexus.personality.plexus.lifecycle.phase.Initializable;
 
 public class DefaultCheeseComponent
@@ -27,11 +26,6 @@ public class DefaultCheeseComponent
         return cheese;
     }
 }
-+---+
+```
 
- Notice that we implement <<<Intializable>>>. This is part of the
- {{{./plexus-lifecycle.html}Component Lifecycle}}. When plexus automatically
- instantiates your component it will automatically <<<intiailize()>>> it as
- well.
-
- 
\ No newline at end of file
+Notice that we implement `Intializable`. This is part of the [Component Lifecycle](./plexus-lifecycle.html). When plexus automatically instantiates your component it will automatically `intiailize()` it as well.
diff --git a/src/site/markdown/guides/trails/index.md b/src/site/markdown/guides/trails/index.md
index 913eb86..90a6c1e 100644
--- a/src/site/markdown/guides/trails/index.md
+++ b/src/site/markdown/guides/trails/index.md
@@ -1,48 +1,37 @@
- -----
- Plexus Documentation Trails 
- -----
- Rahul Thakur
- -----
-2006-06-16
- -----
+---
+title: Plexus Documentation Trails
+author: Rahul Thakur
+date: 2006-06-16
+---
 
-Documentation Trails
+# Documentation Trails
 
-  The Plexus documentation is organised into trails, depending on how you intend to use it.
+The Plexus documentation is organised into trails, depending on how you intend to use it.
 
-* Component-oriented Programming Trail
+## Component-oriented Programming Trail
 
-  This trail is for those that are new to component-oriented programming and would like to know more about it,
-  independant of Plexus.
+This trail is for those that are new to component-oriented programming and would like to know more about it, independant of Plexus.
 
-  [[1]] {{{../../ref/why-use-components.html} Why Use Components?}}
+1. [ Why Use Components?](../../ref/why-use-components.html)
 
-  ~~TODO: finish
-  
+<!-- TODO: finish -->
 
-* Component Trail
+## Component Trail
 
-  This trail is for those wishing to create Plexus components for applications already using the Plexus Container
+This trail is for those wishing to create Plexus components for applications already using the Plexus Container
 
-  [[1]] To learn the basics about Plexus components and the Plexus container, try the
-  {{{../quick-start/getting-started.html} Five Minute Tutorial}}.
+1. To learn the basics about Plexus components and the Plexus container, try the [ Five Minute Tutorial](../quick-start/getting-started.html).
 
-  [[2]] To learn more about writing components, take the {{{./writing-components/index.html} Component Tutorial}}.
+1. To learn more about writing components, take the [ Component Tutorial](./writing-components/index.html).
 
-  ~~TODO: finish
+<!-- TODO: finish -->
 
-* Container Trail
+## Container Trail
 
-  This trail is for those wishing to create an application that uses the Plexus container.
+This trail is for those wishing to create an application that uses the Plexus container.
 
-  [[1]] To get started using the Plexus container, try the {{{../quick-start/getting-started.html} Five Minute Tutorial}}.
-  
-  [[1]] To learn how to use Plexus for web application development, follow the {{{./plexus-web-applications/index.html}Plexus in Web applications}} trail.
+1. To get started using the Plexus container, try the [ Five Minute Tutorial](../quick-start/getting-started.html).
 
-  ~~TODO: finish
-
-
-
-
- 
+1. To learn how to use Plexus for web application development, follow the [Plexus in Web applications](./plexus-web-applications/index.html) trail.
 
+<!-- TODO: finish -->
diff --git a/src/site/markdown/guides/writing-components/00_index.md b/src/site/markdown/guides/writing-components/00_index.md
index e8b550f..423e0c2 100644
--- a/src/site/markdown/guides/writing-components/00_index.md
+++ b/src/site/markdown/guides/writing-components/00_index.md
@@ -1,56 +1,51 @@
- -----
-Plexus Sample Application Trail
- -----
-Rahul Thakur
- ----
-2006-06-08
- ------
+---
+title: Plexus Sample Application Trail
+author: Rahul Thakur
+date: 2006-06-08
+---
 
- <<<The contents of this document are a work in progress>>>
+`The contents of this document are a work in progress`
 
-About this trail
+# About this trail
 
- This trail shows how to get started with Plexus Component development. It starts off with a simple Plexus component and gradually evolves it to show different ways a component can be used.
-  
- * {{{./01_preparing_for_project.html}Prepping project: Website Monitor component}}
- 
- * {{{./02_diving_in.html}Diving in}}
- 
- * {{{./03_joys_of_tdd.html}Joys of TDD}} (Test Driven Development)
- 
- * {{{./04_more_bells_n_whistles.html}More bells & whistles}}
- 
- * {{{./05_configuring_to_get_it_right.html}Configuring to get it right!}}
+This trail shows how to get started with Plexus Component development. It starts off with a simple Plexus component and gradually evolves it to show different ways a component can be used.
 
- * {{{./06_we_have_a_component.html}Voila! We have a Component}}
- 
- * Component Usage Scenarios
- 
-  * {{{./07_01_from_a_maven_mojo.html}From a Maven Mojo}}
+- [Prepping project: Website Monitor component](./01_preparing_for_project.html)
 
-    * {{{./07_01_implementing_monitor_mojo.html} Implementing Monitor Mojo}}
+- [Diving in](./02_diving_in.html)
 
-    * {{{./07_01_configuring_monitor_mojo.html} Adding configuration for the Mojo}}
+- [Joys of TDD](./03_joys_of_tdd.html) (Test Driven Development)
 
-    * {{{./07_01_setting_up_mojo_unit_tests.html} Setting up Mojo unit tests}}
+- [More bells & whistles](./04_more_bells_n_whistles.html)
 
-  * {{{./07_02_from_a_plexus_application.html} From a Plexus application}}
+- [Configuring to get it right!](./05_configuring_to_get_it_right.html)
 
-    * {{{./07_02_plexus_embedder_and_component_integration.html} Plexus Embedder Intro & Site Monitor component integration into the application }} 
+- [Voila! We have a Component](./06_we_have_a_component.html)
 
-    
-  * {{{./07_03_from_a_web_application.html}From a Web application}}
+- Component Usage Scenarios
 
-    *  {{{./07_03_setting_up_a_web_application.html} Setting up a Web Application Project }} 
-    
-  * {{{./07_04_from_a_soap_webservice.html}From a SOAP Web Service}}
-    
-  * {{{./07_05_from_an_xmlrpc_service.html}From an XMLRPC Service}}
-    
- * {{{./08_packaging_up.html}Packaging}}
+- [From a Maven Mojo](./07_01_from_a_maven_mojo.html)
 
- * Other Resources
+- [ Implementing Monitor Mojo](./07_01_implementing_monitor_mojo.html)
 
-  []
+- [ Adding configuration for the Mojo](./07_01_configuring_monitor_mojo.html)
 
- You can also refer to the {{{/guides/developer-guide/index.html}Plexus Developer's Guide}} if you are interested in an in-depth understanding of Plexus internals and workings.
+- [ Setting up Mojo unit tests](./07_01_setting_up_mojo_unit_tests.html)
+
+- [ From a Plexus application](./07_02_from_a_plexus_application.html)
+
+- [ Plexus Embedder Intro & Site Monitor component integration into the application ](./07_02_plexus_embedder_and_component_integration.html)
+
+- [From a Web application](./07_03_from_a_web_application.html)
+
+- [ Setting up a Web Application Project ](./07_03_setting_up_a_web_application.html)
+
+- [From a SOAP Web Service](./07_04_from_a_soap_webservice.html)
+
+- [From an XMLRPC Service](./07_05_from_an_xmlrpc_service.html)
+
+- [Packaging](./08_packaging_up.html)
+
+- Other Resources
+
+You can also refer to the [Plexus Developer's Guide](/guides/developer-guide/index.html) if you are interested in an in-depth understanding of Plexus internals and workings.
diff --git a/src/site/markdown/guides/writing-components/01_preparing_for_project.md b/src/site/markdown/guides/writing-components/01_preparing_for_project.md
index 35b3a6b..a4fd1d3 100644
--- a/src/site/markdown/guides/writing-components/01_preparing_for_project.md
+++ b/src/site/markdown/guides/writing-components/01_preparing_for_project.md
@@ -1,102 +1,83 @@
- -----
-Chapter 1 : Preparing for first Plexus Project
- -----
-Rahul Thakur
- -----
-2006-06-08
- -----
+---
+title: Chapter 1 : Preparing for first Plexus Project
+author: Rahul Thakur
+date: 2006-06-08
+---
 
- <<<The contents of this document are a work in progress>>>
+`The contents of this document are a work in progress`
 
-Overview
+# Overview
 
- The chapter gets you to jump start into Plexus Component development. While a scan through of 'Concepts' would be helpful, it is not really required.
+The chapter gets you to jump start into Plexus Component development. While a scan through of 'Concepts' would be helpful, it is not really required.
 
- Where ever deemed neccessary cross-references are provided to make it easy for a new developer to reference the required material.
+Where ever deemed neccessary cross-references are provided to make it easy for a new developer to reference the required material.
 
-Pre-requisites
+# Pre-requisites
 
- The tutorial assumes you have Maven 2.0.x+ setup and have an internet connection and are able to download required Maven artifacts from online repositories.
+The tutorial assumes you have Maven 2.0.x\+ setup and have an internet connection and are able to download required Maven artifacts from online repositories.
 
- For the purpose of this tutorial we will develop a Plexus Website Monitor component.
+For the purpose of this tutorial we will develop a Plexus Website Monitor component.
 
- Lets get started!
- 
-* Create that skeleton!
+Lets get started!
 
- Plexus has some archetypes available that can make initial project setups a breeze. We use one such archetype for our Plexus component here.
-From the command prompt, change directory to the location where you wish to set up the new Plexus Component project.
-Run the following command from the command line to setup an initial project structure
+## Create that skeleton!
 
-+------------------------------------------+
+Plexus has some archetypes available that can make initial project setups a breeze. We use one such archetype for our Plexus component here. From the command prompt, change directory to the location where you wish to set up the new Plexus Component project. Run the following command from the command line to setup an initial project structure
+
+```
 
  mvn archetype:create -DarchetypeGroupId=org.codehaus.plexus -DarchetypeArtifactId=plexus-archetype-component-simple -DarchetypeVersion=1.0-alpha-1-SNAPSHOT -DgroupId=org.codehaus.plexus -DartifactId=plexus-website-monitor-component  -DpackageName=org.codehaus.plexus.tutorial -Dpackaging=jar -DremoteRepositories=http://snapshots.repository.codehaus.org/
 
-+------------------------------------------+
-
- Cool! At this point you've created a basic project structure that should give you a jump-start into development.
-
-** Archetype creation options explained
-
- More info on archetype creation and usage can be found  {{{http://maven.apache.org/guides/getting-started/index.html}here}} on the Maven website.
-
- The following table explains the options that we used above.
-
-*----------+--------------+----------------:
-| <<Commandline Option>>	| <<Description>> 	| <<Required>> |
-*----------+--------------+----------------:
-| -DarchetypeGroupId 	| "groupId" for the archetype we want to use 	| Yes |
-*----------+--------------+----------------:
-| -DarchetypeArtifact 	| "artifactId" for the archetype we want to use |	Yes |
-*----------+--------------+----------------:
-| -DarchetypeVersion 	| "version" for the archetype we want to use 	| Yes| 
-*----------+--------------+----------------:
-| -DgroupId 	| "groupId" for the project to be generated 	| Yes |
-*----------+--------------+----------------:
-| -DartifactId | "artifactId" for the project to be generated |	Yes |
-*----------+--------------+----------------:
-| -DpackageName |	Base package name to be use for any Java sources being copied over 	| No|
-*----------+--------------+----------------:
-| -Dpackaging |	Packaging to be used for the created project | No|
-*----------+--------------+----------------:
-| -DremoteRepositories | Comma-separated list of repositories to lookup to retrieve archetype | No|
-*----------+--------------+----------------:
- 
-*Generate a Project for your IDE.
-
-** For Eclipse.
- 
-   [[1]] Change directory to the newly created directory 'plexus-website-monitor-component'
-   
-   [[1]] Open up pom.xml and review the handful of dependencies setup there for version changes.
-
-  *As of this writing Plexus Snapshots were not being published to the Codehaus snapshots repository. Hopefully this should get resolved quickly.
-  
-   [[1]] Run the following command from command prompt to generate Eclipse project setting files.
-
-+------------------------------------------+
- E:\workspaces\plexus-docs\plexus-website-monitor-component>mvn eclipse:eclipse
-+------------------------------------------+
+```
+
+Cool! At this point you've created a basic project structure that should give you a jump-start into development.
+
+### Archetype creation options explained
+
+More info on archetype creation and usage can be found [here](http://maven.apache.org/guides/getting-started/index.html) on the Maven website.
+
+The following table explains the options that we used above.
 
- Eclipse project files should get generated succesfully at this point. If there were any unsatisfied dependencies (due to 2-1-3), update <version> for dependencies in pom.xml to an available release version.
- 
-   [[1]] Fire up Eclipse and import the generated project into an Eclipse Workspace.
- 
+|**Commandline Option**|**Description**|**Required**|
+|---|---|---|
+|-DarchetypeGroupId|"groupId" for the archetype we want to use|Yes|
+|-DarchetypeArtifact|"artifactId" for the archetype we want to use|Yes|
+|-DarchetypeVersion|"version" for the archetype we want to use|Yes|
+|-DgroupId|"groupId" for the project to be generated|Yes|
+|-DartifactId|"artifactId" for the project to be generated|Yes|
+|-DpackageName|Base package name to be use for any Java sources being copied over|No|
+|-Dpackaging|Packaging to be used for the created project|No|
+|-DremoteRepositories|Comma-separated list of repositories to lookup to retrieve archetype|No|
 
- Now, let's quickly recap the resources we see in our Eclipse project.
+## Generate a Project for your IDE.
 
- Eclipse Package Explorer View of  our import Plexus Component project.
+### For Eclipse.
+
+1. Change directory to the newly created directory 'plexus-website-monitor-component'
+
+1. Open up pom.xml and review the handful of dependencies setup there for version changes.
+
+- As of this writing Plexus Snapshots were not being published to the Codehaus snapshots repository. Hopefully this should get resolved quickly.
+
+1. Run the following command from command prompt to generate Eclipse project setting files.
+
+```
+ E:\workspaces\plexus-docs\plexus-website-monitor-component>mvn eclipse:eclipse
+```
 
- ~~TODO: Include Package Explorer image here
+Eclipse project files should get generated succesfully at this point. If there were any unsatisfied dependencies (due to 2-1-3), update _version_ for dependencies in pom.xml to an available release version.
 
- That concludes the preparation for our component project, we are all set to get our hands dirty with our first Plexus component.
+1. Fire up Eclipse and import the generated project into an Eclipse Workspace.
 
+Now, let's quickly recap the resources we see in our Eclipse project.
 
+Eclipse Package Explorer View of our import Plexus Component project.
 
- If you have a developer's itch and want to see if there is something we can do with the minimal project setup by the archetype for us - well, good news! Navigate your way through to the "HelloWorldTest" class (selected in the image above). Right click on it and choose "Run As  >  JUnit Test" and see for yourself. eeeks.....our unit test failed!! But fear not, for we come back to Component testing in a later chapter, so stay put!
+<!-- TODO: Include Package Explorer image here -->
+That concludes the preparation for our component project, we are all set to get our hands dirty with our first Plexus component.
 
- The project resources that we setup so far can be downloaded from this link here:
+If you have a developer's itch and want to see if there is something we can do with the minimal project setup by the archetype for us - well, good news! Navigate your way through to the "HelloWorldTest" class (selected in the image above). Right click on it and choose "Run As \> JUnit Test" and see for yourself. eeeks.....our unit test failed!! But fear not, for we come back to Component testing in a later chapter, so stay put!
 
- 
- ~~TODO: Link this Basic Eclipse project for Website Monitor
+The project resources that we setup so far can be downloaded from this link here:
 
+<!-- TODO: Link this Basic Eclipse project for Website Monitor -->
diff --git a/src/site/markdown/guides/writing-components/02_diving_in.md b/src/site/markdown/guides/writing-components/02_diving_in.md
index 5a17fb1..9381264 100644
--- a/src/site/markdown/guides/writing-components/02_diving_in.md
+++ b/src/site/markdown/guides/writing-components/02_diving_in.md
@@ -1,38 +1,34 @@
- -----
-Writing your first Plexus Component
- -----
-Rahul Thakur
- ----
-2006-06-11
- ------
+---
+title: Writing your first Plexus Component
+author: Rahul Thakur
+date: 2006-06-11
+---
 
- <<<The contents of this document are a work in progress>>>
+`The contents of this document are a work in progress`
 
-Creating a Component 'Role'
+# Creating a Component 'Role'
 
- If you browse through the sources generated by the Plexus component archetype used for preparing and setting up our project, you will see that we have:
+If you browse through the sources generated by the Plexus component archetype used for preparing and setting up our project, you will see that we have:
 
- [[1]]  an Interface "HelloWorld.java" , and
- 
- [[2]]  a Class "DefaultHelloWorld.java" which implements the interface in (1) above.
- 
- [[3]]  a Component Descriptor "components.xml" located under <project-root>/src/main/resources/META-INF/
- 
+1. an Interface "HelloWorld.java" , and
 
- Components are registered with Plexus Container based on "ROLE" they can play or implement. If you look at the interface sources you will notice the ROLE specified by that interface. The class DefaultHelloWorld is the provider or concrete implementation of the interface HelloWorld. It can reside within the same JAR as the inteface or a different one. Think of ROLE as a key that can be used to query the Plexus Container for an implementation. The component descriptor, as the name implies, describes our component. We will revisit it again in later chapters but for the moment, know that the descriptor holds:
+1. a Class "DefaultHelloWorld.java" which implements the interface in (1) above.
 
- [[1]]  the ROLE that the component implements or acts a provider for.
+1. a Component Descriptor "components.xml" located under _project-root_/src/main/resources/META-INF/
 
- [[2]]  the configuration for the component implementation.
+Components are registered with Plexus Container based on "ROLE" they can play or implement. If you look at the interface sources you will notice the ROLE specified by that interface. The class DefaultHelloWorld is the provider or concrete implementation of the interface HelloWorld. It can reside within the same JAR as the inteface or a different one. Think of ROLE as a key that can be used to query the Plexus Container for an implementation. The component descriptor, as the name implies, describes our component. We will revisit it again in later chapters but for the moment, know that the descriptor holds:
 
- When Plexus Container starts up, it uses Classworlds (the library that handles the classloading) to discover any Plexus components. It does this by looking for component descriptors ({{{/guides/developer-guide/configuration/component-descriptor.html}More on Component Descriptor here }}) under standard location - META-INF/plexus.
+1. the ROLE that the component implements or acts a provider for.
 
- That's enough to start tinkering with your website monitor component, so let's get our hands dirty!
-Identify a Component Role
+1. the configuration for the component implementation.
 
- Delete the .java files from the sources (under src/main and src/test ) that were generated by the archetype. The first thing we need to do is to identify a ROLE for our component - WebsiteMonitor.
+When Plexus Container starts up, it uses Classworlds (the library that handles the classloading) to discover any Plexus components. It does this by looking for component descriptors ([More on Component Descriptor here ](/guides/developer-guide/configuration/component-descriptor.html)) under standard location - META-INF/plexus.
 
-+------------------------------------------+
+That's enough to start tinkering with your website monitor component, so let's get our hands dirty! Identify a Component Role
+
+Delete the .java files from the sources (under src/main and src/test ) that were generated by the archetype. The first thing we need to do is to identify a ROLE for our component - WebsiteMonitor.
+
+```
 public interface WebsiteMonitor {
 
     /**
@@ -40,7 +36,6 @@ public interface WebsiteMonitor {
      */
     String ROLE = WebsiteMonitor.class.getName ();
 
-
     /**
      * Monitor the specified website.
      *
@@ -51,13 +46,13 @@ public interface WebsiteMonitor {
      */
     public void monitor(String website) throws Exception;
 }
-+------------------------------------------+
+```
 
-Create provider for the Role
+# Create provider for the Role
 
- Lets create a bare-bones implementation of a provider for the component Role that we identified above and gradually flesh it out.
+Lets create a bare-bones implementation of a provider for the component Role that we identified above and gradually flesh it out.
 
-+------------------------------------------+
+```
 public class DefaultWebsiteMonitor implements WebsiteMonitor {
 
     /*
@@ -71,13 +66,13 @@ public class DefaultWebsiteMonitor implements WebsiteMonitor {
     }
 
 }
-+------------------------------------------+
+```
 
-Create a Component descriptor
+# Create a Component descriptor
 
- Locate the component descriptor for our component provider under <project-root>/src/main/resources/META-INF/plexus/component.xml. Edit its content to reflect as below:
+Locate the component descriptor for our component provider under _project-root_/src/main/resources/META-INF/plexus/component.xml. Edit its content to reflect as below:
 
-+------------------------------------------+
+```
 <component-set>
   <components>
     <component>
@@ -89,12 +84,11 @@ Create a Component descriptor
     </component>
   </components>
 </component-set>
-+------------------------------------------+
-
+```
 
- Before we implement the the provider, we need to update our project dependencies and include Jakarta Commons HttpClient library. To do this, locate pom.xml under <project-root> and edit it to reflect the <dependencies> section of our pom.xml as below:
+Before we implement the the provider, we need to update our project dependencies and include Jakarta Commons HttpClient library. To do this, locate pom.xml under _project-root_ and edit it to reflect the _dependencies_ section of our pom.xml as below:
 
-+------------------------------------------+
+```
 <dependencies>
     <dependency>
       <groupId>org.codehaus.plexus</groupId>
@@ -113,24 +107,20 @@ Create a Component descriptor
       <version>3.0.1</version>
     </dependency>
   </dependencies>
-+------------------------------------------+
+```
 
+Update Eclipse project dependencies for new library that we added above, to do this:
 
- Update Eclipse project dependencies for new library that we added above, to do this:  
-
-  [[1]] Open up a command prompt window
-  
-  [[2]] Change directory to the Website Monitor project's folder, and
-  
-  [[3]] Run the following command to update the Eclipse project dependencies.       
-   
-+------------------------------------------+
-mvn  eclipse:clean  eclipse:eclipse
-+------------------------------------------+
+1. Open up a command prompt window
 
+1. Change directory to the Website Monitor project's folder, and
 
- Refresh the Eclipse project in the workspace to reflect the updated dependencies.
+1. Run the following command to update the Eclipse project dependencies.
 
- We are now ready to start writing some unit tests for our (yet empty) component and drilling some useful implementation details into it!
+```
+mvn  eclipse:clean  eclipse:eclipse
+```
 
+Refresh the Eclipse project in the workspace to reflect the updated dependencies.
 
+We are now ready to start writing some unit tests for our (yet empty) component and drilling some useful implementation details into it!
diff --git a/src/site/markdown/guides/writing-components/03_joys_of_tdd.md b/src/site/markdown/guides/writing-components/03_joys_of_tdd.md
index 146521e..d23aafe 100644
--- a/src/site/markdown/guides/writing-components/03_joys_of_tdd.md
+++ b/src/site/markdown/guides/writing-components/03_joys_of_tdd.md
@@ -1,22 +1,20 @@
- -----
-Writing tests for a Plexus Component
- -----
-Rahul Thakur
- ----
-2006-06-11
- ------
+---
+title: Writing tests for a Plexus Component
+author: Rahul Thakur
+date: 2006-06-11
+---
 
- <<<The contents of this document are a work in progress>>>
+`The contents of this document are a work in progress`
 
-Testing our Plexus Component
+# Testing our Plexus Component
 
- We create a basic unit test for our component. We do this by extending the PlexusTestCase class rather than the JUnit TestCase. PlexusTestCase sets up a Plexus Container intance for us to allow our component to be executed as it would when its deployed.
+We create a basic unit test for our component. We do this by extending the PlexusTestCase class rather than the JUnit TestCase. PlexusTestCase sets up a Plexus Container intance for us to allow our component to be executed as it would when its deployed.
 
- Note that if we override the setUp () and tearDown()  methods to add some custom set up or clean up bits to our test case, then we need to ensure that super.XXX() is called (where XXX is the method being overridden).  Othewise we will need to take care of Plexus container instance setup and clean ups ourselves.
+Note that if we override the setUp () and tearDown() methods to add some custom set up or clean up bits to our test case, then we need to ensure that super.XXX() is called (where XXX is the method being overridden). Othewise we will need to take care of Plexus container instance setup and clean ups ourselves.
 
- Here is a rudimentary test case for your component.  
+Here is a rudimentary test case for your component.
 
-+------------------------------------------+
+```
 package org.codehaus.plexus.tutorial;
 
 import java.net.UnknownHostException;
@@ -37,7 +35,6 @@ public class WebsiteMonitorTest extends PlexusTestCase {
         super.setUp ();
     }
 
-
     /**
      * Test if we are able to lookup and obtain our component instance from the
      * container.
@@ -49,7 +46,6 @@ public class WebsiteMonitorTest extends PlexusTestCase {
         assertNotNull (component);
     }
 
-
     /**
      * Test an unkown host.
      *
@@ -68,7 +64,6 @@ public class WebsiteMonitorTest extends PlexusTestCase {
         assertEquals (true, (e instanceof UnknownHostException));
     }
 
-
     /**
      * Test a page that does not exists.
      *
@@ -87,12 +82,11 @@ public class WebsiteMonitorTest extends PlexusTestCase {
     }
 
 }
-+------------------------------------------+
+```
 
+Time to take our unit test for a spin! Right click on the test case class in the Package Explorer view in Eclipse and choose to "Run As \> JUnit Test" - our test case fails as expected. Lets start stubbing in some implementation into the component and fixing the situation. The monitor(String website) is implemented as below to check the status of the provided website URL.
 
- Time to take our unit test for a spin! Right click on the test case class in the Package Explorer view in Eclipse and choose to "Run As > JUnit Test" - our test case fails as expected. Lets start stubbing in some implementation into the component and fixing the situation. The monitor(String website) is implemented as below to check the status of the provided website URL.
- 
-+------------------------------------------+
+```
 public class DefaultWebsiteMonitor implements WebsiteMonitor {
 
     /*
@@ -121,7 +115,4 @@ public class DefaultWebsiteMonitor implements WebsiteMonitor {
     }
 
 }
-+------------------------------------------+
-
-
-
+```
diff --git a/src/site/markdown/guides/writing-components/04_more_bells_n_whistles.md b/src/site/markdown/guides/writing-components/04_more_bells_n_whistles.md
index 30808a6..eaa8b1e 100644
--- a/src/site/markdown/guides/writing-components/04_more_bells_n_whistles.md
+++ b/src/site/markdown/guides/writing-components/04_more_bells_n_whistles.md
@@ -1,18 +1,16 @@
- -----
-More fun with Plexus Components
- -----
-Rahul Thakur
- ----
-2006-06-11
- ------
+---
+title: More fun with Plexus Components
+author: Rahul Thakur
+date: 2006-06-11
+---
 
- <<<The contents of this document are a work in progress>>>
+`The contents of this document are a work in progress`
 
-Control those 'evil' System.out's!
+# Control those 'evil' System.out's!
 
- We tweak our component implementation a bit to allow more control over messages being logged the console. To to this we update DefaultWebsiteMonitor to extend from org.codehaus.plexus.logging.AbstractLogEnabled. System.outs are then replaced by call to getLogger() to obtain the org.codehaus.plexus.logging.Logger instance setup by the container for us. The resulting code looks like this:
+We tweak our component implementation a bit to allow more control over messages being logged the console. To to this we update DefaultWebsiteMonitor to extend from org.codehaus.plexus.logging.AbstractLogEnabled. System.outs are then replaced by call to getLogger() to obtain the org.codehaus.plexus.logging.Logger instance setup by the container for us. The resulting code looks like this:
 
-+------------------------------------------+
+```
 public class DefaultWebsiteMonitor extends AbstractLogEnabled implements WebsiteMonitor {
 
     /*
@@ -43,11 +41,8 @@ public class DefaultWebsiteMonitor extends AbstractLogEnabled implements Website
     }
 
 }
-+------------------------------------------+
-
-
-Plugging in our custom Logging implementation
-
- An example of plugging in a custom logging implementation is demonstrated {{{./05_01_custom_logging_implementation.html} here}}.
+```
 
+# Plugging in our custom Logging implementation
 
+An example of plugging in a custom logging implementation is demonstrated [ here](./05_01_custom_logging_implementation.html).
diff --git a/src/site/markdown/guides/writing-components/05_01_custom_logging_implementation.md b/src/site/markdown/guides/writing-components/05_01_custom_logging_implementation.md
index 2744402..3bdb69a 100644
--- a/src/site/markdown/guides/writing-components/05_01_custom_logging_implementation.md
+++ b/src/site/markdown/guides/writing-components/05_01_custom_logging_implementation.md
@@ -1,48 +1,41 @@
- -----
-Overriding Plexus Logger Manager
- -----
-Rahul Thakur
- ----
-2006-06-11
- ------
- 
- 
-Using a custom LoggerManager
+---
+title: Overriding Plexus Logger Manager
+author: Rahul Thakur
+date: 2006-06-11
+---
 
- Say, we want to use Log4j logging for the log messages in our Website monitor component - how could we replace the default logging implementation?
+# Using a custom LoggerManager
 
- Before we demonstrate how logger can be swapped, some notes on how logging is setup up for a Plexus component
+Say, we want to use Log4j logging for the log messages in our Website monitor component - how could we replace the default logging implementation?
 
-    * Logging for a component is handled using a org.codehaus.plexus.logging.LoggerManager component.
-    
-    * LoggerManager makes a org.codehaus.plexus.logging.Logger instance available to the Plexus container. The LoggerManager can create (or obtain) as well as configure the Logger instance before making it available to the Plexus container.
-    
-    * Each component in Plexus runtime get its own Logger instance. 
-    
-    * LoggerManager is initialized on Plexus container startup. It is for this reason, the LoggerManager should be overridden via Plexus container's configuration.
+Before we demonstrate how logger can be swapped, some notes on how logging is setup up for a Plexus component
 
+- Logging for a component is handled using a org.codehaus.plexus.logging.LoggerManager component.
 
- From what we have coded up so far, we don't have Plexus container configuration available to us, nor is it desirable to run our component in a Plexus container without being fully tested. So here is what we do:
+- LoggerManager makes a org.codehaus.plexus.logging.Logger instance available to the Plexus container. The LoggerManager can create (or obtain) as well as configure the Logger instance before making it available to the Plexus container.
 
-   [[1]] Override the configuration used by PlexusTestCase to set up a Plexus Container instance.
-   
-   [[2]] Setup the Log4jLoggerManager in the overridden configuration.
+- Each component in Plexus runtime get its own Logger instance.
 
-   
+- LoggerManager is initialized on Plexus container startup. It is for this reason, the LoggerManager should be overridden via Plexus container's configuration.
 
- For step (1) above we update the WebMonitorTest and override the getCustomConfiguration() method from PlexusTestCase as follows:
+From what we have coded up so far, we don't have Plexus container configuration available to us, nor is it desirable to run our component in a Plexus container without being fully tested. So here is what we do:
 
-+------------------------------------------+
+1. Override the configuration used by PlexusTestCase to set up a Plexus Container instance.
+
+1. Setup the Log4jLoggerManager in the overridden configuration.
+
+For step (1) above we update the WebMonitorTest and override the getCustomConfiguration() method from PlexusTestCase as follows:
+
+```
 protected InputStream getCustomConfiguration() throws Exception {
         InputStream is = this.getClass ().getClassLoader ().getResourceAsStream ("org/codehaus/plexus/PlexusTestContainerConfig.xml");
         return is;
     }
-+------------------------------------------+
+```
 
+For step (2), create an XML configuration file under \<project-root\>/src/test/resources/org/codehaus/plexus/PlexusTestContainerConfig.xml, with following contents:
 
- For step (2), create an XML configuration file under \<project-root\>/src/test/resources/org/codehaus/plexus/PlexusTestContainerConfig.xml, with following contents:
-
-+------------------------------------------+
+```
 <!-- Override the configuration that is used by the PlexusTestCase to create a Container instance -->
 <plexus>
   <components>
@@ -84,5 +77,4 @@ protected InputStream getCustomConfiguration() throws Exception {
     </component>
   </components>
 </plexus>
-+------------------------------------------+
-
+```
diff --git a/src/site/markdown/guides/writing-components/05_configuring_to_get_it_right.md b/src/site/markdown/guides/writing-components/05_configuring_to_get_it_right.md
index 9b8a45c..86761df 100644
--- a/src/site/markdown/guides/writing-components/05_configuring_to_get_it_right.md
+++ b/src/site/markdown/guides/writing-components/05_configuring_to_get_it_right.md
@@ -1,20 +1,17 @@
- -----
-Configuring Plexus Components
- -----
-Rahul Thakur
- ----
-2006-06-11
- ------
+---
+title: Configuring Plexus Components
+author: Rahul Thakur
+date: 2006-06-11
+---
 
- <<<The contents of this document are a work in progress>>>
+`The contents of this document are a work in progress`
 
-Configuring a Plexus Component via descriptor
+# Configuring a Plexus Component via descriptor
 
- ~~TODO: Start by changing the interface and factoring 'website' out and moving it to be a property in the component injectable by the Container based on configuration.
+<!-- TODO: Start by changing the interface and factoring 'website' out and moving it to be a property in the component injectable by the Container based on configuration. -->
+We change the Component Role interface to look like this:
 
- We change the Component Role interface to look like this:
-
-+------------------------------------------+
+```
 public interface WebsiteMonitor
 {
 
@@ -46,12 +43,11 @@ public interface WebsiteMonitor
      */
     boolean isInitialized();
 }
-+------------------------------------------+
+```
 
+and, factor our component provider implementation to look like this:
 
- and, factor our component provider implementation to look like this:
- 
-+------------------------------------------+
+```
 public class DefaultWebsiteMonitor
     extends AbstractLogEnabled
     implements WebsiteMonitor
@@ -121,18 +117,16 @@ public class DefaultWebsiteMonitor
     }
 
 }
-+------------------------------------------+
-
+```
 
- Note how <<<'websites'>>> is now a java.util.List property rather than a argument to the method. Also notice the annotation @plexus.configuration that indicates that this property is a plexus configuration element. This annotation is processed by Plexus' Component Descriptor Creator (or CDC). The CDC can parse and generate a components.xml from Java sources.
+Note how `'websites'` is now a java.util.List property rather than a argument to the method. Also notice the annotation @plexus.configuration that indicates that this property is a plexus configuration element. This annotation is processed by Plexus' Component Descriptor Creator (or CDC). The CDC can parse and generate a components.xml from Java sources.
 
- Now that we made <<<'websites'>>> to be a configuration property, we need to update the component's descriptor and specify values for websites. We add a list of websites as shown the the snippet below. Plexus container ensures that a component's fields are mapped and initialized and mapped from a component's configuration file. It can intelligently discover and map configuration items of different types like String, Lists (in this case). You can also specify you own configuration implementation class by specifying an <<<'implementation'>>> attribute on <<<<configuration>>>> element. Plexus will then attempt to inject the values from the XML configuration into the Configuration implementation's properties. Each of the nested element maps to a configuration property in the implementation class.
-  
-  ~~TODO: Provide a link to page that discusses configuration mapping.
+Now that we made `'websites'` to be a configuration property, we need to update the component's descriptor and specify values for websites. We add a list of websites as shown the the snippet below. Plexus container ensures that a component's fields are mapped and initialized and mapped from a component's configuration file. It can intelligently discover and map configuration items of different types like String, Lists (in this case). You can also specify you own configuration implementation class by specifying an `'implementation'` attribute on `<configuration`\> element. Plexus will then attempt to inject the values from the XML configuration into the Configuration implementation's properties. Each of the nested element maps to a configuration property in the implementation class.
 
- This mandates a change in the descriptor, which now looks something like this:
+<!-- TODO: Provide a link to page that discusses configuration mapping. -->
+This mandates a change in the descriptor, which now looks something like this:
 
-+------------------------------------------+
+```
 <component-set>
   <components>
     <component>
@@ -150,10 +144,7 @@ public class DefaultWebsiteMonitor
     </component>
   </components>
 </component-set>
-+------------------------------------------+
-
-
- ~~TODO: May be add a time-interval configuration property such that the monitor can ping the specified site at regular intervals
-
- ~~TODO: add a MonitorResult to communicate the results of a Monitoring run back to the client.
+```
 
+<!-- TODO: May be add a time-interval configuration property such that the monitor can ping the specified site at regular intervals -->
+<!-- TODO: add a MonitorResult to communicate the results of a Monitoring run back to the client. -->
diff --git a/src/site/markdown/guides/writing-components/06_we_have_a_component.md b/src/site/markdown/guides/writing-components/06_we_have_a_component.md
index 3c29f26..6450d99 100644
--- a/src/site/markdown/guides/writing-components/06_we_have_a_component.md
+++ b/src/site/markdown/guides/writing-components/06_we_have_a_component.md
@@ -1,12 +1,9 @@
- -----
-A working component - finally!
- -----
-Rahul Thakur
- ----
-2006-06-08
- ------
+---
+title: A working component - finally!
+author: Rahul Thakur
+date: 2006-06-08
+---
 
- <<<The contents of this document are a work in progress>>>
+`The contents of this document are a work in progress`
 
-
-~~TODO:  
+<!-- TODO:   -->
diff --git a/src/site/markdown/guides/writing-components/07_01_configuring_monitor_mojo.md b/src/site/markdown/guides/writing-components/07_01_configuring_monitor_mojo.md
index 0b3b167..3a40f32 100644
--- a/src/site/markdown/guides/writing-components/07_01_configuring_monitor_mojo.md
+++ b/src/site/markdown/guides/writing-components/07_01_configuring_monitor_mojo.md
@@ -1,34 +1,28 @@
- -----
-Using a Plexus Component from a Maven Mojo.
- -----
-Rahul Thakur
- ----
-2006-06-27
- ------
+---
+title: Using a Plexus Component from a Maven Mojo.
+author: Rahul Thakur
+date: 2006-06-27
+---
 
- <<<The contents of this document are a work in progress>>>
+`The contents of this document are a work in progress`
 
-Adding Configuration for the Monitor Mojo
+# Adding Configuration for the Monitor Mojo
 
+## Configuring a 'short-hand' to invoke Monitor Mojo
 
-* Configuring a 'short-hand' to invoke Monitor Mojo
-  
-  By default Maven expects all Maven plugin artifacts:
-  
-  [[1]] to belong to the group <<<org.apache.maven.plugins>>>
+By default Maven expects all Maven plugin artifacts:
 
-  [[1]] to have the artifactId follow pattern <<<maven-xxxx-plugin>>>, 
-  where <<<xxxx>>> can serve as a short-hand prefix to invoke a Mojo 
-  from a Maven plugin.
+1. to belong to the group `org.apache.maven.plugins`
 
-    For our case we need to let Maven know that our plugin's <<<groupId>>> 
-  and <<<artifactId>>> are different from what Maven expects by default. 
+1. to have the artifactId follow pattern `maven-xxxx-plugin`, where `xxxx` can serve as a short-hand prefix to invoke a Mojo from a Maven plugin.
 
-  So we define for our Maven plugin a <<plugin prefix>> via our plugin's pom.xml.
+For our case we need to let Maven know that our plugin's `groupId` and `artifactId` are different from what Maven expects by default.
 
-  To do this, we add the following to our pom.xml under the <<<<project>>>> element.
+So we define for our Maven plugin a **plugin prefix** via our plugin's pom.xml.
 
-+---------------------------+
+To do this, we add the following to our pom.xml under the `<project`\> element.
+
+```
 <?xml version="1.0" encoding="UTF-8"?>
 <project>
   .
@@ -46,17 +40,15 @@ Adding Configuration for the Monitor Mojo
   </build>
 </project>  
 
-+---------------------------+
-  
-  This tells Maven to use <<website>> as a plugin prefix or a 'short-hand' to 
-  allow invoking available Mojo(s) from our plugin.
+```
+
+This tells Maven to use **website** as a plugin prefix or a 'short-hand' to allow invoking available Mojo(s) from our plugin.
 
-  [[1]] Next we add the <<<groupId>>> of our Maven plugin in Maven settings 
-  file. This is available under <<<~/.m2/settings.xml>>>.
+1. Next we add the `groupId` of our Maven plugin in Maven settings file. This is available under `~/.m2/settings.xml`.
 
-  [[1]] Edit it and add the following: 
+1. Edit it and add the following:
 
-+---------------------------+
+```
 <settings>
   .
   .
@@ -65,25 +57,20 @@ Adding Configuration for the Monitor Mojo
     <pluginGroup>org.codehaus.plexus</pluginGroup>
   </pluginGroups>
 </settings>
-+---------------------------+
+```
 
-  This should allow our Mojo to be invoked from the command prompt without have
-  the need to type fully qualified reference to MonitorMojo 
-  (org.codehaus.plexus:plexus-website-monitor-plugin:monitor), and by simply typing:
+This should allow our Mojo to be invoked from the command prompt without have the need to type fully qualified reference to MonitorMojo (org.codehaus.plexus:plexus-website-monitor-plugin:monitor), and by simply typing:
 
-+---------------------------+ 
+```
  mvn website:monitor
-+---------------------------+
-
-
-    A more definitive reference on plugin prefix resolution is available {{{http://maven.apache.org/guides/introduction/introduction-to-plugin-prefix-mapping.html}here}} on the Maven website.
+```
 
-* Configuring list of websites
+A more definitive reference on plugin prefix resolution is available [here](http://maven.apache.org/guides/introduction/introduction-to-plugin-prefix-mapping.html) on the Maven website.
 
-  ~~Now we see how to set up a configuration for the MonitorMojo and use it to 
-  ~~convey to the website monitor component the list of websites to monitor.
+## Configuring list of websites
 
-  We will come back to configuring the MonitorMojo but before we do that we'll
-  look at setting up unit tests for it.
+<!-- Now we see how to set up a configuration for the MonitorMojo and use it to  -->
+<!-- convey to the website monitor component the list of websites to monitor. -->
+We will come back to configuring the MonitorMojo but before we do that we'll look at setting up unit tests for it.
 
- {{{./07_01_setting_up_mojo_unit_tests.html}Next: Setting up Mojo unit tests}}
+[Next: Setting up Mojo unit tests](./07_01_setting_up_mojo_unit_tests.html)
diff --git a/src/site/markdown/guides/writing-components/07_01_from_a_maven_mojo.md b/src/site/markdown/guides/writing-components/07_01_from_a_maven_mojo.md
index 6f7c828..328ec1c 100644
--- a/src/site/markdown/guides/writing-components/07_01_from_a_maven_mojo.md
+++ b/src/site/markdown/guides/writing-components/07_01_from_a_maven_mojo.md
@@ -1,47 +1,41 @@
- -----
-Using a Plexus Component from a Maven Mojo.
- -----
-Rahul Thakur
- ----
-2006-06-08
- ------
+---
+title: Using a Plexus Component from a Maven Mojo.
+author: Rahul Thakur
+date: 2006-06-08
+---
 
-Website Monitor Plugin 
+# Website Monitor Plugin
 
- This section will show how to use a Plexus component from within a Maven mojo.
+This section will show how to use a Plexus component from within a Maven mojo.
 
-* Setting up a Maven Plugin Project
+## Setting up a Maven Plugin Project
 
-** Creating a Maven plugin Project using an archetype
+### Creating a Maven plugin Project using an archetype
 
-  Maven Archetypes are discussed in detail {{{http://maven.apache.org/guides/mini/guide-creating-archetypes.html}here}}.
+Maven Archetypes are discussed in detail [here](http://maven.apache.org/guides/mini/guide-creating-archetypes.html).
 
-  [[1]] From the command prompt, change directory to the location where you 
-  want to setup the maven plugin project.
+1. From the command prompt, change directory to the location where you want to setup the maven plugin project.
 
-  [[1]] Run the following command to set up a skeleton Maven Plugin project.  
+1. Run the following command to set up a skeleton Maven Plugin project.
 
-+------------------------------------------+
+```
 
  mvn archetype:create -DarchetypeGroupId=org.apache.maven.archetypes -DarchetypeArtifactId=maven-archetype-mojo \
      -DarchetypeVersion=1.0-SNAPSHOT -DgroupId=org.codehaus.plexus -DartifactId=plexus-website-monitor-plugin
 
-+------------------------------------------+
+```
 
- The <<<maven-archetype-mojo>>> sets up a skeleton Maven plugin project '<<<plexus-website-monitor-plugin>>>' for 
- us with reasonable defaults.
+The `maven-archetype-mojo` sets up a skeleton Maven plugin project '`plexus-website-monitor-plugin`' for us with reasonable defaults.
 
- 
-** Updating pom.xml dependencies
+### Updating pom.xml dependencies
 
-  [[1]] Locate pom.xml under the '<<<plexus-website-monitor-plugin>>>' folder. 
+1. Locate pom.xml under the '`plexus-website-monitor-plugin`' folder.
 
-  [[1]] Edit it and add a <<<dependency>>> to the 
-  plexus-website-monitor-component that we have developed in earlier chapters.
+1. Edit it and add a `dependency` to the plexus-website-monitor-component that we have developed in earlier chapters.
 
-    The pom.xml should look like this now:
+The pom.xml should look like this now:
 
-+------------------------------------------+
+```
 <?xml version="1.0"?>
 <project>
   <modelVersion>4.0.0</modelVersion>
@@ -70,24 +64,20 @@ Website Monitor Plugin
     </dependency>
   </dependencies>
 </project>
-+------------------------------------------+
+```
 
+### Setting up an Eclipse project
 
-** Setting up an Eclipse project 
+Note that this step assumes that we have Plexus Website Monitor Component available in our local repository or downloadable from a remote repository.
 
-  Note that this step assumes that we have Plexus Website Monitor Component 
-  available in our local repository or downloadable from a remote repository.
-  
-  [[1]] Run the following command to generate Eclipse project and set up library path to dependencies.
+1. Run the following command to generate Eclipse project and set up library path to dependencies.
 
-+------------------------------------------+
+```
  mvn eclipse:eclipse
-+------------------------------------------+
+```
 
-  [[1]] From the Eclipse workbench, use 'File > Import > Existing projects into workspace' 
-  to import the created maven plugin project. 
+1. From the Eclipse workbench, use 'File \> Import \> Existing projects into workspace' to import the created maven plugin project.
 
-    The website monitor plugin should now be set up as a project under Eclipse.
+The website monitor plugin should now be set up as a project under Eclipse.
 
-
- {{{./07_01_implementing_monitor_mojo.html}Next: Implementing Monitor Mojo}}
+[Next: Implementing Monitor Mojo](./07_01_implementing_monitor_mojo.html)
diff --git a/src/site/markdown/guides/writing-components/07_01_implementing_monitor_mojo.md b/src/site/markdown/guides/writing-components/07_01_implementing_monitor_mojo.md
index fb1ba54..14a12a2 100644
--- a/src/site/markdown/guides/writing-components/07_01_implementing_monitor_mojo.md
+++ b/src/site/markdown/guides/writing-components/07_01_implementing_monitor_mojo.md
@@ -1,34 +1,28 @@
- -----
-Using a Plexus Component from a Maven Mojo.
- -----
-Rahul Thakur
- ----
-2006-06-27
- ------
+---
+title: Using a Plexus Component from a Maven Mojo.
+author: Rahul Thakur
+date: 2006-06-27
+---
 
- <<<The contents of this document are a work in progress>>>
+`The contents of this document are a work in progress`
 
-Implementing the Monitor Mojo
+# Implementing the Monitor Mojo
 
-  If you would like to understand what a Maven Mojo is, please refer to the 
-  documentation {{{http://maven.apache.org/guides/plugin/guide-java-plugin-development.html}here}} 
-  on the Maven website.
+If you would like to understand what a Maven Mojo is, please refer to the documentation [here](http://maven.apache.org/guides/plugin/guide-java-plugin-development.html) on the Maven website.
 
-* Monitor Mojo
+## Monitor Mojo
 
-  We noticed that the archetype creator filled in the maven plugin project with
-  some reasonable defaults. It also created a <<<MyMojo>>> placeholder 
-  implementation of a Mojo for us, but it doesn't do much for us.
+We noticed that the archetype creator filled in the maven plugin project with some reasonable defaults. It also created a `MyMojo` placeholder implementation of a Mojo for us, but it doesn't do much for us.
 
-  So, 
+So,
 
-  [[1]] Delete <<<MyMojo>>> implementation from the project sources.
+1. Delete `MyMojo` implementation from the project sources.
 
-  [[1]] Create a <<<MonitorMojo>>> that extends <<<org.apache.maven.plugin.AbstractMojo>>>.
+1. Create a `MonitorMojo` that extends `org.apache.maven.plugin.AbstractMojo`.
 
-    The Mojo source should like this: 
+The Mojo source should like this:
 
-+-----------------------------------+
+```
 
 public class MonitorMojo
     extends AbstractMojo
@@ -43,12 +37,11 @@ public class MonitorMojo
 
 }
 
-+-----------------------------------+
+```
 
-  [[1]] Add a Javadoc <<<@goal>>> annotation in Javadoc comments for a Class to
-  bind a goal name that runs this Mojo. 
+1. Add a Javadoc `@goal` annotation in Javadoc comments for a Class to bind a goal name that runs this Mojo.
 
-+-----------------------------------+
+```
 
 /**
  * A Mojo that monitors a given list of websites.
@@ -69,17 +62,15 @@ public class MonitorMojo
 
 }
 
-+-----------------------------------+
+```
 
-* Wiring the Website Monitor Component
+## Wiring the Website Monitor Component
 
-  [[1]] Declare a field of type <<<org.codehaus.plexus.tutorial.WebsiteMonitor>>> for <<<MonitorMojo>>>.
+1. Declare a field of type `org.codehaus.plexus.tutorial.WebsiteMonitor` for `MonitorMojo`.
 
-  [[1]] Add a Javadoc annotation <<<@component>>> on the field. This indicates 
-  to Plexus runtime to lookup and populate the field with an implementation 
-  with a Component ROLE = '<<<org.codehaus.plexus.tutorial.WebsiteMonitor>>>'
+1. Add a Javadoc annotation `@component` on the field. This indicates to Plexus runtime to lookup and populate the field with an implementation with a Component ROLE = '`org.codehaus.plexus.tutorial.WebsiteMonitor`'
 
-+-----------------------------------+
+```
 
 /**
  * A Mojo that monitors a given list of websites.
@@ -107,27 +98,17 @@ public class MonitorMojo
 
 }
 
-+-----------------------------------+
-  
+```
 
-  [[1]] (optional) We can get choosy if we know there are more than one 
-  implementations of <<<org.codehaus.plexus.tutorial.WebsiteMonitor>>> ROLE 
-  available. This can done by adding an attribute '<<<role-hint>>>' to the
-  Javadoc annotation that we added in the previous step.
+1. (optional) We can get choosy if we know there are more than one implementations of `org.codehaus.plexus.tutorial.WebsiteMonitor` ROLE available. This can done by adding an attribute '`role-hint`' to the Javadoc annotation that we added in the previous step.
 
-  Say, for instance we had a different website monitor implementation to 
-  monitor FTP websites, the Javadoc annotation for that Mojo field will look
-  like the snippet below. 
-  
-  Of course, the value of <<<role-hint>>> provided in the code snippet 
-  reproduced below should have been defined for the website monitor's 
-  implementation's component descriptor that monitors FTP sites.
+Say, for instance we had a different website monitor implementation to monitor FTP websites, the Javadoc annotation for that Mojo field will look like the snippet below.
 
-  Again the Plexus runtime does the magic of injecting the appropriate
-  implementation.
+Of course, the value of `role-hint` provided in the code snippet reproduced below should have been defined for the website monitor's implementation's component descriptor that monitors FTP sites.
 
+Again the Plexus runtime does the magic of injecting the appropriate implementation.
 
-+-----------------------------------+
+```
 
 /**
  * A Mojo that monitors a given list of websites.
@@ -155,8 +136,6 @@ public class MonitorMojo
 
 }
 
-+-----------------------------------+
-
-
- {{{./07_01_configuring_monitor_mojo.html}Next: Adding configuration for the Mojo}}
+```
 
+[Next: Adding configuration for the Mojo](./07_01_configuring_monitor_mojo.html)
diff --git a/src/site/markdown/guides/writing-components/07_01_setting_up_mojo_unit_tests.md b/src/site/markdown/guides/writing-components/07_01_setting_up_mojo_unit_tests.md
index 00a53cf..9584ce3 100644
--- a/src/site/markdown/guides/writing-components/07_01_setting_up_mojo_unit_tests.md
+++ b/src/site/markdown/guides/writing-components/07_01_setting_up_mojo_unit_tests.md
@@ -1,42 +1,32 @@
- -----
-Using a Plexus Component from a Maven Mojo.
- -----
-Rahul Thakur
- ----
-2006-06-27
- ------
+---
+title: Using a Plexus Component from a Maven Mojo.
+author: Rahul Thakur
+date: 2006-06-27
+---
 
- <<<The contents of this document are a work in progress>>>
+`The contents of this document are a work in progress`
 
-Setting up unit tests for Monitor Mojo 
+# Setting up unit tests for Monitor Mojo
 
- Unit testing allows us to test out our Mojo implmentation without requiring a
- project to be set up. 
+Unit testing allows us to test out our Mojo implmentation without requiring a project to be set up.
 
- Maven provides a <<Plugin Test Harness>> to enable testing of Mojos. 
+Maven provides a **Plugin Test Harness** to enable testing of Mojos.
 
- Some relatively comprehensive notes on the Maven Plugin Harness are available
- {{{http://docs.codehaus.org/display/MAVEN/Maven+Plugin+Harness}here}}.
+Some relatively comprehensive notes on the Maven Plugin Harness are available [here](http://docs.codehaus.org/display/MAVEN/Maven\+Plugin\+Harness).
 
-* Adding test sources directory to the project 
+## Adding test sources directory to the project
 
-  This step is needed as the Mojo Archetype (as of this writing) does not sets
-  up test folder when we created our Maven plugin project.
+This step is needed as the Mojo Archetype (as of this writing) does not sets up test folder when we created our Maven plugin project.
 
-  [[1]] To the project root add a directory <<<src/test/java>>>. We will create
-  our unit tests under this location. 
+1. To the project root add a directory `src/test/java`. We will create our unit tests under this location.
 
-  [[1]] To the project root add a director <<<src/test/resources>>>. This 
-  directory will hold resources that we use for Mojo testing.  
+1. To the project root add a director `src/test/resources`. This directory will hold resources that we use for Mojo testing.
 
+## Adding plugin test harness dependency
 
-* Adding plugin test harness dependency
+1. First thing we need to do is to add the Maven plugin test harness dependency to our Plugin's `pom.xml`. Locate the `pom.xml` and add the harness dependency as follows.
 
-  [[1]] First thing we need to do is to add the Maven plugin test harness 
-  dependency to our Plugin's <<<pom.xml>>>. Locate the <<<pom.xml>>> and add 
-  the harness dependency as follows.
-
-+----------------------------+  
+```
   <dependencies>
     .
     .
@@ -48,37 +38,27 @@ Setting up unit tests for Monitor Mojo
       <scope>test</scope>
     </dependency>
   </dependencies>
-+----------------------------+  
+```
 
-  [[1]] Next we need to update depdendency references in our Eclipse project 
-  settings to make the plugin testing harness available. To do this run the 
-  following from the command prompt from the plugin project's directory.
+1. Next we need to update depdendency references in our Eclipse project settings to make the plugin testing harness available. To do this run the following from the command prompt from the plugin project's directory.
 
-+----------------------------+
+```
  mvn eclipse:clean eclipse:eclipse
-+----------------------------+
+```
+
+1. Refresh the Eclipse project by selecting the project root folder and pressing 'F5' key.
 
-  [[1]] Refresh the Eclipse project by selecting the project root folder and 
-  pressing 'F5' key. 
+You will see that the plugin testing harness dependency and the test directory that we added in the previous step are now updated.
 
-  You will see that the plugin testing harness dependency and the test 
-  directory that we added in the previous step are now updated. 
+## Writing our Mojo unit tests
 
-* Writing our Mojo unit tests
-  
-  [[1]] Create a new package <<<org.codehaus.plexus>>> to create our test in.
-  Note that we create the package with the same name that our Mojo 
-  implementation resides in. This is a convenience to test out methods on Mojo
-  which may have access specifiers that allow access only from within same 
-  package.
-  
-  [[1]] We write a couple of tests to ensure that our Mojo instance is being 
-  retrieved as expected, and to test that it executes without errors for a 
-  valid list of websites.
+1. Create a new package `org.codehaus.plexus` to create our test in. Note that we create the package with the same name that our Mojo implementation resides in. This is a convenience to test out methods on Mojo which may have access specifiers that allow access only from within same package.
 
-  Our test source looks as follows: 
+1. We write a couple of tests to ensure that our Mojo instance is being retrieved as expected, and to test that it executes without errors for a valid list of websites.
 
-+----------------------------+
+Our test source looks as follows:
+
+```
 public class MonitorMojoTest
     extends AbstractMojoTestCase
 {
@@ -109,12 +89,11 @@ public class MonitorMojoTest
         }
     }
 }
-+----------------------------+
+```
 
-  [[1]] We set up a test configuration for the Mojo under <<<src/test/resources/unit/plugin-config.xml>>> 
-  (yes, that's the file that we refer to in the test above!).
+1. We set up a test configuration for the Mojo under `src/test/resources/unit/plugin-config.xml` (yes, that's the file that we refer to in the test above!).
 
-+----------------------------+
+```
 <project>
   <build>
     <plugins>
@@ -130,11 +109,11 @@ public class MonitorMojoTest
     </plugins>
   </build>
 </project>
-+----------------------------+  
+```
 
-  [[1]] Also our Mojo implementation is now updated to be as below:
+1. Also our Mojo implementation is now updated to be as below:
 
-+----------------------------+  
+```
 public class MonitorMojo
     extends AbstractMojo
 {
@@ -220,21 +199,16 @@ public class MonitorMojo
     }
 
 }
-+----------------------------+    
-  
-  [[1]] Let's run the test and see what happens. You can run the test from 
-  within your favourite IDE, or from command prompt by typing
+```
+
+1. Let's run the test and see what happens. You can run the test from within your favourite IDE, or from command prompt by typing
 
-+----------------------------+  
+```
  mvn clean test 
-+----------------------------+    
-  
-  At this point, the Mojo test should run without any failures. 
-  
-  
-    Great! You have just hooked your Plexus component successfully to a Maven 
-    plugin.
-    
-  For more information on developing and using Maven plugins, please refer to 
-  {{{http://maven.apache.org/guides/plugin/guide-java-plugin-development.html}Guide to Developing Java Plugins}}
-    
+```
+
+At this point, the Mojo test should run without any failures.
+
+Great! You have just hooked your Plexus component successfully to a Maven plugin.
+
+For more information on developing and using Maven plugins, please refer to [Guide to Developing Java Plugins](http://maven.apache.org/guides/plugin/guide-java-plugin-development.html)
diff --git a/src/site/markdown/guides/writing-components/07_02_from_a_plexus_application.md b/src/site/markdown/guides/writing-components/07_02_from_a_plexus_application.md
index f444f21..0525bfb 100644
--- a/src/site/markdown/guides/writing-components/07_02_from_a_plexus_application.md
+++ b/src/site/markdown/guides/writing-components/07_02_from_a_plexus_application.md
@@ -1,53 +1,46 @@
- -----
-Using a Plexus Component from a Plexus application.
- -----
-Rahul Thakur
- ----
-2006-06-08
- ------
+---
+title: Using a Plexus Component from a Plexus application.
+author: Rahul Thakur
+date: 2006-06-08
+---
 
- <<<The contents of this document are a work in progress>>>
+`The contents of this document are a work in progress`
 
-Plexus Website Monitor Application
+# Plexus Website Monitor Application
 
- This section will show how to use a Plexus component in a Plexus application.
+This section will show how to use a Plexus component in a Plexus application.
 
-* Setting up a Plexus Application project
+## Setting up a Plexus Application project
 
-** Creating a Plexus application project using an archetype
+### Creating a Plexus application project using an archetype
 
-  Maven Archetypes are discussed in detail {{{http://maven.apache.org/guides/mini/guide-creating-archetypes.html}here}}.
+Maven Archetypes are discussed in detail [here](http://maven.apache.org/guides/mini/guide-creating-archetypes.html).
 
-  [[1]] From the command prompt, change directory to the location where you 
-  want to setup the Plexus application project.
+1. From the command prompt, change directory to the location where you want to setup the Plexus application project.
 
-  [[1]] Run the following command to set up a skeleton Plexus Application project.  
+1. Run the following command to set up a skeleton Plexus Application project.
 
-
-+------------------------------------------+
+```
 
  mvn archetype:create -DarchetypeGroupId=org.codehaus.plexus -DarchetypeArtifactId=plexus-archetype-application \
      -DarchetypeVersion=1.0-alpha-1-SNAPSHOT -DgroupId=org.codehaus.plexus -DartifactId=plexus-website-monitor-application \
      -DremoteRepositories=http://snapshots.repository.codehaus.org/
 
-+------------------------------------------+
+```
 
- The <<<maven-archetype-mojo>>> sets up a skeleton Maven plugin project '<<<plexus-website-monitor-application>>>' for 
- us with reasonable defaults.
+The `maven-archetype-mojo` sets up a skeleton Maven plugin project '`plexus-website-monitor-application`' for us with reasonable defaults.
 
- 
-** Updating pom.xml dependencies
+### Updating pom.xml dependencies
 
-  [[1]] Locate pom.xml under the '<<<plexus-website-monitor-application>>>' folder. 
+1. Locate pom.xml under the '`plexus-website-monitor-application`' folder.
 
-  [[1]] Edit it and add a <<<dependency>>> to the 
-  plexus-website-monitor-component that we have developed in earlier chapters.
+1. Edit it and add a `dependency` to the plexus-website-monitor-component that we have developed in earlier chapters.
 
-  [[1]] We also configure a 
+1. We also configure a
 
-    The pom.xml should look like this now:
+The pom.xml should look like this now:
 
-+------------------------------------------+
+```
 
 <?xml version="1.0"?><project>
   <parent>
@@ -90,37 +83,33 @@ Plexus Website Monitor Application
   </dependencies>
 </project>
 
-+------------------------------------------+
-
+```
 
-** Setting up an IDE project
+### Setting up an IDE project
 
-  Before we proceed further let us set up an Eclipse project for our Plexus application project. To do so currently, and as a workaround we comment out the generated <<<<packaging>>>> element in the <<<pom.xml>>> and add a <<<<packaging>>>><<<jar>>><<<</packaging>>>>. To generate an Eclipse project: 
+Before we proceed further let us set up an Eclipse project for our Plexus application project. To do so currently, and as a workaround we comment out the generated `<packaging>` element in the `pom.xml` and add a `<packaging>jar</packaging>`. To generate an Eclipse project:
 
-  [[1]] Open up a command prompt/terminal, and
+1. Open up a command prompt/terminal, and
 
-  [[1]] run the following command 
+1. run the following command
 
-+-------------------------------------------+  
+```
 
   mvn eclipse:clean eclipse:eclipse 
 
-+-------------------------------------------+
-
- Import the generated project under an Eclipse Project. 
+```
 
+Import the generated project under an Eclipse Project.
 
+### Adding an Application Entry Class
 
-** Adding an Application Entry Class 
+For any standalone Java application, we need a Class that defines a `main` method; the case of Plexus application is no different. We add a Application main class for our application (don't worry about the implementation details yet).
 
- For any standalone Java application, we need a Class that defines a <<<main>>> method; the case of Plexus application is no different. We add a Application main class for our application (don't worry about the implementation details yet). 
+We create a folder for Java sources `src/main/java` and add a sensible package for the main class. For this trail, we have created the package `org.codehaus.plexus.site.monitor` and create a main class `Main.java` under it.
 
+The generated source with a `System.out.println()` looks like below:
 
- We create a folder for Java sources <<<src/main/java>>> and add a sensible package for the main class. For this trail, we have created the package <<<org.codehaus.plexus.site.monitor>>> and create a main class <<<Main.java>>> under it. 
-
- The generated source with a <<<System.out.println()>>> looks like below: 
-
-+-------------------------------------------+
+```
 
 public class Main
 {
@@ -133,20 +122,19 @@ public class Main
 
 }
 
-+-------------------------------------------+
+```
+
+Having imported the project and added a main class, we now revert the `packaging` back to value `plexus-application`.
 
-  Having imported the project and added a main class, we now revert the <<<packaging>>> back to value <<<plexus-application>>>.
+### Setting up packaging configuration
 
+Next we set up an application assembler plugin for our Plexus application project. To do this,
 
-** Setting up packaging configuration
- 
- Next we set up an application assembler plugin for our Plexus application project. To do this, 
- 
-  [[1]] Locate the pom.xml for the plexus application project 
+1. Locate the pom.xml for the plexus application project
 
-  [[1]] update the <<<<build>>>> element configuration such that it is reflected as below
+1. update the `<build`\> element configuration such that it is reflected as below
 
-+--------------------------------------------+
+```
 
 ...
   <build>
@@ -193,22 +181,19 @@ public class Main
   </build>
 ...
 
-+--------------------------------------------+
+```
 
- Note how the assembly directory is specified in the <<<appassembler>>> plugin configuration - this is where our Plexus application will be packaged up when the Maven plugin is invoked. 
+Note how the assembly directory is specified in the `appassembler` plugin configuration - this is where our Plexus application will be packaged up when the Maven plugin is invoked.
 
+The discussion on Plugin configuration is beyond the scope of this tutorial, you can refer to book 'Better builds with Maven' or other resources available at:
 
- The discussion on Plugin configuration is beyond the scope of this tutorial, you can refer to book 'Better builds with Maven' or other resources available at:
+1. [Maven Books and Articles](http://maven.apache.org/articles.html).
 
-  [[1]] {{{http://maven.apache.org/articles.html}Maven Books and Articles}}.
+### Adding `\<pluginRepositories`\> for Appassembler plugin download
 
+As of this writing the Appassembler pluging is available from the Codehaus snapshots repository. To have Maven download the latest version (snapshot), we add the `pluginRepositories` information to the `pom.xml`
 
-** Adding <<<<pluginRepositories>>>> for Appassembler plugin download 
-
- As of this writing the Appassembler pluging is available from the Codehaus snapshots repository. To have Maven download the latest version (snapshot), we add the <<<pluginRepositories>>> information to the <<<pom.xml>>>
-
-
-+---------------------------------------------+
+```
 <project>
 ....
 ....
@@ -220,41 +205,37 @@ public class Main
     </pluginRepository>
   </pluginRepositories>
 </project>
-+---------------------------------------------+
- 
+```
 
-** Testing Application configuration
+### Testing Application configuration
 
- Before we go any further, let us take our Plexus site monitor application for a spin. To do this:
+Before we go any further, let us take our Plexus site monitor application for a spin. To do this:
 
-  [[1]]   Open a command prompt/terminal
+1. Open a command prompt/terminal
 
-  [[1]]   Change directory to the Plexus application project's directory
+1. Change directory to the Plexus application project's directory
 
-  [[1]]   Run the following Maven command 
+1. Run the following Maven command
 
-+--------------------------------------------+
+```
 mvn clean package 
-+--------------------------------------------+
+```
 
- If you look under <<<target>>> directory you will see that the Site Monitor application is assembled under <<<site-monitor-app>>> directory. The contents under that directory consist of executable scripts (Shell and batch script by default). 
+If you look under `target` directory you will see that the Site Monitor application is assembled under `site-monitor-app` directory. The contents under that directory consist of executable scripts (Shell and batch script by default).
 
- Lets try running the application and see what happens. To do this: 
+Lets try running the application and see what happens. To do this:
 
- [[1]]    At the command prompt, change directory to <<<${project-home}/target/site-monitor-app/bin>>>
+1. At the command prompt, change directory to `$project-home/target/site-monitor-app/bin`
 
- [[1]]    Run the script appropriate for your operating system. 
+1. Run the script appropriate for your operating system.
 
- You should an output similar to as below on the console:
+You should an output similar to as below on the console:
 
-+--------------------------------------------+
+```
 E:\plexus\plexus-examples\plexus-website-monitor-application\target\site-monitor-app\bin>monitor.bat
 Hello Plexus application!
-+--------------------------------------------+
-
-
- At this point we are ready to play with Plexus Embedder and hook our Website monitor component into our Plexus application.
-
- {{{./07_02_plexus_embedder_and_component_integration.html}Next: Plexus Embedder Intro & Site Monitor component integration into the application }} 
+```
 
+At this point we are ready to play with Plexus Embedder and hook our Website monitor component into our Plexus application.
 
+[Next: Plexus Embedder Intro & Site Monitor component integration into the application ](./07_02_plexus_embedder_and_component_integration.html)
diff --git a/src/site/markdown/guides/writing-components/07_02_plexus_embedder_and_component_integration.md b/src/site/markdown/guides/writing-components/07_02_plexus_embedder_and_component_integration.md
index 836f18f..5424251 100644
--- a/src/site/markdown/guides/writing-components/07_02_plexus_embedder_and_component_integration.md
+++ b/src/site/markdown/guides/writing-components/07_02_plexus_embedder_and_component_integration.md
@@ -1,22 +1,20 @@
- -----
-Plexus Embedder and Component lookups
- -----
-Rahul Thakur
- ----
-2006-11-15
- ------
- 
- <<<The contents of this document are a work in progress>>>
+---
+title: Plexus Embedder and Component lookups
+author: Rahul Thakur
+date: 2006-11-15
+---
 
-Plexus Embedder
+`The contents of this document are a work in progress`
 
-  The Plexus Embedder allows us to set up and start a Plexus Container container from within a Standalone application. The components can then be looked up in usual manner (we will see demonstrate in bit, if you don't know). 
+# Plexus Embedder
 
-* Making Embedder available to the application 
- 
-  First thing, we need to make the Embedder available to our application by adding a dependency on it in the <<<pom.xml>>>. Follow snippet shows the relevant <<<<dependency>>>> section of the application project's <<<pom.xml>>>.
+The Plexus Embedder allows us to set up and start a Plexus Container container from within a Standalone application. The components can then be looked up in usual manner (we will see demonstrate in bit, if you don't know).
 
-+-------------------------------+ 
+## Making Embedder available to the application
+
+First thing, we need to make the Embedder available to our application by adding a dependency on it in the `pom.xml`. Follow snippet shows the relevant `<dependency`\> section of the application project's `pom.xml`.
+
+```
 
 <project>
   ...
@@ -42,24 +40,23 @@ Plexus Embedder
   ...
 </project>
 
-+-------------------------------+
+```
 
-  Regenerate the IDE project again as discussed in the previous section.
+Regenerate the IDE project again as discussed in the previous section.
 
+## Starting up an embedded Plexus Container instance
 
-* Starting up an embedded Plexus Container instance
+Lets add some code to our Site Monitor application entry class that:
 
-  Lets add some code to our Site Monitor application entry class that:
-  
-  [[1]] creates and starts an Embedder instance
+1. creates and starts an Embedder instance
 
-  [[1]] Obtains <<<PlexusContainer>>> instance, and
+1. Obtains `PlexusContainer` instance, and
 
-  [[1]] performs a lookup for <<<WebsiteMonitor>>> component
+1. performs a lookup for `WebsiteMonitor` component
 
-  Our updated code looks as below:
+Our updated code looks as below:
 
-+-------------------------------+
+```
 public class Main
 {
 
@@ -96,32 +93,24 @@ public class Main
     }
 
 }
-+-------------------------------+
+```
 
-  At this point you can try running the above <<<Main>>> class from your 
-  favorite IDE. For demonstration purposes the <<<WebsiteMonitor>>> is by
-  default configured to monitor <<<http://plexus.codehaus.org>>>. You should
-  see it output the HTTP status for the monitoring request issued. 
+At this point you can try running the above `Main` class from your favorite IDE. For demonstration purposes the `WebsiteMonitor` is by default configured to monitor `http://plexus.codehaus.org`. You should see it output the HTTP status for the monitoring request issued.
 
-  Something like this:
+Something like this:
 
-+--------------------------------+
+```
 [INFO] HTTP request returned HTTP status code: 200 for website: http://plexus.codehaus.org/
-+--------------------------------+
-
-* How does Plexus Embedder works?
+```
 
-  Plexus Embedder creates an instance of Plexus Container, which then loads and
-  parses all available dependencies to discover any Plexus Components and registers 
-  them internally to make them available for look-ups. 
+## How does Plexus Embedder works?
 
-  To recapture again, the container looks for a Component descriptor under:
+Plexus Embedder creates an instance of Plexus Container, which then loads and parses all available dependencies to discover any Plexus Components and registers them internally to make them available for look-ups.
 
-  [[1]] META-INF/plexus/components.xml
+To recapture again, the container looks for a Component descriptor under:
 
-  This is exactly what those few lines of code achieve in the above snippet. 
-  You can, of course, use the Embedder to do fancier stuff.
+1. META-INF/plexus/components.xml
 
-  Great! we have just finished integrating our site monitor component into our 
-  site monitor application.
+This is exactly what those few lines of code achieve in the above snippet. You can, of course, use the Embedder to do fancier stuff.
 
+Great! we have just finished integrating our site monitor component into our site monitor application.
diff --git a/src/site/markdown/guides/writing-components/07_03_from_a_web_application.md b/src/site/markdown/guides/writing-components/07_03_from_a_web_application.md
index aa7810b..a982026 100644
--- a/src/site/markdown/guides/writing-components/07_03_from_a_web_application.md
+++ b/src/site/markdown/guides/writing-components/07_03_from_a_web_application.md
@@ -1,40 +1,32 @@
- -----
-Using a Plexus Component from a web application.
- -----
-Michal Maczka 
-Rahul Thakur
- ----
-2006-11-21
- ------
+---
+title: Using a Plexus Component from a web application.
+author:
+  - Michal Maczka
+  - Rahul Thakur
+date: 2006-11-21
+---
 
- <<<The contents of this document are a work in progress>>>
+`The contents of this document are a work in progress`
 
+# How to use Plexus in web applications
 
-How to use Plexus in web applications
+Before we demonstrate how we can set up a web application to start a Plexus Container and look up Plexus components, let us understand the alternatives that are available to embed Plexus container in web applications.
 
- Before we demonstrate how we can set up a web application to start a Plexus 
- Container and look up Plexus components, let us understand the alternatives 
- that are available to embed Plexus container in web applications.
+## Configuration
 
-* Configuration
+Plexus Servlet module exists for simplifying embedding and usage of Plexus in context of web applications which run inside the servlet container.
 
- Plexus Servlet module exists for simplifying embedding and usage of Plexus in
- context of web applications which run inside the servlet container.
+There are two ways of embedding Plexus.
 
- There are two ways  of embedding Plexus.  
+1. By setting up a **Plexus[ServletContextListener](http://java.sun.com/products/servlet/2.3/javadoc/javax/servlet/ServletContextListener.html)**
 
- [[1]]  By setting up a <<Plexus{{{http://java.sun.com/products/servlet/2.3/javadoc/javax/servlet/ServletContextListener.html}ServletContextListener}}>>
+1. By setting up a **PlexusLoaderServlet**.
 
- [[1]]  By setting up a <<PlexusLoaderServlet>>.
+The first way is suported by servlet containers which are compliant with servlet specification 2.3 or higher. Second one should be used for compatibility with older versions of servlet containers
 
+## Setting up PlexusServletContextListener to embed Plexus
 
- The first way is suported by servlet containers which are compliant with
- servlet specification 2.3 or higher.  Second one should be used for
- compatibility with older versions of servlet containers
-
-* Setting up PlexusServletContextListener to embed Plexus
-
-+---+
+```
 <web-app>
   ...
   <listener>
@@ -42,54 +34,49 @@ How to use Plexus in web applications
   </listener>
   ...
 <web-app>
-+---+
+```
 
-* Setting up PlexusLoaderServlet to embed Plexus
+## Setting up PlexusLoaderServlet to embed Plexus
 
-+---+
+```
 <servlet>
   <servlet-name>plexus</servlet-name>
   <servlet-class>org.codehaus.plexus.servlet.PlexusLoaderServlet</servlet-class>
   <load-on-startup>1</load-on-startup>
 </servlet>
-+---+
-
- By default, in both the above cases, the Plexus Embedder will search for the 
- configuration files in the following locations:
-
- * /WEB-INF/plexus.xml (for main Plexus configuration file)
+```
 
- * /WEB-INF/plexus.properties (for properties file which is used for seeding Plexus context)
+By default, in both the above cases, the Plexus Embedder will search for the configuration files in the following locations:
 
- These location can be overidden <TODO: explain how>
+- /WEB-INF/plexus.xml (for main Plexus configuration file)
 
- ~~ TODO: Incorporate following
- ~~ Notes from chat with Trygvis
- ~~ plexus.properties is useful for changing ${properties} in your xml file
- ~~ you can change the location of plexus.xml with servlet configuration
- ~~ init-prameters or something
+- /WEB-INF/plexus.properties (for properties file which is used for seeding Plexus context)
 
+These location can be overidden _TODO: explain how_
 
- In both the above cases a new instance of Plexus Conatiner will be created and stored in
- "application" scope for the web application under the key:
- <<org.codehaus.plexus.PlexusConstants.PLEXUS_KEY>>
+<!--  TODO: Incorporate following -->
+<!--  Notes from chat with Trygvis -->
+<!--  plexus.properties is useful for changing ${properties} in your xml file -->
+<!--  you can change the location of plexus.xml with servlet configuration -->
+<!--  init-prameters or something -->
+In both the above cases a new instance of Plexus Conatiner will be created and stored in "application" scope for the web application under the key: **org.codehaus.plexus.PlexusConstants.PLEXUS_KEY**
 
-* How to lookup and release components
+## How to lookup and release components
 
-** In a Servlet
+### In a Servlet
 
-+---+
+```
 ...
 ServletContext context = getServletContext();
 VelocityComponent velocityComponent = ( VelocityComponent ) PlexusServletUtils.lookup( context, VelocityComponent.ROLE );
 ...
 PlexusServletUtils.release( context, velocityComponent );
 ...
-+---+
+```
 
-** In JSP
+### In JSP
 
-+---+
+```
 <%
 ...
 VelocityComponent velocityComponent = ( VelocityComponent ) PlexusServletUtils.lookup( application, VelocityComponent.ROLE );
@@ -97,11 +84,11 @@ VelocityComponent velocityComponent = ( VelocityComponent ) PlexusServletUtils.l
 PlexusServletUtils.release( application, velocityComponent );
 ...
 %>
-+---+
+```
 
-** In Struts Action or in similar case 
+### In Struts Action or in similar case
 
-+---+
+```
 public abstract class BaseAction extends Action
 {
     protected Object lookup( HttpServletRequest request, String role )
@@ -135,30 +122,26 @@ public abstract class BaseAction extends Action
         release( request, velocityComponent );
     }
 }
-+---+
+```
 
+## Obtaining the Plexus Container instance
 
-* Obtaining the Plexus Container instance
+If you need to access the instance of PlexusContainer object, it can be obtained by the following call:
 
- If you need to access the instance of PlexusContainer object, it can be 
- obtained by the following call:
-
-+---+
+```
 PlexusContainer getPlexusContainer( ServletContext servletContext )
-+---+
+```
 
-** Required artifacts
+### Required artifacts
 
- Maven dependency:
+Maven dependency:
 
-+---+
+```
 <dependency>
   <groupId>plexus</groupId>
   <artifactId>plexus-servlet</artifactId>
   <version>1.0-beta-2</version>
 </dependency>
-+---+
-
- {{{./07_03_setting_up_a_web_application.html}Next: Setting up a Web Application Project }} 
-
+```
 
+[Next: Setting up a Web Application Project ](./07_03_setting_up_a_web_application.html)
diff --git a/src/site/markdown/guides/writing-components/07_03_setting_up_a_web_application.md b/src/site/markdown/guides/writing-components/07_03_setting_up_a_web_application.md
index aef69be..22e0c4b 100644
--- a/src/site/markdown/guides/writing-components/07_03_setting_up_a_web_application.md
+++ b/src/site/markdown/guides/writing-components/07_03_setting_up_a_web_application.md
@@ -1,29 +1,24 @@
- -----
-Preparing the Web application project.
- -----
-Rahul Thakur
- ----
-2006-11-22
- ------
+---
+title: Preparing the Web application project.
+author: Rahul Thakur
+date: 2006-11-22
+---
 
- <<<The contents of this document are a work in progress>>>
+`The contents of this document are a work in progress`
 
-Preparing the web application project to use Plexus
+# Preparing the web application project to use Plexus
 
- We will create a very basic web application project first and then gradually
- evolve it to demonstrate how Plexus can be embedded.
+We will create a very basic web application project first and then gradually evolve it to demonstrate how Plexus can be embedded.
 
- To create a web application skeleton: 
+To create a web application skeleton:
 
-  [[1]] Open the command prompt/terminal window. 
+1. Open the command prompt/terminal window.
 
-  [[1]] Change directory to where you want to create your web application 
-        project.
+1. Change directory to where you want to create your web application project.
 
-  [[1]] Run the following Maven command 
+1. Run the following Maven command
 
-
-+---------------------------+
+```
 mvn archetype:create -DarchetypeGroupId=org.apache.maven.archetypes \
     -DarchetypeArtifactId=maven-archetype-webapp \
     -DarchetypeVersion=1.0-alpha-4-SNAPSHOT  \
@@ -32,43 +27,28 @@ mvn archetype:create -DarchetypeGroupId=org.apache.maven.archetypes \
     -DpackageName=org.codehaus.plexus.tutorial \
     -Dpackaging=war \
     -DremoteRepositories=http://people.apache.org/repo/m2-snapshot-repository/
-+---------------------------+
-
- <<Archetype creation options are explained here:>>
-
-
-*----------+--------------+----------------:
-| <<Commandline Option>> 	| <<Description>> 	| <<Required>> |
-*----------+--------------+----------------:
-| -DarchetypeGroupId 	| "groupId" for the archetype we want to use 	| Yes |
-*----------+--------------+----------------:
-| -DarchetypeArtifact 	| "artifactId" for the archetype we want to use |	Yes |
-*----------+--------------+----------------:
-| -DarchetypeVersion 	| "version" for the archetype we want to use 	| Yes| 
-*----------+--------------+----------------:
-| -DgroupId 	| "groupId" for the project to be generated 	| Yes |
-*----------+--------------+----------------:
-| -DartifactId | "artifactId" for the project to be generated |	Yes |
-*----------+--------------+----------------:
-| -DpackageName |	Base package name to be use for any Java sources being copied over 	| No|
-*----------+--------------+----------------:
-| -Dpackaging |	Packaging to be used for the created project | No|
-*----------+--------------+----------------:
-| -DremoteRepositories | Comma-separated list of repositories to lookup to retrieve archetype | No|
-*----------+--------------+----------------:
+```
 
+**Archetype creation options are explained here:**
 
- For more information on Maven Archetypes please refer to 
- {{{http://maven.apache.org/guides/getting-started/index.html}this resource}} on the Maven website.
+|**Commandline Option**|**Description**|**Required**|
+|---|---|---|
+|-DarchetypeGroupId|"groupId" for the archetype we want to use|Yes|
+|-DarchetypeArtifact|"artifactId" for the archetype we want to use|Yes|
+|-DarchetypeVersion|"version" for the archetype we want to use|Yes|
+|-DgroupId|"groupId" for the project to be generated|Yes|
+|-DartifactId|"artifactId" for the project to be generated|Yes|
+|-DpackageName|Base package name to be use for any Java sources being copied over|No|
+|-Dpackaging|Packaging to be used for the created project|No|
+|-DremoteRepositories|Comma-separated list of repositories to lookup to retrieve archetype|No|
 
+For more information on Maven Archetypes please refer to [this resource](http://maven.apache.org/guides/getting-started/index.html) on the Maven website.
 
- A web application project should have been created now at the location where 
- you ran the <<<archetype:create>>> command. 
+A web application project should have been created now at the location where you ran the `archetype:create` command.
 
- Locate the <<<pom.xml>>> under the created project, the contents of the POM 
- should be as below:
+Locate the `pom.xml` under the created project, the contents of the POM should be as below:
 
-+---------------------------+
+```
 <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
   <modelVersion>4.0.0</modelVersion>
@@ -90,18 +70,15 @@ mvn archetype:create -DarchetypeGroupId=org.apache.maven.archetypes \
     <finalName>plexus-example-webapp</finalName>
   </build>
 </project>
-+---------------------------+
+```
 
-* Updating the POM 
+## Updating the POM
 
-  Before we can embed Plexus in our web application we need to make the JAR 
-  library that contains the Plexus Embedder available to our project. We do 
-  this by introducing required  <<<<dependency>>>> elements in the project's
-  <<<pom.xml>>>. 
+Before we can embed Plexus in our web application we need to make the JAR library that contains the Plexus Embedder available to our project. We do this by introducing required `<dependency`\> elements in the project's `pom.xml`.
 
-  The updated <<<pom.xml>>> (along with some other updates) looks as below:
+The updated `pom.xml` (along with some other updates) looks as below:
 
-+---------------------------+
+```
 <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
   <parent>
@@ -139,30 +116,26 @@ mvn archetype:create -DarchetypeGroupId=org.apache.maven.archetypes \
     </dependency>
   </dependencies>
 </project>
-+---------------------------+
+```
 
-*Generate a Project for your IDE.
+## Generate a Project for your IDE.
 
-** For Eclipse.
- 
-   [[1]] Change directory to the newly created directory 'plexus-example-webapp'
-   
-   [[1]] Run the following command from command prompt to generate Eclipse project setting files.
+### For Eclipse.
 
-   
-+------------------------------------------+
+1. Change directory to the newly created directory 'plexus-example-webapp'
+
+1. Run the following command from command prompt to generate Eclipse project setting files.
+
+```
  (for WTP 0.7)
  E:\plexus\plexus-examples\plexus-example-webapp>mvn eclipse:eclipse 
-+------------------------------------------+
+```
 
-+------------------------------------------+
+```
  (for WTP 1.0 or higher)
  E:\plexus\plexus-examples\plexus-example-webapp>mvn eclipse:eclipse -Dwtpversion=1.0
-+------------------------------------------+
-
- Eclipse project files should get generated succesfully at this point. If there were any unsatisfied dependencies, update <<<<version>>>> for dependencies in pom.xml to an available release version.
- 
-   [[1]] Fire up Eclipse and import the generated project into an Eclipse Workspace.
- 
+```
 
+Eclipse project files should get generated succesfully at this point. If there were any unsatisfied dependencies, update `<version`\> for dependencies in pom.xml to an available release version.
 
+1. Fire up Eclipse and import the generated project into an Eclipse Workspace.
diff --git a/src/site/markdown/guides/writing-components/07_04_from_a_soap_webservice.md b/src/site/markdown/guides/writing-components/07_04_from_a_soap_webservice.md
index c3b6bcd..2971cc6 100644
--- a/src/site/markdown/guides/writing-components/07_04_from_a_soap_webservice.md
+++ b/src/site/markdown/guides/writing-components/07_04_from_a_soap_webservice.md
@@ -1,11 +1,9 @@
- -----
-Using a Plexus compoenent from a webservice.
- -----
-Rahul Thakur
- ----
-2006-06-08
- ------
+---
+title: Using a Plexus compoenent from a webservice.
+author: Rahul Thakur
+date: 2006-06-08
+---
 
- <<<The contents of this document are a work in progress>>>
+`The contents of this document are a work in progress`
 
-~~TODO:  
+<!-- TODO:   -->
diff --git a/src/site/markdown/guides/writing-components/07_05_from_an_xmlrpc_service.md b/src/site/markdown/guides/writing-components/07_05_from_an_xmlrpc_service.md
index cdc96c1..da7243e 100644
--- a/src/site/markdown/guides/writing-components/07_05_from_an_xmlrpc_service.md
+++ b/src/site/markdown/guides/writing-components/07_05_from_an_xmlrpc_service.md
@@ -1,11 +1,9 @@
- -----
-Using a Plexus Component from an XML RPC service
- -----
-Rahul Thakur
- ----
-2006-06-08
- ------
+---
+title: Using a Plexus Component from an XML RPC service
+author: Rahul Thakur
+date: 2006-06-08
+---
 
- <<<The contents of this document are a work in progress>>>
+`The contents of this document are a work in progress`
 
-~~TODO:  
+<!-- TODO:   -->
diff --git a/src/site/markdown/guides/writing-components/07_component_usage_scenarios.md b/src/site/markdown/guides/writing-components/07_component_usage_scenarios.md
index 3842603..f2f7da8 100644
--- a/src/site/markdown/guides/writing-components/07_component_usage_scenarios.md
+++ b/src/site/markdown/guides/writing-components/07_component_usage_scenarios.md
@@ -1,11 +1,9 @@
- -----
-Component Usage scenarios - an overview 
- -----
-Rahul Thakur
- ----
-2006-06-08
- ------
+---
+title: Component Usage scenarios - an overview
+author: Rahul Thakur
+date: 2006-06-08
+---
 
- <<<The contents of this document are a work in progress>>>
+`The contents of this document are a work in progress`
 
-~~TODO:  
+<!-- TODO:   -->
diff --git a/src/site/markdown/guides/writing-components/08_packaging_up.md b/src/site/markdown/guides/writing-components/08_packaging_up.md
index e5e8a74..fb65910 100644
--- a/src/site/markdown/guides/writing-components/08_packaging_up.md
+++ b/src/site/markdown/guides/writing-components/08_packaging_up.md
@@ -1,16 +1,12 @@
- -----
-Packaging up a Plexus component.
- -----
-Rahul Thakur
- ----
-2006-06-08
- ------
+---
+title: Packaging up a Plexus component.
+author: Rahul Thakur
+date: 2006-06-08
+---
 
- <<<The contents of this document are a work in progress>>>
+`The contents of this document are a work in progress`
 
-Packaging as a Plexus Application
+# Packaging as a Plexus Application
 
- ~~TODO: Discuss what is a Plexus Application - makes use of Plexus Runtime and is managed by Plexus Container
-
-* Elements of a Plexus Application
- 
+<!-- TODO: Discuss what is a Plexus Application - makes use of Plexus Runtime and is managed by Plexus Container -->
+## Elements of a Plexus Application
diff --git a/src/site/markdown/index.md b/src/site/markdown/index.md
index e88eafa..1b81bc8 100644
--- a/src/site/markdown/index.md
+++ b/src/site/markdown/index.md
@@ -1,119 +1,83 @@
- -----
- Plexus Overview
- -----
- Brett Porter
- -----
- 2015-09-13
- -----
+---
+title: Plexus Overview
+author: Brett Porter
+date: 2015-09-13
+---
 
-Overview
+# Overview
 
-  Codehaus Plexus is a collection of small Java libraries that {{{https://maven.apache.org/}Apache Maven}} and
-  its plugins are built on: archive handling, compiler abstraction, file I/O, XML, string interpolation,
-  classloader management and code generation.
+Codehaus Plexus is a collection of small Java libraries that [Apache Maven](https://maven.apache.org/) and its plugins are built on: archive handling, compiler abstraction, file I/O, XML, string interpolation, classloader management and code generation.
 
-  If you write Maven plugins you almost certainly depend on several of these already, usually transitively.
+If you write Maven plugins you almost certainly depend on several of these already, usually transitively.
 
-  Each project has its own site, linked below, with Javadoc and reports. Sources and issues are on
-  {{{https://github.com/codehaus-plexus}GitHub}}.
+Each project has its own site, linked below, with Javadoc and reports. Sources and issues are on [GitHub](https://github.com/codehaus-plexus).
 
-* A note on the name
+## A note on the name
 
-  Plexus originally had two halves: an IoC container, and a set of components written for it.
-  <<The container is retired.>> Maven moved to {{{https://www.eclipse.org/sisu/}Eclipse Sisu}} and
-  {{{https://jcp.org/en/jsr/detail?id=330}JSR-330}} years ago, and nothing listed below needs a Plexus
-  container to run -- the components are ordinary JSR-330 beans.
+Plexus originally had two halves: an IoC container, and a set of components written for it. **The container is retired.** Maven moved to [Eclipse Sisu](https://www.eclipse.org/sisu/) and [JSR-330](https://jcp.org/en/jsr/detail?id\=330) years ago, and nothing listed below needs a Plexus container to run -- the components are ordinary JSR-330 beans.
 
-  What remains, and what this project is now, is the second half: the libraries below. The container
-  documentation is still on this site, under <Old IoC Documentation>, because a great deal of writing
-  from that era links to it. See {{{./ref/feature-comparison.html}Feature Comparison}} for how Plexus
-  related to other IoC ecosystems of the time.
+What remains, and what this project is now, is the second half: the libraries below. The container documentation is still on this site, under _Old IoC Documentation_, because a great deal of writing from that era links to it. See [Feature Comparison](./ref/feature-comparison.html) for how Plexus related to other IoC ecosystems of the time.
 
-Libraries
+# Libraries
 
-  * {{{./plexus-utils/}plexus-utils}} -- utilities for strings, files, command lines and process execution.
+- [plexus-utils](./plexus-utils/) -- utilities for strings, files, command lines and process execution.
 
-  * {{{./plexus-xml/}plexus-xml}} -- XML classes split out of <plexus-utils> 4 (<<<Xpp3Dom>>> and friends).
+- [plexus-xml](./plexus-xml/) -- XML classes split out of _plexus-utils_ 4 (`Xpp3Dom` and friends).
 
-  * {{{./plexus-io/}plexus-io}} -- file and resource abstractions, selectors and mappers.
+- [plexus-io](./plexus-io/) -- file and resource abstractions, selectors and mappers.
 
-  * {{{./plexus-interpolation/}plexus-interpolation}} -- resolves expressions in the <<<$\{...\}>>> style;
-    the engine behind POM interpolation.
+- [plexus-interpolation](./plexus-interpolation/) -- resolves expressions in the `${...}` style; the engine behind POM interpolation.
 
-  * {{{./plexus-classworlds/}plexus-classworlds}} -- classloader management; how Maven isolates plugins
-    from itself.
+- [plexus-classworlds](./plexus-classworlds/) -- classloader management; how Maven isolates plugins from itself.
 
-  []
+# Components
 
-Components
+- [plexus-archiver](./plexus-archiver/) -- one API over zip, jar, tar and their compressed variants.
 
-  * {{{./plexus-archiver/}plexus-archiver}} -- one API over zip, jar, tar and their compressed variants.
+- [plexus-compiler](./plexus-compiler/) -- one API over javac, ECJ, AspectJ and others; used by _maven-compiler-plugin_.
 
-  * {{{./plexus-compiler/}plexus-compiler}} -- one API over javac, ECJ, AspectJ and others; used by
-    <maven-compiler-plugin>.
+- [plexus-languages](./plexus-languages/) -- reads `module-info` and splits the classpath from the module path (_plexus-java_).
 
-  * {{{./plexus-languages/}plexus-languages}} -- reads <<<module-info>>> and splits the classpath from
-    the module path (<plexus-java>).
+- [plexus-sec-dispatcher](./plexus-sec-dispatcher/) -- encrypts and decrypts passwords in `settings.xml`. See the [Maven encryption guide](https://maven.apache.org/guides/mini/guide-encryption-4.html) for usage.
 
-  * {{{./plexus-sec-dispatcher/}plexus-sec-dispatcher}} -- encrypts and decrypts passwords in
-    <<<settings.xml>>>. See the
-    {{{https://maven.apache.org/guides/mini/guide-encryption-4.html}Maven encryption guide}} for usage.
+- [plexus-resources](./plexus-resources/) -- reads a resource from the filesystem, the classpath or a URL.
 
-  * {{{./plexus-resources/}plexus-resources}} -- reads a resource from the filesystem, the classpath or a URL.
+- [plexus-velocity](./plexus-velocity/) -- Apache Velocity integration.
 
-  * {{{./plexus-velocity/}plexus-velocity}} -- Apache Velocity integration.
+- [plexus-i18n](./plexus-i18n/) -- resource bundle lookup for localised messages.
 
-  * {{{./plexus-i18n/}plexus-i18n}} -- resource bundle lookup for localised messages.
+- [plexus-interactivity](./plexus-interactivity/) -- prompts the user on the console.
 
-  * {{{./plexus-interactivity/}plexus-interactivity}} -- prompts the user on the console.
+- [plexus-build-api](./plexus-build-api/) -- lets plugins report file changes to an incremental build, such as m2e.
 
-  * {{{./plexus-build-api/}plexus-build-api}} -- lets plugins report file changes to an incremental
-    build, such as m2e.
+# Tooling
 
-  []
+- [Modello](./modello/) -- generates Java classes, readers and writers, XSD and documentation from a single model file. MIT licensed; everything else here is Apache-2.0.
 
-Tooling
+- [plexus-testing](./plexus-testing/) -- JUnit 5 support for testing JSR-330 components.
 
-  * {{{./modello/}Modello}} -- generates Java classes, readers and writers, XSD and documentation from a
-    single model file. MIT licensed; everything else here is Apache-2.0.
+- [plexus](./plexus-pom/) -- the parent POM every project here inherits.
 
-  * {{{./plexus-testing/}plexus-testing}} -- JUnit 5 support for testing JSR-330 components.
+# Retired
 
-  * {{{./plexus-pom/}plexus}} -- the parent POM every project here inherits.
+These are archived and receive no fixes, including security fixes. Don't start anything new on them.
 
-  []
+- [plexus-containers](./plexus-containers/) -- use [Eclipse Sisu](https://www.eclipse.org/sisu/) with JSR-330 annotations.
 
-Retired
+- [plexus-cipher](https://github.com/codehaus-plexus/plexus-cipher) -- absorbed into [plexus-sec-dispatcher](./plexus-sec-dispatcher/) 4.x.
 
-  These are archived and receive no fixes, including security fixes. Don't start anything new on them.
+- [plexus-digest](./plexus-digest/) -- use `java.security.MessageDigest`, or Commons Codec.
 
-  * {{{./plexus-containers/}plexus-containers}} -- use {{{https://www.eclipse.org/sisu/}Eclipse Sisu}}
-    with JSR-330 annotations.
+- [plexus-cli](https://github.com/codehaus-plexus/plexus-cli) -- use Commons CLI or picocli.
 
-  * {{{https://github.com/codehaus-plexus/plexus-cipher}plexus-cipher}} -- absorbed into
-    {{{./plexus-sec-dispatcher/}plexus-sec-dispatcher}} 4.x.
+- [plexus-component-factories](https://github.com/codehaus-plexus/plexus-component-factories) and [plexus-maven-plugin](https://github.com/codehaus-plexus/plexus-maven-plugin) -- container concerns that no longer exist under Sisu.
 
-  * {{{./plexus-digest/}plexus-digest}} -- use <<<java.security.MessageDigest>>>, or Commons Codec.
+- [plexus-swizzle](https://github.com/codehaus-plexus/plexus-swizzle) -- no replacement.
 
-  * {{{https://github.com/codehaus-plexus/plexus-cli}plexus-cli}} -- use Commons CLI or picocli.
+- [plexus-components](https://github.com/codehaus-plexus/plexus-components) -- split into the individual repositories above.
 
-  * {{{https://github.com/codehaus-plexus/plexus-component-factories}plexus-component-factories}} and
-    {{{https://github.com/codehaus-plexus/plexus-maven-plugin}plexus-maven-plugin}} -- container concerns
-    that no longer exist under Sisu.
+# Contributing
 
-  * {{{https://github.com/codehaus-plexus/plexus-swizzle}plexus-swizzle}} -- no replacement.
+Issues and pull requests are welcome on each repository. See [CONTRIBUTING](https://github.com/codehaus-plexus/.github/blob/master/CONTRIBUTING.md) for building, the Java baseline and code formatting.
 
-  * {{{https://github.com/codehaus-plexus/plexus-components}plexus-components}} -- split into the
-    individual repositories above.
-
-  []
-
-Contributing
-
-  Issues and pull requests are welcome on each repository. See
-  {{{https://github.com/codehaus-plexus/.github/blob/master/CONTRIBUTING.md}CONTRIBUTING}} for building,
-  the Java baseline and code formatting.
-
-  To report a security vulnerability, please follow
-  {{{https://github.com/codehaus-plexus/.github/blob/master/SECURITY.md}SECURITY}} rather than opening a
-  public issue.
+To report a security vulnerability, please follow [SECURITY](https://github.com/codehaus-plexus/.github/blob/master/SECURITY.md) rather than opening a public issue.
diff --git a/src/site/markdown/new-container-gotchas.md b/src/site/markdown/new-container-gotchas.md
index 1448238..f8c824e 100644
--- a/src/site/markdown/new-container-gotchas.md
+++ b/src/site/markdown/new-container-gotchas.md
@@ -1,40 +1,25 @@
- -----
- New container gotchas
- -----
- Brett Porter
- -----
-2007-01-13
- -----
+---
+title: New container gotchas
+author: Brett Porter
+date: 2007-01-13
+---
 
-New Container Gotchas
+# New Container Gotchas
 
-  Due to the fundamental classloading changes in the new container, there can occasionally be clahes with old versions of the 
-  container or components designed for the other container. This document will help workaround those issues, align code
-  appropriately, and perhaps help form a list of backwards compatibility fixes that need to be made.
+Due to the fundamental classloading changes in the new container, there can occasionally be clahes with old versions of the container or components designed for the other container. This document will help workaround those issues, align code appropriately, and perhaps help form a list of backwards compatibility fixes that need to be made.
 
-* New component API creeping into dependency tree
+## New component API creeping into dependency tree
 
-  One thing to watch out for is that if you are using an old container (alpha-10) in your application, but some of your
-  dependencies have been updated to the new one as a compile time dependency, then the plexus-component-api artifact will be
-  added to the tree, which can conflict with the same classes already in the alpha-10 artifact.
+One thing to watch out for is that if you are using an old container (alpha-10) in your application, but some of your dependencies have been updated to the new one as a compile time dependency, then the plexus-component-api artifact will be added to the tree, which can conflict with the same classes already in the alpha-10 artifact.
 
-  <<Workaround:>> upgrade application to the new container, or add component-api to \<exclusions\> where necessary.
+**Workaround:** upgrade application to the new container, or add component-api to \<exclusions\> where necessary.
 
-* New component API creeping into plugin dependency tree
+## New component API creeping into plugin dependency tree
 
-  Similar to above, but more serious. This causes the new component API to be loaded into the classloader of a plugin.
-  In Maven 2.0.x, this means that many Plexus classes will be loaded from there, causing ClassNotFoundExceptions, or failed
-  instanceof calls causing the plugins not to work. For instance, a NullPointerException for a logger is a classic case.
+Similar to above, but more serious. This causes the new component API to be loaded into the classloader of a plugin. In Maven 2.0.x, this means that many Plexus classes will be loaded from there, causing ClassNotFoundExceptions, or failed instanceof calls causing the plugins not to work. For instance, a NullPointerException for a logger is a classic case.
 
-  <<Workaround:>> None known. You can add plexus-component-api to the exclusions in Maven, but this requires a new 2.0.x release.
-  Alternatively, don't use the component API from plugins that have a prerequisite lower than Maven 2.1.
-
-* Maven Jetty Plugin
-
-  The Maven Jetty Plugin seems to be failing with webapps that use the plexus container in some instances. In former versions
-  of plexus-xwork-integration, the container was forced to ignore plexus.xml from Maven using a classloader. Using the new
-  version this appears not to work (though I suspect it would work if Maven was using the new container too - ie, trunk).
-  More investigation needed. See {{{http://jira.codehaus.org/browse/JETTY-62} JETTY-62}} for the original problem that is
-  reoccurring.
+**Workaround:** None known. You can add plexus-component-api to the exclusions in Maven, but this requires a new 2.0.x release. Alternatively, don't use the component API from plugins that have a prerequisite lower than Maven 2.1.
 
+## Maven Jetty Plugin
 
+The Maven Jetty Plugin seems to be failing with webapps that use the plexus container in some instances. In former versions of plexus-xwork-integration, the container was forced to ignore plexus.xml from Maven using a classloader. Using the new version this appears not to work (though I suspect it would work if Maven was using the new container too - ie, trunk). More investigation needed. See [ JETTY-62](http://jira.codehaus.org/browse/JETTY-62) for the original problem that is reoccurring.
diff --git a/src/site/markdown/ref/component-configuration.md b/src/site/markdown/ref/component-configuration.md
index 5a56aa9..abfbda3 100644
--- a/src/site/markdown/ref/component-configuration.md
+++ b/src/site/markdown/ref/component-configuration.md
@@ -1,82 +1,69 @@
- -----
- Component Configuration
- -----
- -----
+---
+title: Component Configuration
+---
 
- <<<The contents of this document are a work in progress>>>
+`The contents of this document are a work in progress`
 
-Component Configuration
+# Component Configuration
 
-* Overview
+## Overview
 
- For each component plexus creates a component profile.   The profiles keeps track of the following things for each component:
+For each component plexus creates a component profile. The profiles keeps track of the following things for each component:
 
- * {{{#Component_Factory}}}
+- [Component_Factory](#Component_Factory)
 
- * {{{#Lifecycle_Handler}}}
+- [Lifecycle_Handler](#Lifecycle_Handler)
 
- * {{{#Component_Composer}}}
+- [Component_Composer](#Component_Composer)
 
- * {{{#Instantiation_Strategy}}}
+- [Instantiation_Strategy](#Instantiation_Strategy)
 
- * The configuration for the component
+- The configuration for the component
 
-* Component Descriptor
+## Component Descriptor
 
- Let's take a look at the component descriptor.  It starts off with a block for the component:
+Let's take a look at the component descriptor. It starts off with a block for the component:
 
-+---+
+```
 <component>
-+---+
+```
 
- You can then declare the role and the role hint of the component. The role and
- the hint are what you use to look up your component from plexus. The hint is
- optional. The hint is just an extra id that allows you to differentiate
- components of the same type.
+You can then declare the role and the role hint of the component. The role and the hint are what you use to look up your component from plexus. The hint is optional. The hint is just an extra id that allows you to differentiate components of the same type.
 
-+---+
+```
 <role>org.codehaus.plexus.Component</role>
 <role-hint>component1</role-hint>
-+---+
+```
 
- The implementation attribute tells plexus what you want to use to implement the specified role:
+The implementation attribute tells plexus what you want to use to implement the specified role:
 
-+---+
+```
 <implementation>org.codehaus.plexus.DefaultComponent</implementation>
-+---+
+```
 
- You can specify how your class should be created via the component factory.
- The default is java.  But, there are additional [Component Factories] as well
- for groovy, bsh, and jpython.
+You can specify how your class should be created via the component factory. The default is java. But, there are additional \[Component Factories\] as well for groovy, bsh, and jpython.
 
-+---+
+```
 <component-factory>org.codehaus.plexus.DefaultComponent</component-factory>
-+---+
+```
 
- If you want to use a personality that is not the default personality, you can
- specify a lifecycle handler.  You will need this when you are mixing and
- matching component personalities.
- 
-+---+
+If you want to use a personality that is not the default personality, you can specify a lifecycle handler. You will need this when you are mixing and matching component personalities.
+
+```
 <lifecycle-handler>avalon</lifecycle-handler>
-+---+
+```
 
- Then, there is the instantiation strategy.  This controls how often plexus creates your components.  There are the following options:
+Then, there is the instantiation strategy. This controls how often plexus creates your components. There are the following options:
 
-*-----+------+------+
-|<<Strategy>>|<<Description>>|
-*-----+------+------+
-|per-lookup|Every time you lookup a component one will be created.|
-*-----+------+------+
-|singleton|Only one instance of your component will ever be created.|
-*-----+------+------+
-|keep-alive|This ensures a component is only used as a singleton, and is only shutdown when the container shuts down.|
-*-----+------+------+
-|poolable|Pools several component instances.|
-*-----+------+------+
+|**Strategy**|**Description**||
+|---|---|---|
+|per-lookup|Every time you lookup a component one will be created.||
+|singleton|Only one instance of your component will ever be created.||
+|keep-alive|This ensures a component is only used as a singleton, and is only shutdown when the container shuts down.||
+|poolable|Pools several component instances.||
 
- The default is singleton and you can change the strategy like this:
+The default is singleton and you can change the strategy like this:
 
-+---+
+```
 <instantiation-strategy>per-lookup</instantiation-strategy>
-+---+
+```
diff --git a/src/site/markdown/ref/feature-comparison.md b/src/site/markdown/ref/feature-comparison.md
index abd7dcd..f84a6ce 100644
--- a/src/site/markdown/ref/feature-comparison.md
+++ b/src/site/markdown/ref/feature-comparison.md
@@ -1,69 +1,43 @@
- ------
- Plexus Feature Comparison
- ------
- Brett Porter
- Rahul Thakur
- ------
-2006-05-27
- ------
+---
+title: Plexus Feature Comparison
+author:
+  - Brett Porter
+  - Rahul Thakur
+date: 2006-05-27
+---
 
- <<<The contents of this document are a work in progress>>>
+`The contents of this document are a work in progress`
 
-How does Plexus compare with Spring (1, early 2000)?
+# How does Plexus compare with Spring (1, early 2000)?
 
-  * <<Plexus is simpler and much much smaller than Spring.>>
+- **Plexus is simpler and much much smaller than Spring.**
 
-  The simplest Spring Component which has configuration settings injected is 
-  more complex than in an equivalent case for Plexus as Plexus does not require
-  setters.
+The simplest Spring Component which has configuration settings injected is more complex than in an equivalent case for Plexus as Plexus does not require setters.
 
-  * <<Spring attempts to be a Swiss Army knife.>>
+- **Spring attempts to be a Swiss Army knife.**
 
-  Spring tries to sell itself as a "j2ee framework" and as a Swiss Army knife -
-  one framework for all possible problems. 
-  
-  Plexus is a container that is also usable in the context of application 
-  deployment to the j2ee platform. It also competes with pico/nano containers 
-  at the low end (plexus jars are still under 1 mb).  Plexus Application Server
-  (which is build on top of Plexus container) can be used as a replacement for 
-  j2ee application servers. So for example, users can deploy ftp or http 
-  servers with plexus. Users are free to compose their application only from 
-  the pieces (jars and components) that they really need. Instead of a Swiss 
-  Army knife you can use better tools:  hammer, screwdriver as you need to use 
-  them without having to include them all.
+Spring tries to sell itself as a "j2ee framework" and as a Swiss Army knife - one framework for all possible problems.
 
- * <<Complex component life cycles are not supported in Spring.>>
+Plexus is a container that is also usable in the context of application deployment to the j2ee platform. It also competes with pico/nano containers at the low end (plexus jars are still under 1 mb). Plexus Application Server (which is build on top of Plexus container) can be used as a replacement for j2ee application servers. So for example, users can deploy ftp or http servers with plexus. Users are free to compose their application only from the pieces (jars and components) that they really need. Instead of a Swiss Army knife you can use better tools: hammer, screwdriver as you need to use them without having to include them all.
 
- * <<Spring configuration files are much longer than the one for Plexus.>>
+- **Complex component life cycles are not supported in Spring.**
 
-  Specifically hierarchical configuration settings ala xstream are not
-  supported by Spring.
+- **Spring configuration files are much longer than the one for Plexus.**
 
- * <<Spring is not using IoC for all dependecies of components.>>
+Specifically hierarchical configuration settings ala xstream are not supported by Spring.
 
-  For example Spring is promoting terrible things like logging based on commons-logging,
-  which makes most of the component dependent on an ugly singleton (IoC is 
-  against singletons!) and inevitably leads to incorrect class loader 
-  hierarchies (commons-logging must be in root classloader of the container).
+- **Spring is not using IoC for all dependecies of components.**
 
- * <<Missing notion of "Component identity">>
+For example Spring is promoting terrible things like logging based on commons-logging, which makes most of the component dependent on an ugly singleton (IoC is against singletons!) and inevitably leads to incorrect class loader hierarchies (commons-logging must be in root classloader of the container).
 
-  Spring doesn't allow you to direct logging output from two deployed instances
-  of the same component/bean to different files (unless you use AOP). This is
-  due to the fact that "component identity" is not propagated or understood by
-  the logging system. In Plexus such things are possible - but not yet
-  implemented.
+- **Missing notion of "Component identity"**
 
- * <<Component class loader isolation.>>
+Spring doesn't allow you to direct logging output from two deployed instances of the same component/bean to different files (unless you use AOP). This is due to the fact that "component identity" is not propagated or understood by the logging system. In Plexus such things are possible - but not yet implemented.
 
-  Spring doesn't allow you to easly deploy two distinct components which are 
-  using conflicting version of "the same" jar (e.g. common-collections-2.x and
-  commons-collection-3.x). for their internal stuff.
+- **Component class loader isolation.**
 
- * <<In Plexus you don't have to repeat yourself.>>
+Spring doesn't allow you to easly deploy two distinct components which are using conflicting version of "the same" jar (e.g. common-collections-2.x and commons-collection-3.x). for their internal stuff.
 
-  Component descriptors which are in jars contain the facts which are needed 
-  by the container to manage components. Component personalities provide useful 
-  shortcuts for saying to container this is "avalon component", this is "pico 
-  component", so you don't have to redefine that for every component.
+- **In Plexus you don't have to repeat yourself.**
 
+Component descriptors which are in jars contain the facts which are needed by the container to manage components. Component personalities provide useful shortcuts for saying to container this is "avalon component", this is "pico component", so you don't have to redefine that for every component.
diff --git a/src/site/markdown/ref/plexus-descriptor.md b/src/site/markdown/ref/plexus-descriptor.md
index 902875b..3f34caa 100644
--- a/src/site/markdown/ref/plexus-descriptor.md
+++ b/src/site/markdown/ref/plexus-descriptor.md
@@ -1,11 +1,9 @@
- ------
- Plexus Descriptor - A reference
- ------
- Rahul Thakur
- ------
-2006-06-17
- ------
+---
+title: Plexus Descriptor - A reference
+author: Rahul Thakur
+date: 2006-06-17
+---
 
-Plexus Descriptor Reference
+# Plexus Descriptor Reference
 
- Coming soon...
+Coming soon...
diff --git a/src/site/markdown/ref/plexus-services.md b/src/site/markdown/ref/plexus-services.md
index 93cff2a..af45ee0 100644
--- a/src/site/markdown/ref/plexus-services.md
+++ b/src/site/markdown/ref/plexus-services.md
@@ -1,32 +1,22 @@
- -----
- Plexus Services
- -----
- Rahul Thakur
- -----
-2006-05-05
- -----
+---
+title: Plexus Services
+author: Rahul Thakur
+date: 2006-05-05
+---
 
-Overview 
+# Overview
 
-  What is a Plexus Service? 
+What is a Plexus Service?
 
-  Plexus Service is a Plexus Component implementation that complies with the
-  API contract specified in the <<<org.codehaus.plexus.appserver.service.PlexusService>>> interface and is independent in 
-  itself.
+Plexus Service is a Plexus Component implementation that complies with the API contract specified in the `org.codehaus.plexus.appserver.service.PlexusService` interface and is independent in itself.
 
-  A good example is the Continuum application that is packaged up with Plexus
-  appserver runtime. 
+A good example is the Continuum application that is packaged up with Plexus appserver runtime.
 
-  The Continuum application depends on the Plexus-Jetty service. Plexus-Jetty
-  service needs to be started before the Continuum web application can be 
-  deployed to it.
+The Continuum application depends on the Plexus-Jetty service. Plexus-Jetty service needs to be started before the Continuum web application can be deployed to it.
 
+When the Plexus container loads up a Plexus Service, it expects it to implement the following operations derived from the `PlexusService` interface.
 
-  When the Plexus container loads up a Plexus Service, it expects it to 
-  implement the following operations derived from the <<<PlexusService>>> 
-  interface.
-
-+------+  
+```
   void beforeApplicationStart( AppRuntimeProfile appRuntimeProfile, 
     PlexusConfiguration serviceConfiguration ) throws PlexusServiceException;
   
@@ -37,56 +27,39 @@ Overview
 
   void applicationStop( AppRuntimeProfile runtimeProfile )
     throws PlexusServiceException;
-+------+
-
-  The operations allow a Plexus Service implementation to hook into the 
-  container at runtime. 
+```
 
-  The Plexus container identifies that a Plexus Component is of type Plexus 
-  Service from the ROLE it is assigned. 
+The operations allow a Plexus Service implementation to hook into the container at runtime.
 
-  <<<org.codehaus.plexus.appserver.service.PlexusService>>>
+The Plexus container identifies that a Plexus Component is of type Plexus Service from the ROLE it is assigned.
 
+`org.codehaus.plexus.appserver.service.PlexusService`
 
-Plexus Service Lifecycle
+# Plexus Service Lifecycle
 
-  The operations specified in the PlexusService interface define a Service's 
-  lifecycle.
+The operations specified in the PlexusService interface define a Service's lifecycle.
 
-  When the Plexus runtime loads up a discovered Plexus Service, the lifecycle 
-  hooks are invoked and allow the PlexusService implementation to configure 
-  itself or clean up its resources, as is appropriate for the phase. 
+When the Plexus runtime loads up a discovered Plexus Service, the lifecycle hooks are invoked and allow the PlexusService implementation to configure itself or clean up its resources, as is appropriate for the phase.
 
-  Lets take a look at what the different operation available in the 
-  PlexusService interface are for and how a PlexusService implmentation might 
-  be expected to implement them. 
+Lets take a look at what the different operation available in the PlexusService interface are for and how a PlexusService implmentation might be expected to implement them.
 
-+------+
+```
   void beforeApplicationStart( AppRuntimeProfile appRuntimeProfile, 
     PlexusConfiguration serviceConfiguration ) throws PlexusServiceException;
-+------+
+```
 
-  This Lifecycle operation is called on the loaded Service just before a 
-  target application (i.e, the Plexus Application being started) is marked as
-  STARTED. The Service is expected to initialized and configure itself in this 
-  phase. The Service is said to have STARTED when this operation returns. 
+This Lifecycle operation is called on the loaded Service just before a target application (i.e, the Plexus Application being started) is marked as STARTED. The Service is expected to initialized and configure itself in this phase. The Service is said to have STARTED when this operation returns.
 
-+------+
+```
   void afterApplicationStart( AppRuntimeProfile appRuntimeProfile, 
     PlexusConfiguration serviceConfiguration ) throws PlexusServiceException
-+------+
+```
 
-  This operation is called after the target Plexus application has been 
-  started. <<TODO: Expand more on this >>
+This operation is called after the target Plexus application has been started. **TODO: Expand more on this**
 
-+------+
+```
   void applicationStop( AppRuntimeProfile runtimeProfile )
     throws PlexusServiceException;
-+------+
-
-  This lifecycle operation is called on the loaded service just when the target
-  Plexus application is requested to be stopped. The Service implementation is 
-  expected to clean up its resources in this phase. 
-
-
+```
 
+This lifecycle operation is called on the loaded service just when the target Plexus application is requested to be stopped. The Service implementation is expected to clean up its resources in this phase.
diff --git a/src/site/markdown/ref/technical-articles.md b/src/site/markdown/ref/technical-articles.md
index 15c6e6b..70ad55e 100644
--- a/src/site/markdown/ref/technical-articles.md
+++ b/src/site/markdown/ref/technical-articles.md
@@ -1,11 +1,9 @@
- ------
- Technical Articles and other resources
- ------
- Rahul Thakur
- ------
-2006-06-17
- ------
+---
+title: Technical Articles and other resources
+author: Rahul Thakur
+date: 2006-06-17
+---
 
-List of Technical Articles and Resources on Plexus
+# List of Technical Articles and Resources on Plexus
 
- Coming soon...
+Coming soon...
diff --git a/src/site/markdown/ref/why-use-components.md b/src/site/markdown/ref/why-use-components.md
index 9f3e3dc..f93063e 100644
--- a/src/site/markdown/ref/why-use-components.md
+++ b/src/site/markdown/ref/why-use-components.md
@@ -1,174 +1,123 @@
- ------
- Why Use Components?
- ------
- Brett Porter
- ------
-2006-05-27
- ------
+---
+title: Why Use Components?
+author: Brett Porter
+date: 2006-05-27
+---
 
- <<<The contents of this document are a work in progress>>>
+`The contents of this document are a work in progress`
 
-Introduction
+# Introduction
 
-  You may have walked through the {{{../guides/quick-start/getting-started.html} Five Minute Tutorial}} and wondered
-  why all the component scaffolding was needed, when a simple <<<new CheeseImplementation()>>> would be sufficient.
-  There is a number of reasons why this is helpful for any application design.
+You may have walked through the [ Five Minute Tutorial](../guides/quick-start/getting-started.html) and wondered why all the component scaffolding was needed, when a simple `new CheeseImplementation()` would be sufficient. There is a number of reasons why this is helpful for any application design.
 
-  Here are some of the reasons to use component-oriented programming:
+Here are some of the reasons to use component-oriented programming:
 
-      [[1]] Separation of Concerns
+1. Separation of Concerns
 
-      [[2]] Easier to apply common design patterns
+1. Easier to apply common design patterns
 
-      [[3]] Components are easier to construct and configure
+1. Components are easier to construct and configure
 
-      [[4]] Components are easier to manage
+1. Components are easier to manage
 
-      [[5]] Components are implicitly easier to unit test
+1. Components are implicitly easier to unit test
 
-      [[6]] Components facilitate advanced application architectures without modifying code
+1. Components facilitate advanced application architectures without modifying code
 
-  All of these aspects contribute to <encouraging better application design>. Let's examine each of these in
-  more detail now.
+All of these aspects contribute to _encouraging better application design_. Let's examine each of these in more detail now.
 
-  <<Separation of Concerns>>
+**Separation of Concerns**
 
-  Separation of concerns is a very simple concept that is self explanatory from its name. It is a design pattern
-  that encourages each individual part of a system to have a clear <concern> (which may also be referred to as
-  a <role> or <function>). The boundaries between these parts should also be clear and <well defined>.
+Separation of concerns is a very simple concept that is self explanatory from its name. It is a design pattern that encourages each individual part of a system to have a clear _concern_ (which may also be referred to as a _role_ or _function_). The boundaries between these parts should also be clear and _well defined_.
 
-  Using components will help you in applying separation of concerns to your design. The relationships
-  between components are represented externally, and can be changed without changing the components themselves,
-  so it becomes more natural to deliniate the component design by separate concerns.
+Using components will help you in applying separation of concerns to your design. The relationships between components are represented externally, and can be changed without changing the components themselves, so it becomes more natural to deliniate the component design by separate concerns.
 
-  <<Easier to apply common design patterns>>
+**Easier to apply common design patterns**
 
-  While separation of concerns is the most significant design pattern to appear in a component-oriented design, the use
-  of container functionality can facilitate other design patterns in a simple, consistent manner.
+While separation of concerns is the most significant design pattern to appear in a component-oriented design, the use of container functionality can facilitate other design patterns in a simple, consistent manner.
 
-  For example, the chain of command pattern is very useful in defining a series of actions, and can be achieved by
-  declaring a requirement on a list of component instances.
-~~ This example is demonstrated in the
-~~  {{{./component-requirements.html} Component Requirements Tutorial}}.
+For example, the chain of command pattern is very useful in defining a series of actions, and can be achieved by declaring a requirement on a list of component instances.
 
-  <<Components are easier to construct and configure>>
+<!--  This example is demonstrated in the -->
+<!--   {{{./component-requirements.html} Component Requirements Tutorial}}. -->
+**Components are easier to construct and configure**
 
-  As your application design gets more complicated that the one represented in the tutorial, there will be a
-  number of fields in the components that will need to be populated. Features in containers such as Plexus
-  aid in the construction of your objects, making it faster to develop than before, with less code.
+As your application design gets more complicated that the one represented in the tutorial, there will be a number of fields in the components that will need to be populated. Features in containers such as Plexus aid in the construction of your objects, making it faster to develop than before, with less code.
 
-  So, a component may declare its default configuration, but include an expression that is able to obtain information
-  from the system using it to populate it at runtime, without needing to know anything about the target application
-  at design time. The target application may override the configuration entirely based on its own needs, or even
-  based on other runtime environment factors.
+So, a component may declare its default configuration, but include an expression that is able to obtain information from the system using it to populate it at runtime, without needing to know anything about the target application at design time. The target application may override the configuration entirely based on its own needs, or even based on other runtime environment factors.
 
-  In Plexus, configuration and construction is not limited to setting values on primitive fields either.
-  Complex objects can be configured from XML fragments, as is discussed in the
-  {{{./component-configuration.html} Component Configuration Tutorial}}. Components can also have <other components>
-  configured and injected based on declared <requirements> making construction very simple. These requirements can
-  of course be altered by target applications that may wish to substitute different implementations.
+In Plexus, configuration and construction is not limited to setting values on primitive fields either. Complex objects can be configured from XML fragments, as is discussed in the [ Component Configuration Tutorial](./component-configuration.html). Components can also have _other components_ configured and injected based on declared _requirements_ making construction very simple. These requirements can of course be altered by target applications that may wish to substitute different implementations.
 
-  <<Components are easier to manage>>
+**Components are easier to manage**
 
-  Not only are components easier to construct, but in a good component container such as Plexus they will also be
-  easier to manage through their life within the application.
+Not only are components easier to construct, but in a good component container such as Plexus they will also be easier to manage through their life within the application.
 
-  In Java, you only have control over construction (calling the constructor) and calling methods on the object (or
-  modifying fields). Other behaviour such as finalization is not called predictably and can not be used to perform
-  object clean up, for example.
+In Java, you only have control over construction (calling the constructor) and calling methods on the object (or modifying fields). Other behaviour such as finalization is not called predictably and can not be used to perform object clean up, for example.
 
-  In containers that support component lifecycles, such as Plexus, the component author has control over all aspects of
-  a component's lifecycle. For example, the component can be consulted when the component has been <initialized>,
-  <started>, <stopped>, or <destroyed> to name a few. In Plexus, not only can the components participate in the
-  lifecycle, but a component's lifecycle can be completely customised.
+In containers that support component lifecycles, such as Plexus, the component author has control over all aspects of a component's lifecycle. For example, the component can be consulted when the component has been _initialized_, _started_, _stopped_, or _destroyed_ to name a few. In Plexus, not only can the components participate in the lifecycle, but a component's lifecycle can be completely customised.
 
-  The ability to participate in the component lifecycle can enable the component author to perform necessary
-  set up and clean up, and also to easily apply some design patterns to a component without having to recode
-  the component state handling.
+The ability to participate in the component lifecycle can enable the component author to perform necessary set up and clean up, and also to easily apply some design patterns to a component without having to recode the component state handling.
 
-  Component lifecycles in Plexus are discussed in the {{{./components.html} Components Tutorial}}.
-~~ as well as the
-~~  {{{../documentation/component-lifecycle.html} Component Lifecycle}} documentation.
+Component lifecycles in Plexus are discussed in the [ Components Tutorial](./components.html).
 
-  <<Components are implicitly easier to unit test>>
+<!--  as well as the -->
+<!--   {{{../documentation/component-lifecycle.html} Component Lifecycle}} documentation. -->
+**Components are implicitly easier to unit test**
 
-  The above traits lead to making components easier to unit test. When testing code, it is usualy expected that it
-  is tested in isolation, so that the tests are not influenced by external factors and so that the tests are simpler
-  and easier to write. Through separation of concerns, this becomes a reality.
+The above traits lead to making components easier to unit test. When testing code, it is usualy expected that it is tested in isolation, so that the tests are not influenced by external factors and so that the tests are simpler and easier to write. Through separation of concerns, this becomes a reality.
 
-  In addition, since component construction and configuration can be altered, it is easy to replace default
-  implementations of other components with simple mocks or stubs that guarantee that you are testing a single
-  component at a time.
+In addition, since component construction and configuration can be altered, it is easy to replace default implementations of other components with simple mocks or stubs that guarantee that you are testing a single component at a time.
 
-  Tests generally require quite a lot of object configuration, much of which is duplicated for all but one or two
-  values. Using a component container can dramatically ease this through having pre-set configurations that are
-  modified on a per-test basis.
+Tests generally require quite a lot of object configuration, much of which is duplicated for all but one or two values. Using a component container can dramatically ease this through having pre-set configurations that are modified on a per-test basis.
 
-  Finally, since component tests can be run inside the container, the lifecycle of the component can be executed as it
-  would in the real system, without needing to construct the calling objects. This again makes it easier to test a
-  component in isolation.
+Finally, since component tests can be run inside the container, the lifecycle of the component can be executed as it would in the real system, without needing to construct the calling objects. This again makes it easier to test a component in isolation.
 
-  While components can usually be tested by conventional means, Plexus comes with a testing harness that simplifies
-  the process of performing the regular component construction and lifecycle, running them in-container. This is
-  discussed in the {{{/guides/developer-guide/building-components/component-testing.html} Component Testing}} section of the developer guide.
+While components can usually be tested by conventional means, Plexus comes with a testing harness that simplifies the process of performing the regular component construction and lifecycle, running them in-container. This is discussed in the [ Component Testing](/guides/developer-guide/building-components/component-testing.html) section of the developer guide.
 
-  <<Components facilitate advanced application architectures without modifying code>>
+**Components facilitate advanced application architectures without modifying code**
 
-  Clear separation of components, along with well-defined interfaces, allow replacing components with other
-  implementations. This can facilitate advanced application architectures without code modifications.
+Clear separation of components, along with well-defined interfaces, allow replacing components with other implementations. This can facilitate advanced application architectures without code modifications.
 
-  An example of this can be seen in Apache Geronimo's GBuild, which is built on
-  {{{http://continuum.apache.org/} Apache Continuum}}, a Plexus application. By replacing some components with
-  identical functionality that works with ActiveMQ, a distributed countinuous integration server was built.
+An example of this can be seen in Apache Geronimo's GBuild, which is built on [ Apache Continuum](http://continuum.apache.org/), a Plexus application. By replacing some components with identical functionality that works with ActiveMQ, a distributed countinuous integration server was built.
 
-  Additionally, the container can provide features that can be applied to all components consistently without code
-  modifications. For example, Plexus can resolve components transparently at runtime from a Maven repository.
+Additionally, the container can provide features that can be applied to all components consistently without code modifications. For example, Plexus can resolve components transparently at runtime from a Maven repository.
 
-What are Components?
+# What are Components?
 
-  {{{http://www.amazon.com/exec/obidos/ASIN/0201745720/qid%3D1090125966/sr%3D11-1/ref%3Dsr%5F11%5F1/104-8989869-2491134} Szyperski}}
-  lists several characteristics of components: composition, units of deployment and resuability.
+[ Szyperski](http://www.amazon.com/exec/obidos/ASIN/0201745720/qid%3D1090125966/sr%3D11-1/ref%3Dsr%5F11%5F1/104-8989869-2491134) lists several characteristics of components: composition, units of deployment and resuability.
 
-  Other projects have also offered what a component may be:
+Other projects have also offered what a component may be:
 
-    * {{{http://picocontainer.codehaus.org/Inversion+of+Control} PicoContainer}}
+- [ PicoContainer](http://picocontainer.codehaus.org/Inversion\+of\+Control)
 
-    * {{{http://avalon.apache.org/central/cop/index.html} Avalon}}
+- [ Avalon](http://avalon.apache.org/central/cop/index.html)
 
-    * {{{http://c2.com/cgi/wiki?ComponentOrientedProgramming} C2 - Component Oriented Programming}}
+- [ C2 - Component Oriented Programming](http://c2.com/cgi/wiki?ComponentOrientedProgramming)
 
-  Some descriptions of a component are:
+Some descriptions of a component are:
 
-    * A nontrivial, nearly independent, and replaceable part of a system that fulfils a clear function in the context
-      of a well-defined architecture. A component conforms to and provides the physical realization of a set of
-      interfaces. (Philippe Krutchen, Rational Software)
+- A nontrivial, nearly independent, and replaceable part of a system that fulfils a clear function in the context of a well-defined architecture. A component conforms to and provides the physical realization of a set of interfaces. (Philippe Krutchen, Rational Software)
 
-    * A runtime software component is a dynamically bindable package of one or more programs managed as a unit and
-      accessed through documented interfaces that can be discovered at runtime. (Gartner Group)
+- A runtime software component is a dynamically bindable package of one or more programs managed as a unit and accessed through documented interfaces that can be discovered at runtime. (Gartner Group)
 
-    * A software component is a unit of composition with contractually specified interfaces and explicit context
-      dependencies only. A software component can be deployed independently and is subject to third-party
-      composition. (Clemens Szyperski, <"Component Software">)
+- A software component is a unit of composition with contractually specified interfaces and explicit context dependencies only. A software component can be deployed independently and is subject to third-party composition. (Clemens Szyperski, _"Component Software"_)
 
-    * A self-contained piece of software that can be independently deployed and plugged into an environment that
-      provides a compatible socket. It has well-defined run-time interfaces, and it can cooperate out of the box
-      with other components (Peter Herzum, Olivier Sims, <"Business Component Factory">)
+- A self-contained piece of software that can be independently deployed and plugged into an environment that provides a compatible socket. It has well-defined run-time interfaces, and it can cooperate out of the box with other components (Peter Herzum, Olivier Sims, _"Business Component Factory"_)
 
-* Criteria for Components
+## Criteria for Components
 
-  Meyer: {{{http://www.sdmagazine.com/documents/s=746/sdm0003k/0003k.htm} <"Seven Criteria for Components">}}
+Meyer: [ _"Seven Criteria for Components"_](http://www.sdmagazine.com/documents/s\=746/sdm0003k/0003k.htm)
 
-    * May be used by other software elements (clients).
+- May be used by other software elements (clients).
 
-    * May be used by clients without the intervention of the component's developers.
+- May be used by clients without the intervention of the component's developers.
 
-    * Includes a specification of all dependencies (hardware and software platform, versions, other components).
+- Includes a specification of all dependencies (hardware and software platform, versions, other components).
 
-    * Includes a precise specification of the functionalities it offers.
+- Includes a precise specification of the functionalities it offers.
 
-    * Is usable on the sole basis of that specification.
+- Is usable on the sole basis of that specification.
 
-    * Is composable with other components.
-
-    * Can be integrated into a system quickly and smoothly.
+- Is composable with other components.
 
+- Can be integrated into a system quickly and smoothly.