# Tables

With the flag `MD_FLAG_TABLES`, MD4C enables extension for recognition of
tables.

Basic table example of a table with two columns and three lines (when not
counting the header) is as follows:

```````````````````````````````` example
| Column 1 | Column 2 |
|----------|----------|
| foo      | bar      |
| baz      | qux      |
| quux     | quuz     |
.
<table>
<thead>
<tr><th>Column 1</th><th>Column 2</th></tr>
</thead>
<tbody>
<tr><td>foo</td><td>bar</td></tr>
<tr><td>baz</td><td>qux</td></tr>
<tr><td>quux</td><td>quuz</td></tr>
</tbody>
</table>
````````````````````````````````

The leading and succeeding pipe characters (`|`) on each line are optional:

```````````````````````````````` example
Column 1 | Column 2 |
---------|--------- |
foo      | bar      |
baz      | qux      |
quux     | quuz     |
.
<table>
<thead>
<tr><th>Column 1</th><th>Column 2</th></tr>
</thead>
<tbody>
<tr><td>foo</td><td>bar</td></tr>
<tr><td>baz</td><td>qux</td></tr>
<tr><td>quux</td><td>quuz</td></tr>
</tbody>
</table>
````````````````````````````````

```````````````````````````````` example
| Column 1 | Column 2
|----------|---------
| foo      | bar
| baz      | qux
| quux     | quuz
.
<table>
<thead>
<tr><th>Column 1</th><th>Column 2</th></tr>
</thead>
<tbody>
<tr><td>foo</td><td>bar</td></tr>
<tr><td>baz</td><td>qux</td></tr>
<tr><td>quux</td><td>quuz</td></tr>
</tbody>
</table>
````````````````````````````````

```````````````````````````````` example
Column 1 | Column 2
---------|---------
foo      | bar
baz      | qux
quux     | quuz
.
<table>
<thead>
<tr><th>Column 1</th><th>Column 2</th></tr>
</thead>
<tbody>
<tr><td>foo</td><td>bar</td></tr>
<tr><td>baz</td><td>qux</td></tr>
<tr><td>quux</td><td>quuz</td></tr>
</tbody>
</table>
````````````````````````````````

However for one-column table, at least one pipe has to be used in the table
header underline, otherwise it would be parsed as a Setext title followed by
a paragraph.

```````````````````````````````` example
Column 1
--------
foo
baz
quux
.
<h2>Column 1</h2>
<p>foo
baz
quux</p>
````````````````````````````````

Leading and trailing whitespace in a table cell is ignored and the columns do
not need to be aligned.

```````````````````````````````` example
Column 1 |Column 2
---|---
foo | bar
baz| qux
quux|quuz
.
<table>
<thead>
<tr><th>Column 1</th><th>Column 2</th></tr>
</thead>
<tbody>
<tr><td>foo</td><td>bar</td></tr>
<tr><td>baz</td><td>qux</td></tr>
<tr><td>quux</td><td>quuz</td></tr>
</tbody>
</table>
````````````````````````````````

The table cannot interrupt a paragraph.

```````````````````````````````` example
Lorem ipsum dolor sit amet.
| Column 1 | Column 2
| ---------|---------
| foo      | bar
| baz      | qux
| quux     | quuz
.
<p>Lorem ipsum dolor sit amet.
| Column 1 | Column 2
| ---------|---------
| foo      | bar
| baz      | qux
| quux     | quuz</p>
````````````````````````````````

Similarly, paragraph cannot interrupt a table:

```````````````````````````````` example
Column 1 | Column 2
---------|---------
foo      | bar
baz      | qux
quux     | quuz
Lorem ipsum dolor sit amet.
.
<table>
<thead>
<tr><th>Column 1</th><th>Column 2</th></tr>
</thead>
<tbody>
<tr><td>foo</td><td>bar</td></tr>
<tr><td>baz</td><td>qux</td></tr>
<tr><td>quux</td><td>quuz</td></tr>
<tr><td>Lorem ipsum dolor sit amet.</td><td></td></tr>
</tbody>
</table>
````````````````````````````````

The underline of the table is crucial for recognition of the table, count of
its columns and their alignment: The line has to contain at least one pipe,
and it has provide at least three dash (`-`) characters for every column in
the table.

Thus this is not a table because there are too few dashes for Column 2.

