Tables

A table is for data with two directions: rows that are items and columns that are properties of them. Constants and their values, methods and their convergence rates, a week of lectures and their topics. If your data has only one direction, a list reads better.

Syntax

A table is a header row, a delimiter row of hyphens, and any number of data rows, with cells separated by |:

| Constant | Symbol | Value |
|---|---|---|
| Pi | $\pi$ | 3.14159 |
| Euler's number | $e$ | 2.71828 |
| Golden ratio | $\varphi$ | 1.61803 |

• The header row is required. Screen readers announce each cell with its column's header, so a good header is the difference between "3.14159" and "Value: 3.14159".
• The delimiter row needs at least one hyphen per column (|---|---|).
• The columns do not need to line up in the source, though aligned source is easier to edit by hand.
• The outer pipes are optional, but keeping them makes the source easier to read and to diff.
• A short row is completed with empty cells, and extra cells beyond the header are dropped, so a missing | shows up as a blank rather than as a broken table.

Aligning columns

A colon in the delimiter row sets the alignment of that column: on the left for left, on the right for right, on both sides for centre.

| Method | Order | Error at $h = 0.1$ |
|:---|:---:|---:|
| Euler | 1 | 0.0512 |
| Midpoint | 2 | 0.00171 |
| Runge--Kutta 4 | 4 | 0.0000021 |

Right-align numbers, and give them the same number of decimal places when you can, so the digits line up and the reader compares magnitudes at a glance. Centre short labels and symbols. Leave text left-aligned.

What a cell can hold

A cell holds one line of inline content: text, emphasis, code, links, inline maths and mentions.

| Operation | Syntax | Meaning |
|---|---|---|
| Or | `a \| b` | $a \lor b$ |
| Implication | `a -> b` | $a \Rightarrow b$ |
| Negation | `!a` | $\lnot a$ |

• A literal pipe inside a cell, even inside code, is written \|. Otherwise it ends the cell.
• A line break inside a cell is <br>, the one piece of HTML that tables need:

| Week | Topics |
|---|---|
| 1 | Limits<br>Continuity |
| 2 | The derivative<br>Rules of differentiation |

• Block content does not fit in a cell: no lists, no paragraphs, no display maths, no code blocks. A line starting with - in a cell stays the literal text. If a cell needs a paragraph, the data has outgrown a table: make each row a short section with a heading, or a list item with its details under it.

Wide tables

A table cannot be narrower than its content. When it is wider than the reading column, it scrolls sideways inside its own box while the rest of the page stays still, which is what happens on a phone for most tables with more than three or four columns. Still, keep tables as narrow as the data allows:

• Put units in the header (Time (s)) instead of in every cell.
• Abbreviate long repeated words, and say what the abbreviation means once, in the text above the table.
• Split a table with many columns into two tables that each answer one question.

Captions

Markdown tables have no caption syntax. Say what the table shows in the sentence before it, the way this page does, or put it under a heading of its own when readers should be able to link to it. A table that the text refers to by number ("see Table 2") works best with the number in that sentence or heading.

Raw HTML tables

A raw HTML <table> is allowed, within the permitted HTML, for the rare table Markdown cannot express, such as a cell spanning two columns. It scrolls the same way when wide. Prefer the Markdown form whenever it fits: it is shorter, easier to read in the source, and the editor can edit it as a table.