Convert the FAQ from FML to Markdown - #385
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)
slachiewicz
force-pushed
the
faq-to-markdown
branch
from
August 9, 2026 23:55
72bd279 to
95af6d5
Compare
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. The one anchor on this page is a form Doxia rewrites at render time: <faq id="Why use antrun and not the Ant program itself?"> is not a valid XML name, so DoxiaUtils.encodeId serves it as #Why_use_antrun_and_not_the_Ant_program_itself.3F. The <a id> written here reproduces that rendered form, not the raw attribute, so the live deep link still resolves. No explicit <a id> is written for that anchor, because the h3 the question becomes already generates exactly that id from the same encodeId rule - adding one as well would emit the id twice and Doxia warns about it. The rendered page carries the anchor once, from the heading. 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, and 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, so the menu entry and the link from index.md keep working. FML generates a [top] back-link after each answer; those are dropped rather than hand-written. The question becomes an h3 heading instead of a definition term. Nothing else on the page changes. The anchors are written as <a id="...">, not <a name="...">. maven-site-plugin 3.21.0 strips the name attribute from inline HTML, which would silently delete every anchor on the page while the build stays green; 3.22.0 keeps it. Xhtml5BaseParser reads Attribute.ID first and only falls back to NAME, so id= is the primary path rather than a workaround, and name on <a> is obsolete in HTML5. Each anchor is kept on its own line: folding one into the heading text suppresses the section's own generated id. Generated-by: Claude Opus 5 (1M context)
slachiewicz
force-pushed
the
faq-to-markdown
branch
from
August 10, 2026 00:31
95af6d5 to
df43d0e
Compare
slachiewicz
marked this pull request as ready for review
August 10, 2026 00:35
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 an estate-wide move of the remaining FAQ pages from FML to Markdown.
Two commits, deliberately
src/site/fml/faq.fml->src/site/markdown/faq.md, no content change.Git records a rename plus a rewrite in a single commit as a delete and an add, which stops
git log --follow. Splitting them keeps the history. Please merge or rebase rather than squash.Why by hand
doxia-converter cannot target FML: the questions come out as link-reference syntax rather than headings, the
[top]back-links become links to a nonexistenttoppage, and the contents links lose their#anchors.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 written here reproduce the anchor the live site serves today, not the raw attribute.Here that matters:
id="Why use antrun and not the Ant program itself?"is served as#Why_use_antrun_and_not_the_Ant_program_itself.3F, and that is the string written into the Markdown.Anchors use
<a id>, not<a name>maven-site-plugin 3.21.0 strips the
nameattribute from inline HTML; 3.22.0 keeps it — stripping it would delete every anchor on the page while the build stayed green.Xhtml5BaseParserreadsAttribute.IDfirst and only falls back toNAME, soidis the primary path rather than a workaround, andnameon<a>is obsolete in HTML5. Each anchor is on its own line: folding one into heading text suppresses the section's own generated id.Where the live anchor is byte-identical to what the
###heading generates on its own, no explicit anchor is written — adding one would emit the same id twice, which is invalid HTML and which Doxia warns about. Verified zeroAnchor name … used more than oncewarnings in the site log.Verification
Built the site with
mvn sitebefore and after and compared the set of anchors the generatedfaq.htmlactually serves.<head>byte-identical, so title and metadata are unchanged. No link target on the page changed.site.xmlneeds no edit — FML and Markdown both render tofaq.html, so the menu entry and the./faq.htmllink inindex.mdkeep working.What is lost
FML generates a
[top]back-link after each answer. Those are dropped rather than hand-written. The question becomes anh3heading instead of a definition term. Nothing else changes.Drafted with Claude — please verify