You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@maven.apache.org by "slachiewicz (via GitHub)" <gi...@apache.org> on 2026/08/09 23:12:41 UTC
[PR] Convert the FAQ from FML to Markdown [maven-artifact-plugin]
slachiewicz opened a new pull request, #231:
URL: https://github.com/apache/maven-artifact-plugin/pull/231
Part of an estate-wide move of the remaining FAQ pages from FML to Markdown. This repo is
one of three pilots; the pattern here is the one the rest will follow.
### Two commits, deliberately
1. **A pure rename**, `src/site/fml/faq.fml` → `src/site/markdown/faq.md`, no content change.
2. **The rewrite.**
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 — it currently traces back to 2021.
**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. FML derives
its anchor from the `<faq id=…>` attribute — and where that attribute is not a valid XML
name, `DoxiaUtils.encodeId` rewrites it at render time. Here `id="Configure Reproducible
Builds"` is served as `#Configure_Reproducible_Builds`.
Markdown headings would instead get an anchor derived from the *question text*, which is a
different string. So the `<a name>` written here reproduces **the anchor the live site
serves today**, not the raw attribute.
### Verification
Built the site before and after and compared the set of anchors the generated `faq.html`
actually serves:
| | anchors served |
|---|---|
| before | `Configure_Reproducible_Builds`, `top`, `bodyColumn` |
| after | the same three, plus two heading-derived ids |
Every anchor present before is still present after. 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`.
### What is lost
FML generates a `[top]` back-link after each answer. Those are dropped rather than
hand-written; it is the only rendering difference besides the question becoming an `h3`
heading instead of a definition term.
<sub>Drafted with Claude — please verify</sub>
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Convert the FAQ from FML to Markdown [maven-artifact-plugin]
Posted by "slachiewicz (via GitHub)" <gi...@apache.org>.
slachiewicz merged PR #231:
URL: https://github.com/apache/maven-artifact-plugin/pull/231
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org