slachiewicz opened a new pull request, #1009:
URL: https://github.com/apache/maven-archetype/pull/1009
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
1. **A pure rename**, `maven-archetype-plugin/src/site/fml/faq.fml` →
`maven-archetype-plugin/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.
**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, whereas a
Markdown heading
gets one derived from the *question text* — a different string. So each
original id is
written out explicitly as an `<a name>` ahead of its heading, taken from the
rendered HTML
rather than from 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 | `packaging`, `authentication`, `old`, `excludes`, `top`,
`bodyColumn` |
| after | the same six, plus five heading-derived ids |
Every anchor present before is still present after — the set only grows. 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`, and the
`<item name="FAQ" href="faq.html"/>` entry in the plugin's `site.xml` is
untouched.
### What is lost
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 differences.
<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: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
