Markdown table multiline cells: grid and multiline tests

You have a table where one cell needs more room: a name in the first column and a note wrapping onto a second line in the next. The Markdown tables guide covers pipe rows and alignment; this post tries other ways to get that second line.

The markdown table multiline tests below each ran under pandoc 3.8.3 for macOS with a single reader setting, and the returned HTML is quoted. The test files hold a grid table, a multiline table, a pipe table with a caption line and a pipe cell with a typed tag in it. Nothing here goes past what pandoc printed.

Spec greps and pandoc table extensions

Grep, ignoring case, turned up grid table on 0 lines of the 0.31.2 CommonMark text and multiline table on 0 lines. The word caption matched 2 lines, 2235 and 2236, where the HTML blocks section lists tag names (caption on one line, figcaption on the other). As a whole word, table matched 23 lines, all between lines 2241 and 2937, inside that same HTML blocks section. For a control, thematic break matched 20 lines.

Pandoc adds table syntax through extensions. Piping pandoc --list-extensions=markdown through grep found +grid_tables, +multiline_tables, +pipe_tables and +table_captions. On the commonmark list, grep counted 0 lines for grid_tables, multiline_tables and table_captions, and found -pipe_tables. Both lists showed +raw_html.

A grid table with two lines in one cell

The test file tbl-grid.md draws the table with + corners, - borders and a +===+ line under the header:

+-----------+------------------+
| Owner     | Notes            |
+===========+==================+
| Jane Doe  | First line       |
|           | second line      |
+-----------+------------------+

The command pandoc -f markdown -t html tbl-grid.md gave:

<table style="width:43%;">
<colgroup>
<col style="width: 16%" />
<col style="width: 26%" />
</colgroup>
<thead>
<tr>
<th>Owner</th>
<th>Notes</th>
</tr>
</thead>
<tbody>
<tr>
<td>Jane Doe</td>
<td>First line second line</td>
</tr>
</tbody>
</table>

The two source lines in the Notes cell became one cell, First line second line, with a space where the line ending had been. Pandoc also wrote a colgroup with a width for each column and a width on the table itself.

With pandoc -f commonmark -t html tbl-grid.md, the same file came back as one paragraph of text:

<p>+-----------+------------------+ | Owner | Notes |
+===========+==================+ | Jane Doe | First line | | | second
line | +-----------+------------------+</p>

The commonmark+pipe_tables setting printed those same three lines.

Lists and paragraphs inside a grid cell

An added test, tbl-grid-blocks.md, put a two-item list, a blank cell line and a sentence into the Notes cell:

+-----------+------------------+
| Owner     | Notes            |
+===========+==================+
| Jane Doe  | - First item     |
|           | - Second item    |
|           |                  |
|           | A closing line.  |
+-----------+------------------+

Here is the body row from pandoc -f markdown -t html tbl-grid-blocks.md:

<tr>
<td>Jane Doe</td>
<td><ul>
<li>First item</li>
<li>Second item</li>
</ul>
<p>A closing line.</p></td>
</tr>

The cell held a ul with two items and a p after it. The commonmark reader printed this file as one paragraph of text too, dashes and pipes included.

A multiline table with wrapped cell text

The file tbl-multi.md uses a different form. A dash line opens and closes it, a row of dash groups sits under the header, and a blank line separates the body rows:

----------------------------
Owner      Notes
---------- -----------------
Jane Doe   First line
           second line

John Doe   One line
----------------------------

Pandoc's markdown reader turned that into:

<table style="width:40%;">
<colgroup>
<col style="width: 15%" />
<col style="width: 25%" />
</colgroup>
<thead>
<tr>
<th style="text-align: left;">Owner</th>
<th style="text-align: left;">Notes</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align: left;">Jane Doe</td>
<td style="text-align: left;">First line second line</td>
</tr>
<tr>
<td style="text-align: left;">John Doe</td>
<td style="text-align: left;">One line</td>
</tr>
</tbody>
</table>

The wrapped note was joined with a space, as in the grid test. The two body rows came out as two tr elements, and every header and body cell got style="text-align: left;".