```````````````````````````````` example
| Column 1 | Column 2
| ---------|--
| foo      | bar
| baz      | qux
| quux     | quuz
.
<p>| Column 1 | Column 2
| ---------|--
| foo      | bar
| baz      | qux
| quux     | quuz</p>
````````````````````````````````

The first, the last or both the first and the last dash in each column
underline can be replaced with a colon (`:`) to request left, right or middle
alignment of the respective column:

```````````````````````````````` example
| Column 1 | Column 2 | Column 3 | Column 4 |
|----------|:---------|:--------:|---------:|
| default  | left     | center   | right    |
.
<table>
<thead>
<tr><th>Column 1</th><th align="left">Column 2</th><th align="center">Column 3</th><th align="right">Column 4</th></tr>
</thead>
<tbody>
<tr><td>default</td><td align="left">left</td><td align="center">center</td><td align="right">right</td></tr>
</tbody>
</table>
````````````````````````````````

To include a literal pipe character in any cell, it has to be escaped.

```````````````````````````````` example
Column 1 | Column 2
---------|---------
foo      | bar
baz      | qux \| xyzzy
quux     | quuz
.
<table>
<thead>
<tr><th>Column 1</th><th>Column 2</th></tr>
</thead>
<tbody>
<tr><td>foo</td><td>bar</td></tr>
<tr><td>baz</td><td>qux | xyzzy</td></tr>
<tr><td>quux</td><td>quuz</td></tr>
</tbody>
</table>
````````````````````````````````

Contents of each cell is parsed as an inline text which may contents any
inline Markdown spans like emphasis, strong emphasis, links etc.

```````````````````````````````` example
Column 1 | Column 2
---------|---------
*foo*    | bar
**baz**  | [qux]
quux     | [quuz](/url2)

[qux]: /url
.
<table>
<thead>
<tr><th>Column 1</th><th>Column 2</th></tr>
</thead>
<tbody>
<tr><td><em>foo</em></td><td>bar</td></tr>
<tr><td><strong>baz</strong></td><td><a href="/url">qux</a></td></tr>
<tr><td>quux</td><td><a href="/url2">quuz</a></td></tr>
</tbody>
</table>
````````````````````````````````

However pipes which are inside a code span are not recognized as cell
boundaries.

```````````````````````````````` example
Column 1 | Column 2
---------|---------
`foo     | bar`
baz      | qux
quux     | quuz
.
<table>
<thead>
<tr><th>Column 1</th><th>Column 2</th></tr>
</thead>
<tbody>
<tr><td><code>foo     | bar</code></td><td></td></tr>
<tr><td>baz</td><td>qux</td></tr>
<tr><td>quux</td><td>quuz</td></tr>
</tbody>
</table>
````````````````````````````````


## GitHub Issues

### [Issue 41](https://github.com/mity/md4c/issues/41)
```````````````````````````````` example
* x|x
---|---
.
<ul>
<li>x|x
---|---</li>
</ul>
````````````````````````````````
(Not a table, because the underline has wrong indentation and is not part of the
list item.)

```````````````````````````````` example
* x|x
  ---|---
x|x
.
<ul>
<li><table>
<thead>
<tr>
<th>x</th>
<th>x</th>
</tr>
</thead>
</table>
</li>
</ul>
<p>x|x</p>
````````````````````````````````
(Here the underline has the right indentation so the table is detected.
But the last line is not part of it due its indentation.)


### [Issue 42](https://github.com/mity/md4c/issues/42)

```````````````````````````````` example
] http://x.x *x*

|x|x|
|---|---|
|x|
.
<p>] http://x.x <em>x</em></p>
<table>
<thead>
<tr>
<th>x</th>
<th>x</th>
</tr>
</thead>
<tbody>
<tr>
<td>x</td>
<td></td>
</tr>
</tbody>
</table>
````````````````````````````````


### [Issue 104](https://github.com/mity/md4c/issues/104)

```````````````````````````````` example
A | B
--- | ---
[x](url)
.
<table>
<thead>
<tr>
<th>A</th>
<th>B</th>
</tr>
</thead>
<tbody>
<tr>
<td><a href="url">x</a></td>
<td></td>
</tr>
</tbody>
</table>
````````````````````````````````


### [Issue 138](https://github.com/mity/md4c/issues/138)

```````````````````````````````` example
| abc | def |
| --- | --- |
.
<table>
<thead>
<tr>
<th>abc</th>
<th>def</th>
</tr>
</thead>
</table>
````````````````````````````````