slachiewicz commented on PR #151:
URL:
https://github.com/apache/maven-doxia-converter/pull/151#issuecomment-5234537788
Added `bd03f28`: the anchor item covered how to *spell* an anchor but not
where it may *go*, and
placement is what actually deletes section ids.
I re-tested six placements against both attributes on this project's site
rather than adjusting
the wording from the report. Results — the only arrangement that loses a
section id is a
*surviving* anchor folded into heading text, and it is the arrangement that
looks tidiest:
| placement | anchor survives | following/own section keeps generated id |
|---|---|---|
| own line, `name=` | no | **yes** |
| own line, `id=` | **yes** | **yes** |
| folded into setext heading, `name=` | no | **yes** |
| folded into setext heading, `id=` | **yes** | **no** |
| folded into ATX heading, `name=` | no | **yes** |
| after a closing fence | — | block never closes |
So the two rules are orthogonal and both go in:
* **`id`, not `name`** — `name` is stripped and the empty element discarded,
so the anchor is
gone. (Unchanged from `d5f5f6e`; the six-way table confirms it in every
placement.)
* **Never fold an anchor into heading text** — an anchor that survives
inside a heading
suppresses the id Doxia generates for that section. You trade the
section's own anchor for
your hand-written one. With `name=` you do not see this, but only because
the anchor was
deleted first.
**An anchor on its own line is safe** and is now what the page recommends:
it costs an empty
`<p>` and the following heading keeps its id.
The end-of-preceding-line placement is not a third option once the block is
fenced, and this one
is worse than "does not work" — a closing fence may be followed only by
whitespace, so the fence
closes nothing and **the remainder of the document is swallowed into the
code block**, headings
and all. In my probe the three sections after it disappeared. Loud in the
page, but the build
still exits zero.
`mvn site` and `mvn verify` green (JDK 21, Maven 3.9.16, macOS); RAT 0
unapproved, 23/23. All ten
`<h2>` still render — including past the page's own fenced examples of
unterminated fences, which
was worth checking.
One open question for anyone comparing notes: on this toolchain a
`name`-only anchor is deleted
outright, but a field report of the same page described `<a
name="class_manifest">` arriving as
`<a id="class_manifest">`. That would mean some Doxia versions rewrite
`name` to `id` rather than
dropping it. The guidance is unaffected — write `id`, put it on its own
line, and both behaviours
give the same result — but if someone can pin the version boundary it is
worth a sentence.
--
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]
