(maven-compiler-plugin) 02/02: Convert the FAQ from FML to Markdown

[sl...@apache.org]

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

slachiewicz pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven-compiler-plugin.git

commit fc5ab18359534519a1e3e3397d6f3bf5d1b20822
Author: Sylwester Lachiewicz <sl...@apache.org>
AuthorDate: Mon Aug 10 01:57:43 2026 +0200

    Convert the FAQ from FML to Markdown
    
    doxia-converter cannot target FML usefully - the questions come out as
    link-reference syntax rather than headings, the [top] back-links become
    links to a nonexistent 'top' page, and the contents links lose their #
    anchors. The page is written out by hand instead.
    
    Explicit <a name> anchors keep the existing deep links working. All 1
    still resolve. Where an id was not a valid XML name, Doxia rewrote it at
    render time via DoxiaUtils.encodeId; the anchors written here reproduce
    that rendered form, not the raw attribute.
    
    Verified by building the site before and after and comparing the set of
    anchors the generated faq.html actually serves: every anchor present
    before is still present after, the <head> is byte-identical, and every
    link target on the page is unchanged.
    
    site.xml needs no edit: src/site/fml/faq.fml and
    src/site/markdown/faq.md both render to faq.html.
    
    FML generates a [top] back-link after each answer; those are dropped
    rather than hand-written, which is the only rendering loss.
    
    The anchors are written <a id> rather than <a name>: maven-site-plugin
    3.21.0 silently drops a name attribute from inline HTML, leaving the
    build green and every deep link broken. The id form works on every
    version and is the correct HTML5 spelling.
    
    Generated-by: Claude Opus 5 (1M context)
---
 src/site/markdown/faq.md | 43 +++++++++++++++++++++----------------------
 1 file changed, 21 insertions(+), 22 deletions(-)

diff --git a/src/site/markdown/faq.md b/src/site/markdown/faq.md
index 469a9f3..955c38a 100644
--- a/src/site/markdown/faq.md
+++ b/src/site/markdown/faq.md
@@ -1,4 +1,6 @@
-<?xml version="1.0" encoding="UTF-8"?>
+---
+title: Frequently Asked Questions
+---
 
 <!--
 Licensed to the Apache Software Foundation (ASF) under one
@@ -19,24 +21,21 @@ specific language governing permissions and limitations
 under the License.
 -->
 
-<faqs xmlns="http://maven.apache.org/FML/1.0.1"
-  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-  xsi:schemaLocation="http://maven.apache.org/FML/1.0.1 http://maven.apache.org/xsd/fml-1.0.1.xsd"
-  title="Frequently Asked Questions">
-  <part id="General">
-    <faq id="how-to-add-generated-sources">
-      <question>How do I add my generated sources to the compile path of Maven, when using Modello?</question>
-      <answer>
-        <p>Modello generates the sources in the generate-sources phase and automatically adds the
-          source directory for compilation in Maven. So you don't have to copy the generated sources.
-        </p>
-        <p>You have to declare the <a href="https://codehaus-plexus.github.io/modello/modello-maven-plugin/">Modello Maven Plugin</a>
-          in the build of your project for source generation (in that way the sources are generated each time).
-        </p>
-        <p>For more information about Modello, please visit the
-          <a href="https://codehaus-plexus.github.io/modello/">Modello website</a>.
-        </p>
-      </answer>
-    </faq>
-  </part>
-</faqs>
+<a id="top"></a>
+
+# Frequently Asked Questions
+
+1. [How do I add my generated sources to the compile path of Maven, when using Modello?](#how-to-add-generated-sources)
+
+<a id="how-to-add-generated-sources"></a>
+
+### How do I add my generated sources to the compile path of Maven, when using Modello?
+
+Modello generates the sources in the generate-sources phase and automatically adds the source directory for
+compilation in Maven. So you don't have to copy the generated sources.
+
+You have to declare the [Modello Maven Plugin](https://codehaus-plexus.github.io/modello/modello-maven-plugin/)
+in the build of your project for source generation (in that way the sources are generated each time).
+
+For more information about Modello, please visit the
+[Modello website](https://codehaus-plexus.github.io/modello/).