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:53:38 UTC

[PR] Convert the FAQ from FML to Markdown [maven-war-plugin]

slachiewicz opened a new pull request, #649:
URL: https://github.com/apache/maven-war-plugin/pull/649

   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**, `src/site/fml/faq.fml.vm` → `src/site/markdown/faq.md.vm`, 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.
   
   ### It stays a Velocity template
   
   The two sample POMs interpolate `${project.version}` — the rendered page really does show
   the current plugin version — so the target is `faq.md.vm`, not `faq.md`.
   
   That has one non-obvious consequence: **in a `.vm` file an ATX heading starting `##` is
   swallowed as a Velocity line comment**, which silently deletes the heading on a green
   build. So the page title uses a setext underline and each question is wrapped in
   `#[[### … ]]#` (Velocity's unparsed-content block) to reach the Markdown parser intact.
   The verification below confirms all nine headings survive.
   
   ### 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. Markdown headings get an anchor derived from the *question text*, which is not the
   `<faq id=…>` the site serves today, so each original anchor is written out explicitly as an
   `<a name>`.
   
   ### Verification
   
   Built the site before and after and compared the set of anchors the generated `faq.html`
   actually serves:
   
   | | anchors served |
   |---|---|
   | before | `filtering`, `classifieruse`, `transitiveexclude`, `dependentwarexclude`, `webresourcesexclude`, `waroverlaysexclude`, `configurationdoc`, `attached`, `top`, `bodyColumn` |
   | after | the same ten, plus nine 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.vm` and `src/site/markdown/faq.md.vm` both render to `faq.html`.
   
   ### 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: 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-war-plugin]

Posted by "slachiewicz (via GitHub)" <gi...@apache.org>.
slachiewicz merged PR #649:
URL: https://github.com/apache/maven-war-plugin/pull/649


-- 
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