From a8da7229621a513b6755473c9fec7208641e6d1c Mon Sep 17 00:00:00 2001 From: Sylwester Lachiewicz Date: Mon, 10 Aug 2026 01:11:13 +0200 Subject: [PATCH 1/2] Rename the FAQ ahead of converting it 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. Please merge or rebase rather than squash. Generated-by: Claude Opus 5 (1M context) --- src/site/{fml/faq.fml => markdown/faq.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename src/site/{fml/faq.fml => markdown/faq.md} (100%) diff --git a/src/site/fml/faq.fml b/src/site/markdown/faq.md similarity index 100% rename from src/site/fml/faq.fml rename to src/site/markdown/faq.md From 5907bd5ddbfa87d2935213f1e5adb3944c00c059 Mon Sep 17 00:00:00 2001 From: Sylwester Lachiewicz Date: Mon, 10 Aug 2026 01:12:10 +0200 Subject: [PATCH 2/2] 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 anchors keep the existing deep links working. FML renders as the anchor #Configure_Reproducible_Builds, because DoxiaUtils.encodeId rewrites an id that is not a valid XML name. The emitted here reproduces that rendered form, not the raw attribute, so the live URL still resolves. 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: before: Configure_Reproducible_Builds, top, bodyColumn after: the same three, plus two heading-derived ids The is byte-identical, so the title and metadata are 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 rather than : 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 | 27 ++++++++++++++------------- 1 file changed, 14 insertions(+), 13 deletions(-) diff --git a/src/site/markdown/faq.md b/src/site/markdown/faq.md index 0f95fa6..52a395b 100644 --- a/src/site/markdown/faq.md +++ b/src/site/markdown/faq.md @@ -1,4 +1,6 @@ - +--- +title: Frequently Asked Questions +--- - - - - How to configure my Maven build for Reproducible Builds? - -

See the Configuring for Reproducible Builds guide.

- - - - + + +# Frequently Asked Questions + +1. [How to configure my Maven build for Reproducible Builds?](#Configure_Reproducible_Builds) + + + +### How to configure my Maven build for Reproducible Builds? + +See the [Configuring for Reproducible Builds guide](/guides/mini/guide-reproducible-builds.html).