Markdown Table Basics

Using Flexmark in Stata

Doug Hemken

May 2018

Flexmark extends the basic Markdown specification with the addition of "piped" tables, an additional block element. Inline elements may be included within a table, but not other block elements.

What Demarcates A Table?

A table is an arrangement of data in rows and columns, consisting of a header row, a delimiter row separating the header from the data, and data rows. In flexmark it is possible to have a table that displays as purely a header row, or a table that displays purely as data rows - each is marked with a delimiter row.

Each row consists of cells containing arbitrary text, in which inlines are parsed, separated by pipes (|). A leading and trailing pipe is also recommended for clarity of reading.

The delimiter row consists of cells (separated by pipes) whose only content are hyphens (-) (at least three, like a theme break), or optionally, a leading or trailing colon (:), or both, to indicate left, right, or center alignment respectively. Left justification is the default for data cells, centered for header cells.

Table Delimiter Row

```
| Column One    | Column Two    |
| ---           | ---           |
| data cell one | data cell two |
```

No delimter row or too few hyphens and this is no longer a table:

```
| Column One    | Column Two    |
| data cell one | data cell two |

| Column One    | Column Two    |
| -             | --            |
| data cell one | data cell two |
```

| Column One | Column Two | | data cell one | data cell two |

| Column One | Column Two | | - | – | | data cell one | data cell two |

However, a table can have only a header row, or only a data row:

```
| Column One    | Column Two    |
| ---           | ---           |
```

```
| ---           | ---           |
| data cell one | data cell two |
```

Leading Spaces

In flexmark, one to three leading spaces are ignored.

```
   | Column One    | Column Two    |
  | ---           | ---           |
 | data cell one | data cell two |
```

Four leading spaces mark an indented code block, and the rest of the table is recognized (but has no header row).

```
    | Column One | Column Two |
    | --- | --- |
    | data cell one | data cell two |
```

| Column One | Column Two |
| --- | --- |
| data cell one | data cell two |

Cell Widths

Cells widths in the same column don’t need to match length, though it’s easier to read if they do. Likewise, use of leading and trailing pipes may be inconsistent:

```
| abc | defghi |
:-: | -----------:
data cell | data cell two
```

Number of Cells

It is not necessary for each row to have the same number of cells.

```
| Column One    | Column Two    |
| ---           | ---           |
| data cell one | data cell two | data cell three
| data cell four
```

You can leave cells empty by having two pipe characters.
An empty cell (adjacent pipes with no space) extends the cell before it (a space counts as text).

```
| Column One    |               | Column Two    |
| ---           | ---           |
|| data cell one | data cell two |data cell three
| || data cell four
```

Pipe characters

Include a pipe in a cell’s content by escaping it, including inside other inline spans:

```
| f\|oo  |
| ------ |
| b `\|` az |
| b **\|** im |
```