Markdown table without pipes: pandoc simple tables

A table in a Markdown file can skip pipe characters when pandoc's markdown reader does the converting. In that form, plain spaces split the columns and a row of dashes sits under the header.

Five tiny files were converted on macOS, using pandoc at version 3.8.3, and each HTML result is quoted below. Every result here is from a single run on one machine, and the checks stopped at the HTML output. For tables built with pipes, read the Markdown tables guide. The post on multiline table cells covers grid and multiline tables, along with captions on pipe tables.

Pipeless tables and the CommonMark spec

Against the CommonMark spec file (version 0.31.2), grep -c -F 'simple_tables' found 0 lines. A second search, grep -ci -F 'pipe', also returned 0. To prove the file could match a phrase, grep -ci -F 'thematic break' returned 20.

Pandoc calls the space-split form simple_tables. Asked for its extension list with pandoc --list-extensions=markdown, pandoc showed +simple_tables in this test. Filtered the same way, the commonmark list held just -pipe_tables (command: pandoc --list-extensions=commonmark).

The five input files

Running cat st.md printed:

  Name      Role
  --------  ------
  Jane Doe  Owner
  John Doe  Editor

Each line opens with two spaces. The header words sit over runs of dashes, and the cells in each row are split by spaces alone.

Here is how the other four files differ. st-cap.md holds the same four lines with no indent, then a blank line and Table: Doe team. st-align.md has new words: Right, Left and Center head it, and its rows hold 12, Jane, x and 123, John, yy. Its header and dashes lines open with four spaces, and its two rows open with eight and seven. st-align2.md and st-align3.md keep those words. In both, the header line opens with two spaces, the dashes line with none, and the rows with five and four. The two files differ in where the header words sit over their dashes.

A simple table under the markdown reader

The command:

pandoc -f markdown -t html st.md

Pandoc wrote:

<table>
<thead>
<tr>
<th style="text-align: left;">Name</th>
<th style="text-align: left;">Role</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align: left;">Jane Doe</td>
<td style="text-align: left;">Owner</td>
</tr>
<tr>
<td style="text-align: left;">John Doe</td>
<td style="text-align: left;">Editor</td>
</tr>
</tbody>
</table>

The first line became the thead row, and the two lines under the dashes became tbody rows. The space inside Jane Doe stayed inside one cell. Pandoc gave each th and td a style attribute set to text-align: left;.

Add a caption line

The caption file went through this command:

pandoc -f markdown -t html st-cap.md

It gave the same rows, with one more line right after the opening tag:

<table>
<caption>Doe team</caption>
<thead>

The Table: Doe team line turned into a caption element, and the text Table: was dropped from it. This file had no indent, and the table still came out with its thead and tbody rows. Pandoc names this caption syntax table_captions, and pandoc --list-extensions=markdown showed +table_captions in this test. For more on captions, see the multiline table cells post.

Column alignment from the dashes

Running cat st-align2.md printed:

  Right     Left     Center
-------   ------   --------
     12   Jane       x
    123   John      yy

Converted with the markdown reader, this file got style="text-align: right;" on all three th cells and all six td cells. Here, the last letter of each header word lines up over the last dash of its run.

To get three different values, a new file moved the header words. Running cat st-align3.md printed:

  Right   Left      Center
-------   ------   --------
     12   Jane       x
    123   John      yy

The markdown reader then wrote:

<table>
<thead>
<tr>
<th style="text-align: right;">Right</th>
<th style="text-align: left;">Left</th>
<th style="text-align: center;">Center</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align: right;">12</td>
<td style="text-align: left;">Jane</td>
<td style="text-align: center;">x</td>
</tr>
<tr>
<td style="text-align: right;">123</td>
<td style="text-align: left;">John</td>
<td style="text-align: center;">yy</td>
</tr>
</tbody>
</table>

Across st.md, st-align2.md and st-align3.md, the value pandoc picked matched where each header word sat over its dashes:

