(maven-doxia-converter) 01/01: Record what a table loses, and how to keep it

[sl...@apache.org]

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

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

commit 241b6e6a276ab5b283be214d7e442e0cb112b67e
Author: Sylwester Lachiewicz <sl...@apache.org>
AuthorDate: Mon Aug 10 03:30:24 2026 +0200

    Record what a table loses, and how to keep it
    
    Three table facts turned up converting maven-archetypes, and all three
    share the property that makes this migration dangerous: the words survive
    in the right order, so a text comparison passes, and only a structural
    diff of the generated HTML notices.
    
    A Markdown table must have a header row and an APT table need not, so the
    converter writes an empty one and it renders as a blank band across the
    top. Promoting the real first row removes the band and turns those cells
    into <th>, which is a content decision rather than a tidy-up. Column
    alignment is written faithfully as |:---:| and then dropped by the module.
    The grid form's table-bordered goes too.
    
    Add the escape hatch alongside, since the limitation is only half the
    answer: a <table> left as raw HTML passes through untouched, keeping its
    class and inline style and gaining no <thead>, so a table that has to hold
    its borders or its alignment can. Measured either side rather than assumed.
    
    Generated-by: Claude Opus 5 (1M context)
---
 src/site/markdown/migrating-apt-to-markdown.md | 29 ++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/src/site/markdown/migrating-apt-to-markdown.md b/src/site/markdown/migrating-apt-to-markdown.md
index f01824e..6b47da4 100644
--- a/src/site/markdown/migrating-apt-to-markdown.md
+++ b/src/site/markdown/migrating-apt-to-markdown.md
@@ -298,6 +298,35 @@ changes the rendered page, so decide deliberately:
 * **Typographic substitution.** The Markdown module turns straight quotes into curly quotes
   and `...` into an ellipsis in prose. Code spans and code blocks are left alone.
 
+Tables lose three things, and none of them shows up in a text comparison — the words are all
+still there, in the right order. Only the structural pass below sees these.
+
+* **A table with no header row.** APT does not require one; Markdown does. The converter
+  therefore writes an *empty* header row above the first row, and it renders as a blank band
+  across the top of the table:
+
+  ```
+  |   |   |
+  |:---:|:---:|
+  |Name|Default|
+  ```
+
+  Promoting the real first row to the header removes the blank band, at the cost of those cells
+  becoming `<th>` rather than `<td>`. That is a content decision — make it deliberately, and say
+  so in the commit, because a reviewer reading the Markdown will not see what it fixed.
+
+* **Column alignment.** The converter writes `|:---:|` faithfully, but the Markdown module emits
+  no `text-align`, so a centred APT table renders left-aligned like any other.
+
+* **Grid borders.** APT's `+` grid form renders `<table class="table table-bordered …">`. A
+  Markdown table is always `table-striped` only, so the borders go.
+
+**The escape hatch, if a table has to keep any of that: leave it as raw HTML.** A `<table>`
+written out in the page passes through Doxia untouched — `class`, inline `style` and all — so
+`table-bordered` and per-cell alignment survive exactly as written, and no `<thead>` is inserted.
+It costs you a table that is no longer readable as Markdown, so it is worth it for a page whose
+table is the point, and not otherwise.
+
 ## Differences that are improvements
 
 Several APT constructs render incorrectly today and come out *better* after conversion. Do