Convert the FAQ from FML to Markdown - #689
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. The <a id> emitted here reproduces the anchor the rendered page serves today, not the raw <faq id> attribute, which FML rewrites whenever it is not a valid XML name. Anchors are written as <a id>, not <a name>: maven-site-plugin 3.21.0 strips name= from an inline HTML anchor, which loses every anchor on an otherwise green build, and name= on <a> is obsolete in HTML5. Xhtml5BaseParser reads Attribute.ID first and only falls back to NAME, so id= is the primary path. Each anchor sits on its own line, since folding one into the heading text suppresses the section's own id. Straight quotes in prose are written as " and '. flexmark's smart-punctuation extension would otherwise turn them into typographic quotes, silently changing the visible text - FML, being XML, rendered them straight. This is the convention maven-site-plugin's own converted pages already use. 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: question, skip, deploy_deploy, top, bodyColumn after: the same five, plus four heading-derived ids The check also compares the visible text of the two pages word by word; it is identical apart from the dropped [top] links. The site log reports no "used more than once" anchor warning. 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 now renders as an h3 heading instead of a definition term. Those are the only rendering losses. Generated-by: Claude Opus 5 (1M context)
slachiewicz
force-pushed
the
faq-to-markdown
branch
from
August 10, 2026 00:37
c73ee24 to
498f845
Compare
slachiewicz
marked this pull request as ready for review
August 10, 2026 01:14
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. FML is a
FAQ-specific Doxia format with no Markdown counterpart and doxia-converter cannot target
it, so the page is hand-written rather than converted.
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, since squashing collapses the rename again.
Anchors are preserved, and that is the point
This page has been on maven.apache.org for years and is linked from outside, so no URL may
change. FML derives its anchor from the
<faq id=…>attribute; Markdown headings wouldinstead get an anchor derived from the question text, which is a different string. So the
<a id>written here reproduces the anchor the live site serves today.Verification
Built the site before and after and compared the set of anchors the generated
faq.htmlactually serves:
question,skip,deploy_deploy,top,bodyColumnEvery anchor present before is still present after — the set only grows. The
<head>isbyte-identical, so the title and metadata are unchanged.
site.xmlneeds no edit:src/site/fml/faq.fmlandsrc/site/markdown/faq.mdboth render tofaq.html.Anchors are written as
<a id>, not<a name>maven-site-plugin 3.21.0 strips the
name=attribute from an inline HTML anchor; 3.22.0keeps it — on 3.21.0 every anchor is lost silently on a green build. This repo is on a
parent that pulls 3.22.0 so either form works today, but
<a id>survives both, and it isthe correct form anyway:
Xhtml5BaseParserreadsAttribute.IDfirst and falls back toNAMEonly if it is absent, andname=on<a>is obsolete in HTML5. Anchors stay ontheir own line, since folding one into the heading text suppresses the section's own id.
Straight quotes are written as
"/'flexmark's smart-punctuation extension rewrites a straight
"in Markdown prose as atypographic quote, whereas FML — being XML — rendered it straight. Left alone that silently
changes the visible text, and the anchor check cannot see it. Escaping restores the
original rendering; this is the convention maven-site-plugin's own converted pages use.
Additional checks
target/sitedeleted before every build and the page confirmed regenerated, so no resulthere comes from a stale page.
[top]links.used more than onceanchor warning (this page has no anchor thatcollides with a heading-derived id, so every explicit anchor is load-bearing).
What is lost
FML generates a
[top]back-link after each answer; those are dropped rather thanhand-written. The question now renders as an
h3heading instead of a definition term.Those are the only rendering differences.
Drafted with Claude — please verify