diff --git a/src/site/fml/faq.fml b/src/site/fml/faq.fml
deleted file mode 100644
index 3b54898517..0000000000
--- a/src/site/fml/faq.fml
+++ /dev/null
@@ -1,116 +0,0 @@
-<!--
-Licensed to the Apache Software Foundation (ASF) under one
-or more contributor license agreements.  See the NOTICE file
-distributed with this work for additional information
-regarding copyright ownership.  The ASF licenses this file
-to you under the Apache License, Version 2.0 (the
-"License"); you may not use this file except in compliance
-with the License.  You may obtain a copy of the License at
-
-  http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing,
-software distributed under the License is distributed on an
-"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-KIND, either express or implied.  See the License for the
-specific language governing permissions and limitations
-under the License.
--->
-<faqs id="FAQ" title="Frequently Asked Questions">
-  <part id="general">
-    <title>General</title>
-
-    <faq id="versions">
-      <question>What does the Versions Maven Plugin do?</question>
-      <answer>
-        <p>The Versions Maven Plugin provides a means to update version information in a Maven project</p>
-      </answer>
-    </faq>
-
-    <faq id="comparisonMethod">
-      <question>Why is this plugin reporting version 1.0.0.9 of foo:bar as the latest version when I can see
-        version 1.0.0.23?
-      </question>
-      <answer>
-        <p>The current implementation of
-          <a href="http://maven.apache.org/ref/current/maven-artifact/xref/org/apache/maven/artifact/versioning/DefaultArtifactVersion.html">
-            <code>DefaultArtifactVersion</code>
-          </a>
-          in the core of Maven expects that version numbers will have a very
-          specific format:
-        </p>
-        <p>
-          <i>MajorVersion [</i>
-          <code>.</code>
-          <i>MinorVersion [</i>
-          <code>.</code>
-          <i>IncrementalVersion ] ] [</i>
-          <code>-</code>
-          <i>BuildNumber | Qualifier ]</i>
-        </p>
-        <p>Where<i>MajorVersion</i>,<i>MinorVersion</i>,<i>IncrementalVersion</i>, and
-          <i>BuildNumber</i>
-          are all
-          numeric and
-          <i>Qualifier</i>
-          is a string. If your version number does not match this format, then the entire
-          version number is treated as being the<i>Qualifier</i>.
-        </p>
-        <p>Version numbers in maven are compared using the individual components, so<i>MajorVersion</i>,<i>
-          MinorVersion</i>,<i>IncrementalVersion</i>, and
-          <i>BuildNumber</i>
-          are all compared as<code>Integer</code>s
-          while
-          <i>Qualifier</i>
-          is compared as a<code>String</code>.
-        </p>
-        <p>From the above you may have guessed neither
-          <code>1.0.0.9</code>
-          nor
-          <code>1.0.0.23</code>
-          match the exact
-          format that Maven expects, and as a result they are mapped as being just a<i>Qualifier</i>.
-          String comparison will sort
-          <code>1.0.0.9</code>
-          &gt;<code>1.0.0.23</code>.
-        </p>
-        <p>If you need version numbers to be sorted "correctly" you will need to define some
-          <a href="version-rules.html">
-            version number comparison rules
-          </a>.
-        </p>
-      </answer>
-    </faq>
-    <faq id="repo-metadata">
-      <question>Why is foo:bar version x.y.z not being detected?</question>
-      <answer>
-        <p>
-          In order to determine what versions of an artifact are present, Maven relies on the presence of
-          meta-data files in the repository.  If the meta-data files are missing or contain invalid information
-          then Maven will not know about versions that are available in your repositories.
-        </p>
-        <p>
-          Here are some common reasons why your metadata can be invalid:
-        </p>
-        <ul>
-          <li>
-            You are using a local repository as a remote repository. Stop, don't do this. The local repository
-            uses a separate set of metadata files from those used by a remote repository. There are tools available
-            to convert a local repository into a remote repository, but you're really better off using a repository
-            manager.
-          </li>
-          <li>
-            Artifacts have been deployed by non-maven metadata aware tools.
-          </li>
-          <li>
-            Tools that claim to be maven meta-data aware have clobbered the metadata files.
-          </li>
-        </ul>
-        <p>
-          In most cases, using a repository manager will solve these issues as the repository managers usually
-          rebuild the metadata files based on the artifacts that are present.
-        </p>
-      </answer>
-    </faq>
-  </part>
-</faqs>
diff --git a/src/site/markdown/faq.md b/src/site/markdown/faq.md
new file mode 100644
index 0000000000..b7872d5d7c
--- /dev/null
+++ b/src/site/markdown/faq.md
@@ -0,0 +1,66 @@
+title: FAQ
+autor: Stephen Connolly
+
+<!---
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+  https://www.apache.org/licenses/LICENSE-2.0
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Frequently Asked Questions
+
+## General
+
+### What does the Versions Maven Plugin do?
+
+The Versions Maven Plugin provides a means to update version information in a Maven project
+
+### Why is this plugin reporting version 1.0.0.9 of foo:bar as the latest version when I can see version 1.0.0.23?
+
+The current implementation of
+[DefaultArtifactVersion](https://maven.apache.org/ref/current/maven-artifact/xref/org/apache/maven/artifact/versioning/DefaultArtifactVersion.html)
+in the core of Maven expects that version numbers will have a very specific format:
+
+` <MajorVersion [> . <MinorVersion [> . <IncrementalVersion ] ] [> - <BuildNumber | Qualifier ]> `
+
+Where *MajorVersion*, *MinorVersion*, *IncrementalVersion* and *BuildNumber* are all numeric and *Qualifier*
+is a string. If your version number does not match this format, then the entire version number is treated as being 
+the *Qualifier*.
+
+Version numbers in maven are compared using the individual components, so *MajorVersion*, *MinorVersion*,
+*IncrementalVersion*, and *BuildNumber* are all compared as `Integer`s while *Qualifier* is compared as a `String`.
+
+From the above you may have guessed neither `1.0.0.9` nor `1.0.0.23` match the exact format that Maven expects,
+and as a result they are mapped as being just a *Qualifier*. String comparison will sort `1.0.0.9` > `1.0.0.23`.
+
+If you need version numbers to be sorted "correctly" you will need to define some
+[version number comparison rules](./version-rules.html).
+
+### Why is foo:bar version x.y.z not being detected?
+
+In order to determine what versions of an artifact are present, Maven relies on the presence of
+meta-data files in the repository.  If the meta-data files are missing or contain invalid information
+then Maven will not know about versions that are available in your repositories.
+
+Here are some common reasons why your metadata can be invalid:
+
+- You are using a local repository as a remote repository. Stop, don't do this. The local repository
+uses a separate set of metadata files from those used by a remote repository. There are tools available
+to convert a local repository into a remote repository, but you're really better off using a repository
+manager.
+- Artifacts have been deployed by non-maven metadata aware tools.
+- Tools that claim to be maven meta-data aware have clobbered the metadata files.
+
+In most cases, using a repository manager will solve these issues as the repository managers usually
+rebuild the metadata files based on the artifacts that are present.