slachiewicz opened a new pull request, #152:
URL: https://github.com/apache/maven-doxia-converter/pull/152
Follow-up to #151 (merged). Three table facts found converting
`apache/maven-archetypes`, plus
the escape hatch that makes them actionable.
All three share the property that makes this migration dangerous: **the
words survive, in the
right order, so a text comparison passes.** Only a structural diff of the
generated HTML sees
them. That is the same shape as the info-string trap already on the page.
### What a table loses
| | measured |
|---|---|
| **no header row** | APT does not require one, Markdown does — the
converter writes an *empty* header row that renders as a blank band across the
top |
| **column alignment** | the converter writes `\|:---:\|` faithfully; the
Markdown module emits no `text-align`, so a centred APT table renders left |
| **grid borders** | APT's `+` grid gives `<table class="table
table-bordered …">`; a Markdown table is always `table-striped` only |
Promoting the real first row to the header removes the blank band, at the
cost of those cells
becoming `<th>` rather than `<td>` — a content decision, so the page says to
make it deliberately
and record it, since a reviewer reading the Markdown cannot see what it
fixed.
### The escape hatch
The limitation alone is not much use, so the section now also says what to
do about it: **a
`<table>` left as raw HTML passes through Doxia untouched.** Verified here
rather than taken on
report — same page, three tables, one build:
```
markdown table, |:---:| -> <table class="table table-striped"> <thead>
<th> <td>
(no text-align anywhere)
raw HTML table -> <table class="table table-bordered
table-striped">
<th style="text-align: center;"> <td
style="text-align: center;">
(no <thead> inserted)
markdown table, empty hdr -> <thead> + two empty <th> = the blank band
```
`class`, inline `style` and the author's own row structure all survive. It
costs a table that is
no longer readable as Markdown, so the page frames it as worth it for a page
whose table is the
point and not otherwise.
### Verification
`mvn site`: all ten `<h2>`, the `<h3>` and both tables render. `mvn verify`:
BUILD SUCCESS, RAT 0
unapproved, 23/23 tests — JDK 21, Maven 3.9.16, macOS only. CI on the push
is the real check.
Generated with assistance from Claude Opus 5.
--
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]