1. Word ends where its dashes end, starts further in: right.
2. Word starts where its dashes start, ends short of them: left.
3. Word touches neither end of its dashes: center.

The cells in the rows took the value of their column header. No other layout was tried here.

Turning off simple_tables

This run switched the extension off:

pandoc -f markdown-simple_tables -t html st.md > st-nost.html

The file held one paragraph, and the header, dashes and rows ran together inside it. The dash runs came back as dash characters, so the output holds non-ASCII bytes. Here is that line ASCII-normalized, with [U+2014] standing for each EM DASH and [U+2013] for the one EN DASH:

<p>Name Role [U+2014][U+2014][U+2013] [U+2014][U+2014] Jane Doe Owner John Doe Editor</p>

The byte dump from od -An -tx1 st-nost.html showed e2 80 94 for each U+2014 and e2 80 93 for the U+2013. The eight hyphens under Name turned into two EM DASH characters and one EN DASH. The six hyphens under Role turned into two EM DASH characters.

With st-cap.md, the same run added <p>Table: Doe team</p> as a second paragraph, so the caption line stayed as plain text.

What the commonmark readers wrote

Reading st.md, pandoc wrote these three lines under plain commonmark, and again under commonmark+pipe_tables:

<p>Name Role</p>
<hr />
<p>Jane Doe Owner John Doe Editor</p>

That middle line comes from the spec. A line made of at least three - characters, after no more than three spaces of indent, is a thematic break (lines 838 to 841), and spaces may sit between those characters (line 916). Line 1373 rules out inner spaces in a setext heading underline, so Name Role stayed a paragraph and pandoc wrote no heading. The horizontal rules guide covers that dashes line in more depth.

The st-cap.md runs under those two settings added <p>Table: Doe team</p> after those three lines.

For st-align2.md, each of the two settings gave:

<p>Right Left Center</p>
<hr />
<pre><code> 12   Jane       x
123   John      yy</code></pre>

Its rows had five and four spaces of indent. Lines 1628 to 1633 of the spec say an indented code block is made of lines indented by at least four spaces, with four spaces taken off each one. That is why 12 kept one space at its start.

A table pushed four spaces in

In st-align.md, the header and dashes lines open with four spaces, and the rows open with eight and seven. Under markdown, markdown-simple_tables, commonmark and commonmark+pipe_tables alike, pandoc wrote one identical block:

<pre><code>Right     Left     Center
-------   ------   --------
    12    Jane       x
   123    John      yy</code></pre>

Pandoc took out four spaces from each line and kept the rest as literal text. No table element came out, even with simple_tables on.

Check a pipeless table with grep

Work from the directory where st.md and the other test files live.

1. Open the source with cat st.md, then count the spaces ahead of the first word on each line. Two worked here, and four gave a code block.
2. Convert it: pandoc -f markdown -t html st.md > st.html. Then grep -c '<table>' st.html printed 1.
3. Switch readers: pandoc -f commonmark -t html st.md > st-cm.html. Here grep -c '<table>' st-cm.html printed 0. A count of hr lines, grep -c '<hr />' st-cm.html, printed 1.
4. Check the caption: pandoc -f markdown -t html st-cap.md > st-cap.html, then grep -c '<caption>' st-cap.html printed 1.
5. Look for dash characters with the extension off: pandoc -f markdown-simple_tables -t html st.md > st-nost.html. After that, LC_ALL=C grep -c '[^ -~]' st-nost.html printed 1, one line with a non-ASCII byte.
6. Name the bytes with od -c st-nost.html or od -An -tx1 st-nost.html and match each three-byte group to a code point.

Where Sashmark fits

Sashmark's v1, if built to plan, would let a person fix wording directly in its rendered form. Each save would run a clean Round-Trip, one more planned piece, and untouched lines would keep byte for byte what they held. A Changes View, planned as well, would point out every edit since the file was last opened for reading, and git would play no part.

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.