diff --git a/src/site/markdown/BndBuild.md b/src/site/markdown/BndBuild.md
index 03510b47b1..f3ee54d3df 100644
--- a/src/site/markdown/BndBuild.md
+++ b/src/site/markdown/BndBuild.md
@@ -1,8 +1,8 @@
-## BND Workspace Layout and Pomless Builds
+# BND Workspace Layout and Pomless Builds
 
 Tycho supports building projects that use the **BND Workspace Layout** as [described here](https://bndtools.org/concepts.html).
 
-### BND Workspace Layout
+## BND Workspace Layout
 A BND Workspace layout build layout usually has the following structure:
 
 - `root folder` - this usually is the root of your project repository (e.g. git)
@@ -17,7 +17,7 @@ A BND Workspace layout build layout usually has the following structure:
 
 any folder that do not match the layout is ignored.
 
-### Pomless Builds
+## Pomless Builds
 Given the above layout, Tycho now has a good knowledge about what your build artifacts are.
 In contrast to a traditional maven build where each module has to contain a `pom.xml` file Tycho can derive most all from your supplied bnd configuration files, so everything is configured there and usually no additional maven configuration is required, therefore this build is completely pomless (no pom.xml), there are only a few steps to consider:
 
@@ -45,7 +45,7 @@ In contrast to a traditional maven build where each module has to contain a `pom
 A runnable demo can be found here:
 https://github.com/eclipse-tycho/tycho/tree/master/demo/bnd-workspace
 
-### Mixed Builds
+## Mixed Builds
 
 You can even combine a BND Workspace and PDE bundles in a build, a runnable demo can be found here:
 https://github.com/eclipse-tycho/tycho/tree/master/demo/bnd-pde-workspace
\ No newline at end of file
diff --git a/src/site/markdown/BuildProperties.md b/src/site/markdown/BuildProperties.md
index 911ef838e1..80e1f69ed4 100644
--- a/src/site/markdown/BuildProperties.md
+++ b/src/site/markdown/BuildProperties.md
@@ -1,4 +1,4 @@
-## Build Properties
+# Build Properties
 
 Tycho uses the `build.properties` file [as defined by PDE](https://help.eclipse.org/latest/index.jsp?topic=/org.eclipse.pde.doc.user/reference/pde_feature_generating_build.htm) to configure various aspects of the build.
 
@@ -15,7 +15,7 @@ These expressions are only used in a Tycho build, not when using the Eclipse IDE
 
 See the table below for which keys in `build.properties` defined by PDE are supported by Tycho or if not, whether there are alternatives when using Tycho.
 
-### Common Properties
+## Common Properties
 
 Key | Value
 --- | ---
@@ -25,7 +25,7 @@ qualifier    | not supported - use [Build Qualifer Mojo](tycho-packaging-plugin/
 forceContextQualifier | supported
 custom*      | not supported
 
-### Plugin-specific properties
+## Plugin-specific properties
 
 Key | Value
 --- | ---
@@ -41,7 +41,7 @@ jars.compile.order | supported
 additional.bundles | supported (since Tycho 2.4.0)
 
 
-### Compiler-specific properties
+## Compiler-specific properties
 
 Key | Value
 --- | ---
@@ -60,7 +60,7 @@ compilerAdapter.useLog | not supported
 compilerAdapter.useArgFile | not supported
 sourceFileExtensions | not supported - use [excludeResources](tycho-compiler-plugin/compile-mojo.html#excludeResources) instead
 
-### Feature-specific properties
+## Feature-specific properties
 
 Key | Value
 --- | ---
diff --git a/src/site/markdown/StructuredBuild.md b/src/site/markdown/StructuredBuild.md
index bf3a23548f..dbd8a8b5f7 100644
--- a/src/site/markdown/StructuredBuild.md
+++ b/src/site/markdown/StructuredBuild.md
@@ -1,8 +1,8 @@
-## Structured Build Layout and Pomless Builds
+# Structured Build Layout and Pomless Builds
 
 Tycho supports any layout of your build, but you can save you a lot of configuration work if you are using the so called **Structured Build Layout**.
 
-### Structured Build Layout
+## Structured Build Layout
 A structured build layout usually has the following folder layout, even though you might not use all of the depending on your project:
 
 - `root folder` - this usually contains your parent pom where you configure the plugins to use
@@ -21,7 +21,7 @@ A structured build layout usually has the following folder layout, even though y
         - `...`
 - `target-platform.target` the target platform that should be used
 
-### Pomless Builds
+## Pomless Builds
 Given the above layout, Tycho now has a good knowledge about what your build artifacts are.
 In contrast to a traditional maven build where each module has to contain a `pom.xml` file Tycho can derive most if not all from your existing data, that is the files you are created and using in our IDE, 
 there are only a few steps to consider:
diff --git a/src/site/markdown/SystemProperties.md b/src/site/markdown/SystemProperties.md
index d89a3e3dc9..6e8ed20a8b 100644
--- a/src/site/markdown/SystemProperties.md
+++ b/src/site/markdown/SystemProperties.md
@@ -1,11 +1,11 @@
-## System Properties
+# System Properties
 
 Tycho understands some system properties beyond the ones documented in the respective goals to fine-tune certain behavior and to help with troubleshooting.
 
 Disclaimer: This page is incomplete.
 
 
-### Common Properties
+## Common Properties
 
 These properties are understood by the Tycho-core and affect all maven plugins:
 
@@ -13,21 +13,21 @@ Name | Value | Documentation
 --- | --- | ---
 tycho.mode | `maven` | Completely disables the Tycho lifecycle participant in Maven. For standard Tycho use-cases this is typically not necessary, since e.g. the `clean` goal already disables this. However, this can be useful when explicitly invoking external goals, e.g. `mvn -Dtycho.mode=maven com.foo.bar:some-plugin:some-goal`, in order to improve performance.
 
-### Troubleshooting
+## Troubleshooting
 
 Name | Value | Documentation
 --- | --- | ---
 tycho.debug.artifactcomparator | _any_ | In `tycho-p2-plugin`, output verbose artifact comparison information during baseline validation
 tycho.debug.resolver | `true` or _artifactId_ | Enable debug output for the artifact resolver for all projects or the project with the given _artifactId_
 
-### Baseline compare
+## Baseline compare
 
 Name | Value | Default | Documentation
 --- | --- | --- | ---
 tycho.comparator.showDiff | true / false | false | If set to true if text-like files show a unified diff of possible differences in files
 tycho.comparator.threshold | bytes | 5242880 (~5MB) | gives the number of bytes for content to be compared semantically, larger files will only be compared byte-by-byte
 
-### P2
+## P2
 
 These properties control the behaviour of P2 used by Tycho
 
diff --git a/src/site/markdown/TestingBundles.md b/src/site/markdown/TestingBundles.md
index 5d88f97025..b0ef2f713b 100644
--- a/src/site/markdown/TestingBundles.md
+++ b/src/site/markdown/TestingBundles.md
@@ -1,8 +1,8 @@
-## Testing Bundles / Plugins with Tycho
+# Testing Bundles / Plugins with Tycho
 
 There are different ways to test bundles / plug-ins with Tycho:
 
-### maven-surefire-plugin
+## maven-surefire-plugin
 
 Using [maven-surefire-plugin](https://maven.apache.org/surefire/maven-surefire-plugin/) is the preferred way whenever you want to write a plain unit-test.
 This is a unit test that either:
@@ -47,7 +47,7 @@ The following demo projects are provided as an example:
 - Project using maven standard layout: https://github.com/eclipse-tycho/tycho/tree/master/demo/testing/surefire/with-maven-layout
 
 
-### tycho-surefire-plugin
+## tycho-surefire-plugin
 
 The [tycho-surefire-plugin](https://tycho.eclipseprojects.io/doc/master/tycho-surefire-plugin/plugin-info.html) is the preferred whenever you want to write tests
 that require an OSGi Framework running and is executed in the integration-test phase of your build, this is similar to what PDE offers as Plugin Tests.
@@ -92,7 +92,7 @@ https://github.com/eclipse-tycho/tycho/tree/master/demo/testing/tycho/standalone
 - Project using maven standard layout having the tests in the same module: 
 https://github.com/eclipse-tycho/tycho/tree/master/demo/testing/tycho/samemodule
 
-### bnd-testing
+## bnd-testing
 
 The [tycho-surefire-plugin](https://tycho.eclipseprojects.io/doc/master/tycho-surefire-plugin/plugin-info.html) has also support for [bnd-testing](https://bnd.bndtools.org/chapters/310-testing.html),
 this is like `plugin-test` but uses the BND testing framework. There is currently no JDT/PDE equivalent but this integrates nicely with the [OSGi Testing Support](https://github.com/osgi/osgi-test) and allows to execute prebuild test-bundles.
@@ -132,6 +132,6 @@ to automatically inject services:
 
 
 
-### combining different approaches 
+## combining different approaches 
 
-### setup test source folders in eclipse
+## setup test source folders in eclipse
diff --git a/src/site/markdown/TychoCiFriendly.md b/src/site/markdown/TychoCiFriendly.md
index ba8db7a36e..c1e9c86d4f 100644
--- a/src/site/markdown/TychoCiFriendly.md
+++ b/src/site/markdown/TychoCiFriendly.md
@@ -1,4 +1,4 @@
-## Tycho CI Friendly Versions
+# Tycho CI Friendly Versions
 
 Starting with Maven 3.8.5 Tycho now supports an enhanced form of the [Maven CI Friendly Versions](https://maven.apache.org/maven-ci-friendly.html) beside the standard properties names one could also use:
 
diff --git a/src/site/markdown/TychoProperties.md b/src/site/markdown/TychoProperties.md
index 3837a55512..d838f1b0cf 100644
--- a/src/site/markdown/TychoProperties.md
+++ b/src/site/markdown/TychoProperties.md
@@ -1,10 +1,10 @@
-## Tycho Properties
+# Tycho Properties
 
 Maven provides a set of properties like `project.version` or `project.basedir` that could be used within pom files e.g. to configure the plugins.
 Tycho provides its own set of additional properties.
 
 
-### Tycho Environment Properties
+## Tycho Environment Properties
 
 These properties are set based on the platform where Tycho gets executed: