AnymarkMarkdown tables, properly: alignment, wide tables, merged cells and the HTML escape hatch
Markdown tables are the part of the format people get wrong most often, because the syntax is strict and the error messages are nonexistent: a table that is off by one pipe simply renders as a paragraph of pipes.
The syntax
| Region | Q1 | Q2 | Total |
|--------|----:|----:|------:|
| North | 120 | 135 | 255 |
| South | 98 | 101 | 199 |
Three rules. The first row is the header. The second row is the separator and must have at least three dashes per column. Every row needs the same number of cells, counted by pipes. Leading and trailing pipes are optional in most readers but make the table easier to read as text, so keep them.
Alignment
A colon in the separator row sets the alignment: :--- left (the default), ---: right, :---: centred. Numbers should be right-aligned so the digits line up; text left. Converters that ignore alignment produce tables that look wrong even when every value is correct. Anymark sets it from the content when converting spreadsheets and PDFs.
Padding, or not
Spaces inside cells are ignored, so you can line the pipes up for readability or not bother. The example above is padded; |North|120|135|255| renders identically. Padded tables are easier to review in source view; unpadded ones are easier to edit by hand. Pick one per file.
Pipes and line breaks inside cells
A literal pipe inside a cell has to be escaped: \|. A line break inside a cell is not possible in the pipe syntax; use <br> where the reader allows HTML, or restructure. A cell cannot contain a list or a code block.
Wide tables
A table with twelve columns is legal and unreadable in a narrow window. Options: split it into two tables sharing a key column; drop columns that are not needed in this document; or accept horizontal scrolling, which the Anymark editor and most renderers provide. Do not shrink the text to fit; that is a print-layout problem, and when Anymark prints a wide table it does scale it to the page.
Merged cells: the HTML escape hatch
Pipe tables cannot span cells. If a heading cell covers three columns, you have two honest choices: repeat or leave the extra cells empty, or write the table in HTML, which Markdown allows:
<table>
<tr><th colspan="3">Sales by region</th></tr>
<tr><td>North</td><td>120</td><td>135</td></tr>
</table>
Every major Markdown reader renders this. Anymark writes merged tables this way when converting, and its editor shows and edits them as tables rather than as raw HTML, so the structure survives a round of editing.
A checklist for a table that will not render
- Count the pipes in the header and in the row that misbehaves.
- Check the separator row has at least three dashes per column and nothing else but colons.
- Look for an unescaped pipe inside a cell.
- Make sure there is a blank line before the table.
Four checks, thirty seconds, and the table appears.