Why commonmark read the multiline table as a heading

Plain commonmark gave this for tbl-multi.md, and commonmark+pipe_tables printed the same five lines:

<hr />
<p>Owner Notes</p>
<hr />
<p>Jane Doe First line second line</p>
<h2>John Doe One line</h2>

The spec explains each line. Per lines 838 to 841, a thematic break is a line holding at least three of the same character, -, _ or *, with optional spaces or tabs after each. That covers the opening dash line, and it covers the dash groups under the header, since the space between groups is allowed there. Line 1373 adds that a setext heading underline can't hold internal spaces, so the line of dash groups stayed a break.

The closing dash line had no gap in it, and it sat right under John Doe One line. Lines 1255 to 1260 define a setext heading underline as a run of = or - characters and make a - underline a level 2 heading. Lines 995 to 998 settle the overlap: if a dash run could count as either a break or a setext underline, the heading reading takes precedence. So the last row became an h2.

A pipe table with a caption line

The file tbl-pipe-cap.md puts a Table: caption line under a pipe table. Its rows follow the pipe rules in the Markdown tables guide.

| Owner | Notes |
|---|---|
| Jane Doe | First line |
| | second line |

Table: Owners and notes

This time the markdown reader printed:

<table>
<caption>Owners and notes</caption>
<thead>
<tr>
<th>Owner</th>
<th>Notes</th>
</tr>
</thead>
<tbody>
<tr>
<td>Jane Doe</td>
<td>First line</td>
</tr>
<tr>
<td></td>
<td>second line</td>
</tr>
</tbody>
</table>

The Table: line became a caption element.

Under commonmark+pipe_tables, the table came out with the same rows and no caption, and the caption line printed after it as <p>Table: Owners and notes</p>. An added run, pandoc -f markdown-table_captions -t html tbl-pipe-cap.md, gave that same result. Plain commonmark gave two paragraphs: the table as text, then the caption line.

A br tag inside a pipe cell

The last test file, tbl-pipe-br.md, has a typed tag between the two parts of one cell:

| Owner | Notes |
|---|---|
| Jane Doe | First line<br>second line |

Both pandoc -f markdown -t html tbl-pipe-br.md and pandoc -f commonmark+pipe_tables -t html tbl-pipe-br.md wrote the cell as:

<td>First line<br>second line</td>

That tag came through unchanged, inside the one td. Under plain commonmark, the whole table turned into a paragraph:

<p>| Owner | Notes | |---|---| | Jane Doe | First line<br>second line
|</p>

Typed tags beyond this one get more room in the raw HTML in Markdown post. The line break fixes post covers other ways to end a line.

Test a multiline cell with pandoc

When a wrapped cell comes out wrong, put that one table in a file by itself and run these checks.

1. Print the file with cat tbl-grid.md and confirm the | and + characters line up on every row of the grid.
2. Count tables. pandoc -f markdown -t html tbl-grid.md | grep -c '<table' printed 1 in this test. The count fell to 0 with -f commonmark in its place.
3. Count rows in a multiline table. pandoc -f markdown -t html tbl-multi.md | grep -c '<tr>' printed 3: the header row and two body rows.
4. Look for a stray heading. pandoc -f commonmark -t html tbl-multi.md | grep -c '<h2>' printed 1, the closing dash line read as an underline.
5. Check a caption. pandoc -f markdown -t html tbl-pipe-cap.md | grep -c '<caption>' printed 1; the -f commonmark+pipe_tables run printed 0.

When your count doesn't match, set your output beside the quoted HTML for that file and reader.

Where Sashmark fits

In its v1 plan, Sashmark would let you change words directly inside the rendered page, and the clean Round-Trip it plans for would bring untouched lines back carrying identical bytes. Planned as well, with no git needed for it, is a Changes View, which would highlight wording altered since your prior look at that file. It is in development and has not been released. The app itself has no AI features. See the planned features, the help pages and the roadmap for where each part stands.

Read more at sashmark.com.