Markdown table without header: what pandoc wrote

A markdown table without header text took several shapes in this test, among them one paragraph of plain text, a table holding body rows and nothing else, and two rules wrapped around a paragraph. Which one appeared depended on the table layout and on the reader passed to -f.

All runs here come from one Mac whose pandoc reports version 3.8.3. This post sticks to the HTML pandoc printed and leaves aside how any program might lay it out.

Four files under test

Four small files share the same two names and two numbers. Running cat nohead-pipe.md printed a pipe table that opens on its dash row:

|------|-----|
| Jane | 12  |
| John | 9   |

Running cat blank-head-pipe.md printed the same table with a row of empty cells on top:

|      |     |
|------|-----|
| Jane | 12  |
| John | 9   |

Running cat nohead-simple.md printed two rows held between two dash lines:

------  ----
Jane      12
John       9
------  ----

Running cat nohead-grid.md printed a grid table built from +, - and | characters:

+------+-----+
| Jane | 12  |
+------+-----+
| John | 9   |
+------+-----+

None of the four files puts a word above the data.

Pipe rows that open on dashes

Per the Markdown tables guide, pipe tables must start with a header row, and nohead-pipe.md drops it. This was the result once pipe_tables was added to commonmark:

pandoc -f commonmark+pipe_tables -t html nohead-pipe.md

<p>|------|-----| | Jane | 12 | | John | 9 |</p>

All three lines joined into a single <p> element. The pipes and dashes came through as plain characters, and pandoc wrote no <table> tag.

The markdown reader also gave one paragraph and no table for this file. Its copy swapped the dash runs for EM DASH (U+2014) and EN DASH (U+2013) characters, and this post leaves it out. The extra log keeps an od -An -tx1 dump of it, showing e2 80 94 and e2 80 93 in place of the hyphens.

Pandoc defines pipe_tables as an extension; it is not CommonMark syntax. The markdown list carries +pipe_tables at line 51, so it's active there by default. The commonmark list carries -pipe_tables at line 16, which is why the command above asks for it by name.

Blank cells above the dash row

The file with a blank top row went through both readers:

pandoc -f markdown -t html blank-head-pipe.md
pandoc -f commonmark+pipe_tables -t html blank-head-pipe.md

Each command printed these same twelve lines:

<table>
<tbody>
<tr>
<td>Jane</td>
<td>12</td>
</tr>
<tr>
<td>John</td>
<td>9</td>
</tr>
</tbody>
</table>

Here a <tbody> appears and a <thead> does not. The empty cells on top did not become blank <th> elements either; nothing from that row reached the output.

This agrees with the table guide. Here, a row of empty cells above the dashes was enough to get body-only HTML out of a pipe table.

Simple tables framed by dash lines

Line 58 of the markdown list shows +simple_tables. Its form with header words above the dashes is covered in tables without pipes. This file has dash lines above and below and no words on top:

pandoc -f markdown -t html nohead-simple.md

<table>
<tbody>
<tr>
<td style="text-align: left;">Jane</td>
<td style="text-align: right;">12</td>
</tr>
<tr>
<td style="text-align: left;">John</td>
<td style="text-align: right;">9</td>
</tr>
</tbody>
</table>

Again pandoc gave a <tbody> with no <thead>. The cells did carry alignment styles, though: text-align: left on Jane and John, and text-align: right on 12 and 9.

Grid borders and no equals line

For grid_tables, the markdown list has a plus sign at line 24. The border lines in nohead-grid.md use + and - only, and no line in it holds an = character.

pandoc -f markdown -t html nohead-grid.md

<table style="width:18%;">
<colgroup>
<col style="width: 9%" />
<col style="width: 8%" />
</colgroup>
<tbody>
<tr>
<td>Jane</td>
<td>12</td>
</tr>
<tr>
<td>John</td>
<td>9</td>
</tr>
</tbody>
</table>

Both rows landed in the <tbody>, and there's no <thead>. Pandoc also put a style attribute on the <table> tag and wrote a <colgroup> holding two <col> lines. They're quoted above exactly as pandoc printed them.

Multiline tables without a header

Pandoc's markdown list marks multiline_tables with a plus at line 46. The extra test added a file for it. Running cat nohead-multi.md printed:

----------  -----
Jane Doe    12
owner

John Doe    9
editor
----------  -----

Each name carries on to a second line, and the two rows are split by an empty line. Here is the run:

pandoc -f markdown -t html nohead-multi.md

<table style="width:25%;">
<colgroup>
<col style="width: 16%" />
<col style="width: 8%" />
</colgroup>
<tbody>
<tr>
<td style="text-align: left;">Jane Doe owner</td>
<td style="text-align: left;">12</td>
</tr>
<tr>
<td style="text-align: left;">John Doe editor</td>
<td style="text-align: left;">9</td>
</tr>
</tbody>
</table>

The two lines of each first-column cell were merged with a space between them, so Jane Doe owner ended up in one <td>. All four cells got text-align: left, and once more there's no <thead>. To switch that extension off, the extra script ran pandoc -f markdown-multiline_tables -t html nohead-multi.md, and its output held no <table> tag at all.

What plain commonmark did with these files

Looking at the commonmark list again, there's -pipe_tables at line 16 and no entry at all for simple_tables, grid_tables or multiline_tables. Here is the blank-top-row file under plain commonmark, from the extra test:

pandoc -f commonmark -t html blank-head-pipe.md

<p>| | | |------|-----| | Jane | 12 | | John | 9 |</p>

Without pipe_tables, that file turned into one paragraph, much like the dash-first file did above.

The dash-framed file gave something else:

pandoc -f commonmark -t html nohead-simple.md

<hr />
<p>Jane 12 John 9</p>
<hr />

Those <hr /> tags trace back to the spec. The spec's lines 838 to 841 define a thematic break as three or more matching - characters in a row, led by zero to three spaces. Line 916 lets spaces sit between those characters. Line 1373 bars inner spaces from a setext underline, so the closing dash line stayed a break, and the two rows above it stayed a paragraph.

Checking for a thead with grep

These steps all came from the extra script, run in the test folder. Put your file's name where these use the test file's.

1. Print the top line of the file: awk 'NR==1' blank-head-pipe.md. Here it printed | | |, a row of empty cells.
2. Convert it and save the output: pandoc -f markdown -t html blank-head-pipe.md -o nohead-out.html.
3. Count header blocks with grep -c '<thead>' nohead-out.html. Its answer was 0, and grep's exit status was 1 since it found no match.
4. Count body blocks with grep -c '<tbody>' nohead-out.html. It printed 1.
5. For the dash-first file, the extra script ran pandoc -f markdown -t html nohead-pipe.md -o nohead-out2.html. After it came grep -c '<table>' nohead-out2.html. Here the count came back 0.

A 0 at step 3 beside a 1 at step 4 means pandoc wrote body rows with no header block. A 0 at step 5 means no table came out of that file. If your files also hold double-bracket links, the companion post on Markdown wikilinks reports how pandoc handled those.

Where Sashmark fits

One goal set for Sashmark's initial build is that you could change a sentence while reading it, with no switch to the raw text. Under a clean Round-Trip, untouched parts of the file would come back unchanged on save. Planned alongside it, Changes View would list each spot an agent revised between your visits to that file, git or no git.

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.

More at sashmark.com.