Convert the FAQ from FML to Markdown - #437
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 anchors keep the existing deep links working. FML routes every <faq id> 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 <a name> 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 <head> 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 <a id>, not <a name>: 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 <a> 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)
slachiewicz
force-pushed
the
faq-to-markdown
branch
from
August 10, 2026 00:17
08e628d to
cee8c29
Compare
slachiewicz
marked this pull request as ready for review
August 10, 2026 01:11
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.
Converts this project's FAQ from FML to Markdown, continuing the estate-wide
move off the Doxia FML format.
src/site/fml/faq.fmlbecomessrc/site/markdown/faq.md, in two commits:git mv, no content change, sogit log --followkeeps working;Please merge or rebase rather than squash, so the rename commit survives.
Why by hand rather than with doxia-converter
FML is a FAQ-specific Doxia format (
<faqs>/<part>/<faq id=…>) with noMarkdown counterpart, and doxia-converter cannot target it: the questions come
out as link-reference syntax rather than headings, the
[top]back-links turninto links to a nonexistent
toppage, and the contents links lose their#anchors. The page is written out by hand.
Every published URL still resolves
There is a trivial textual overlap with #425, which adds one blank line
inside this file's licence comment. No content conflict; whichever lands
second resolves it in one line.
This page has been on maven.apache.org for years and is deep-linked from blog
posts and Stack Overflow, so no fragment may change.
FML routes every
<faq id>throughDoxiaUtils.encodeId, which rewrites any idthat is not a valid XML name — a space becomes
_, and any other characterbecomes its dot-prefixed UTF-8 bytes, so
,becomes.2Cand?becomes.3F. The<a name>elements added here reproduce that rendered anchor,not the raw
id=attribute, which for several entries is not the same string.Verified by generating the site before and after the change and comparing the
set of anchors the generated
faq.htmlactually serves —id=on any elementplus
name=on any<a>. The requirement is that the before-set is a subset ofthe after-set:
The anchors carried over are:
The
<head>is byte-identical, so the page title and metadata are unchanged.site.xmlneeds no edit — both source paths render tofaq.html.Accepted rendering losses
[top]back-link after every answer; those are dropped ratherthan hand-written.
h3heading rather than a definition term, sothe answers are no longer wrapped in a
<dl>.Generated-by: Claude Opus 5 (1M context)