TopolearnTables are the clearest way to show options, parameters and comparisons in docs.
Tables are a GitHub Flavored Markdown extension supported almost everywhere (GitHub, GitLab, most static site generators, VS Code preview) but not part of core CommonMark.
| Option | Default | Description |
| -------- | :-----: | ------------------ |
| `port` | 8080 | Port to listen on |- The first row is the header; the second is the delimiter row of dashes, required.
- Colons set alignment:
:---left,:---:centre,---:right. - Leading and trailing pipes are optional, and the columns don't have to line up in the source, though aligned source is easier to read.
- Cells contain inline Markdown only: code, emphasis, links. No block content such as lists or multiple paragraphs; use
<br>for a line break if the renderer allows HTML. - Escape a literal pipe inside a cell as
\|, including inside code spans in a table. - The table ends at a blank line or another block-level start.
For anything complex (merged cells, multi-paragraph cells) use an HTML table, a list of sections, or a definition-style layout instead. Formatters like Prettier realign table columns automatically, which keeps the source readable.
Example
| Command | Alias | Time (s) | Notes |
| :------------ | :---: | -------: | ------------------------- |
| `make build` | `mb` | 12.5 | Compiles everything |
| `make test` | `mt` | 4.0 | Runs **unit** tests |
| `grep a\|b` | | 0.1 | Pipe escaped inside a cell |
Rows don't need aligned pipes:
Name | Value
--- | ---
x | 1Remember
- Header row, then a --- delimiter row, then data rows
- Colons in the delimiter row set left, centre or right alignment
- Cells hold inline content only; escape | as \|
Watch out for
- Trying to put a bullet list inside a table cell; it renders as literal text.