Convert the FAQ from FML to Markdown - #243
Merged
Merged
Conversation
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)
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 id> anchors keep the existing deep links working. All ten 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. Three questions carry no explicit anchor, because for those the id Doxia already derives from the heading text is byte-identical to the anchor the FML page served. Emitting one as well would put the same id on the page twice - invalid HTML, and Doxia warns "Anchor name ... used more than once". The heading supplies those three on its own. 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, no id appears twice, 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. Generated-by: Claude Opus 5 (1M context)
slachiewicz
force-pushed
the
faq-to-markdown
branch
from
August 10, 2026 00:40
a5c406f to
8957258
Compare
slachiewicz
marked this pull request as ready for review
August 10, 2026 01:09
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Part of the estate-wide move of the remaining FAQ pages from FML to Markdown, following the pattern reviewed in apache/maven-artifact-plugin#231, apache/maven-assembly-plugin#1354 and apache/maven-javadoc-plugin#1358.
Two commits, deliberately
src/site/fml/faq.fml->src/site/markdown/faq.md, no content change.Git records a rename plus a rewrite in one commit as a delete and an add, which stops
git log --follow. Splitting them keeps the history. Please merge or rebase rather than squash.Anchors are preserved, and that is the point
This page has been on maven.apache.org for years and is linked from outside. FML derives its anchor from the
<faq id=...>attribute, and where that attribute is not a valid XML nameDoxiaUtils.encodeIdrewrites it at render time. The<a id>elements here reproduce the anchor the live site serves today, not the raw attribute.The
idspelling is deliberate rather thanname: maven-site-plugin 3.21.0 silently drops anameattribute from inline HTML while leaving the element in place, so the build stays green and every deep link stops working (seen for real in apache/maven-gpg-plugin#335).idworks on every version and is the correct HTML5 form.Verification
Built the site before and after and compared the set of anchors the generated
faq.htmlactually serves:Every anchor served before is still served after. The
<head>is byte-identical, so title and metadata are unchanged, and every link target on the page is unchanged.site.xmlneeds no edit - both paths render tofaq.html.What is lost
FML generates a
[top]back-link after each answer. Those are dropped rather than hand-written. The question renders as anh3heading instead of a definition term. Nothing else changes.Drafted with Claude - please verify