From 6a1872e4f68a0e367b2862a2291127d30333b585 Mon Sep 17 00:00:00 2001 From: Sylwester Lachiewicz Date: Mon, 10 Aug 2026 01:44:19 +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 cee8c2996af7a1dcac525f66a29aa98088c60815 Mon Sep 17 00:00:00 2001 From: Sylwester Lachiewicz Date: Mon, 10 Aug 2026 02:03:00 +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 routes every through DoxiaUtils.encodeId, which rewrites an id that is not a valid XML name: a space becomes '_' and any other character becomes its dot-prefixed UTF-8 bytes, so ',' becomes .2C and '?' becomes .3F. The elements emitted here reproduce that rendered form, not the raw attribute, so the live URLs still resolve. Verified by building the site before and after and comparing the set of anchors the generated faq.html actually serves. All 3 anchors present before are still present after (5 after, the extra ones being the ids Doxia derives from the new headings): bodyColumn question top 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. The question renders as an h3 heading rather than a definition term. Those are the only rendering losses. Anchors are written as , not : maven-site-plugin 3.21.0 drops the name attribute from inline HTML anchors while 3.22.0 keeps it, and Xhtml5BaseParser reads Attribute.ID first and only falls back to NAME. id is the primary path and the correct HTML5 form; name on is obsolete. An explicit anchor is emitted only where it is actually needed. Doxia already derives an id for each heading, and where that derived id is byte-identical to the anchor the site serves today, a second explicit anchor would only produce a duplicate id and a "used more than once" warning. Those are omitted; the heading serves the URL. The anchors that remain are the ones where the FML id and the question text differ, and the page would otherwise lose the URL. Generated-by: Claude Opus 5 (1M context) --- src/site/markdown/faq.md | 31 ++++++++++++++----------------- 1 file changed, 14 insertions(+), 17 deletions(-) diff --git a/src/site/markdown/faq.md b/src/site/markdown/faq.md index e94afa96..6e21e6ad 100644 --- a/src/site/markdown/faq.md +++ b/src/site/markdown/faq.md @@ -1,4 +1,6 @@ - +--- +title: Frequently Asked Questions +--- + - - - - Can I use the install:install-file goal to install artifacts to my remote repository? - -

- No. You need to use - deploy:deploy-file instead. -

- - - - +# Frequently Asked Questions + +1. [Can I use the *install:install-file* goal to install artifacts to my remote repository?](#question) + + + +### Can I use the *install:install-file* goal to install artifacts to my remote repository? + +No. You need to use +[*deploy:deploy-file*](http://maven.apache.org/plugins/maven-deploy-plugin/) instead.