(maven-doxia-converter) 03/04: Pin the name-attribute behaviour to a Doxia version boundary

[sl...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

slachiewicz pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven-doxia-converter.git

commit 2c59422fb3ceb3aa63d7923f3232efa02faccf43
Author: Sylwester Lachiewicz <sl...@apache.org>
AuthorDate: Mon Aug 10 02:15:06 2026 +0200

    Pin the name-attribute behaviour to a Doxia version boundary
    
    The anchor rule said a name-only anchor is deleted. That is true on
    doxia-module-markdown 2.0.0 and false on 2.1.0, which rewrites it to id,
    and four repositories on the newer stack have working name anchors that
    the rule as written would have called broken.
    
    Measured on this project's site with the module pinned either side, five
    placements each - own line, glued to a raw </table> or </pre>, straight
    after a fenced block, and folded into a heading. Placement turns out not
    to matter to this at all: 2.0.0 deletes every one, 2.1.0 rewrites every
    one. maven-site-plugin 3.21.0 brings 2.0.0 and 3.22.0 brings 2.1.0. Only
    id behaves the same on both, so id is still what to write, but the reason
    is the version spread rather than a defect.
    
    That boundary turns the folding rule into a delayed failure worth calling
    out. A name anchor folded into heading text looks fine on 2.0.0 precisely
    because it is deleted before it can suppress the section's generated id;
    on 2.1.0 it survives and the id disappears. The page can be converted,
    checked, and merged, and then lose its section anchors on a later site
    plugin bump that touches nothing else.
    
    Also separate the two block kinds in the closing-fence rule. Gluing an
    anchor to the end of a raw <pre>...</pre> is fine and is what converted
    xdoc pages carry; only a fenced block refuses to close, and converting a
    raw block into a fence is what takes the placement away.
    
    Generated-by: Claude Opus 5 (1M context)
---
 src/site/markdown/migrating-apt-to-markdown.md | 42 ++++++++++++++++++++------
 1 file changed, 32 insertions(+), 10 deletions(-)

diff --git a/src/site/markdown/migrating-apt-to-markdown.md b/src/site/markdown/migrating-apt-to-markdown.md
index 727dea2..f8038b8 100644
--- a/src/site/markdown/migrating-apt-to-markdown.md
+++ b/src/site/markdown/migrating-apt-to-markdown.md
@@ -205,20 +205,36 @@ untouched, and the rules below cost anchors and styling on green builds. All of
 to a text comparison: an anchor contributes no visible text, and an `<a>` with no `href` is not
 a link.
 
-**Write the anchor with `id`, not `name`.** The obsolete `name` attribute is dropped, which
-leaves an element with no attributes and no content, and that is discarded. The anchor does not
-move or get wrapped — it is gone, and every link pointing at it is broken. Same line, same
-position, only the attribute differs:
+**Write the anchor with `id`, not `name` — what `name` does depends on the Doxia version.**
+`name` is obsolete in HTML5, and the Markdown module changed how it treats it:
 
-```
-<a name="x"></a>          ->  (nothing at all)
-<a id="x"></a>            ->  <a id="x"></a>
-<a name="x" id="x"></a>   ->  <a id="x"></a>
-```
+| written in the page | doxia-module-markdown 2.0.0 | 2.1.0 |
+|---|---|---|
+| `<a name="x"></a>` | *deleted* | `<a id="x"></a>` |
+| `<a id="x"></a>` | `<a id="x"></a>` | `<a id="x"></a>` |
+| `<a name="x" id="x"></a>` | `<a id="x"></a>` | `<a id="x"></a>` |
+
+On 2.0.0 the attribute is dropped, which leaves an element with no attributes and no content,
+and that is discarded — the anchor is gone and every link to it is broken. On 2.1.0 the same
+source is rewritten to `id` and the anchor works. The version arrives with the site plugin:
+`maven-site-plugin` 3.21.0 brings 2.0.0, 3.22.0 brings 2.1.0. Placement makes no difference to
+this — it holds for an anchor on its own line, glued to a raw `</table>` or `</pre>`, or
+immediately after a fenced block.
+
+Only `id` behaves the same on both, which is why it is the form to write.
 
 **Never fold an anchor into a heading's text.** An anchor that survives *inside* a heading
 suppresses the id Doxia would otherwise generate for that section, so you trade the section's
-own anchor for your hand-written one and every link to the generated id breaks:
+own anchor for your hand-written one and every link to the generated id breaks.
+
+This is the one place where the version difference above is a trap rather than a curiosity. Fold
+`<a name="x"></a>` into a heading and on 2.0.0 nothing appears to be wrong — the anchor is
+deleted before it can do any harm, and the section keeps its generated id. Upgrade the site
+plugin to 3.22.0 and the anchor starts surviving, so **the section silently loses its id on a
+build where nothing but the plugin version changed.** A page converted today and checked today
+can break on somebody else's upgrade months later.
+
+Both attributes behave the same way once the anchor survives:
 
 ```
 <a id="x"></a>Configuration      ->  <h2><a id="x"></a>Configuration</h2>
@@ -248,6 +264,12 @@ That failure is at least loud in the rendered page, but the build still exits ze
 anchor on its own line after the fence and accept the empty paragraph; moving it above the fence
 would change where a deep link lands.
 
+This applies to *fenced* blocks only. A block that stays raw HTML —
+`<pre class="prettyprint linenums"><code>…</code></pre>` — is not a fence, and an anchor glued to
+its closing tag is fine; that is what converted xdoc pages normally carry, and it reproduces the
+anchor's original position exactly. Converting such a block to a fence is what takes the
+placement away, so keep the two decisions together.
+
 **Raw `<pre>` keeps exactly the attributes you write and gains none.** Doxia's own boxed block
 is `<pre class="prettyprint linenums"><code>`; a bare `<pre>` in raw HTML renders as a bare
 `<pre>`, unboxed and unstyled. If you are hand-writing a block to match what xdoc `<source>`