Lists and tables

Ordered, unordered and nested lists, GFM tables, and when to use Steps or ParamField instead.

Lists and tables are plain markdown in Reed. Both render without components. This page covers the syntax, the limits a real build shows, and the two points where a component does the job better.

Lists

Ordered lists

Start each item with a number and a period:

1
1. Create a project.
2
2. Add a `docs.json`.
3
3. Run `reed build`.

The numbers you type after the first do not matter; the list counts up from the first one. Start with a number other than 1 and the list starts there: a list whose first item is 3. renders as 3, 4, 5.

Two lists separated only by a blank line merge into one. Put a sentence or a heading between them to keep them apart.

Unordered lists

Start each item with - or *:

1
- Markdown pages
2
- Generated API pages
3
- The markdown mirror

Pick one marker and use it for the whole list. Switching from - to * partway through starts a new list.

Nested lists

Indent a child item to line up with the text of its parent. Ordered and unordered lists nest inside each other:

1
1. Configure the site.
2
   - Set `name` and `base`.
3
   - Add a `logo`.
4
2. Write pages.

Keep nesting to two levels. A third level usually means the content wants a heading or a table instead.

Lists with code

A fenced block can sit inside a list item. Indent the fence to line up with the item’s text:

1
1. Create a project.
2

3
   ```sh
4
   reed init
5
   ```
6

7
2. Check it.
8

9
   ```sh
10
   reed check
11
   ```

When every item of an ordered list holds a fenced block, Reed raises DS-D04, a warning that suggests Steps. A list like that is a procedure, and Steps gives each step a heading and a visual track. Put each step’s explanation in the Step and the command directly after the Steps element, since fences belong at the top level of the page. See Steps, tabs and code.

DS-D04 does not fail a build unless you pass --strict-components.

Task lists

Task-list syntax, - [ ] item and - [x] item, is not rendered. You get an ordinary bullet with the literal text [ ] item. Use a plain list, and say in the text what is done and what is not.

Tables

Reed renders GitHub-flavored markdown tables. A header row, a delimiter row of hyphens, then one row per line:

1
| Command | What it does |
2
|---|---|
3
| `reed check` | Validates config and content |
4
| `reed build` | Builds the static site |

The outer pipes are optional, but include them. They make the source easier to read and to diff.

Column alignment

Colons in the delimiter row set each column’s alignment:

1
| Left | Center | Right |
2
|:---|:---:|---:|
3
| a | b | 1.00 |

:--- is left, :---: is centered, ---: is right. Right-align columns of numbers so the digits line up.

You cannot set column widths. Columns size to their content.

Formatting inside cells

Inline formatting works in cells: bold, italic, inline code and links.

1
| Option | Default | Notes |
2
|---|---|---|
3
| **`base`** | none | See [Navigation](/docs/authoring/navigation) |

A cell holds one line. You cannot put a list, a paragraph break or a fenced block in a cell. If a cell needs any of those, the content is not tabular; use a list or headings.

Pipes in cells

A literal | in a plain-text cell cannot be escaped. Both \| and the entity | still split the cell in two, and the rest of the row shifts across.

Inside inline code, \| works. The backslash is removed and a single pipe is shown:

1
| Operator | Meaning |
2
|---|---|
3
| `a \|\| b` | Logical or |

If the pipe is not code, reword the cell, for example “a or b” instead of “a | b”.

When a table beats a list

Use a table when every item has the same set of attributes and the reader will compare them across rows: commands and what they do, options with their defaults, codes with their severity. The columns do the work of repeated labels.

Use a list when the items are single ideas or sentences, when they have different shapes, or when the order matters. A two-column table whose second column is a full sentence is usually a list with bold lead-ins.

A table wider than the content column scrolls sideways, which is easy to miss on a phone. Keep tables to three or four columns.

API parameters

For request parameters and response fields, use ParamField and ResponseField instead of a table:

1
<ParamField name="limit" type="integer" in="query" default="20">
2
  Maximum number of results to return. Between 1 and 100.
3
</ParamField>

Each one carries a name, type, location, default and required flag, and a description of any length. A table cell can hold one line; a parameter often needs a paragraph and an example. These components are for documenting an interface by hand; endpoint pages generated from an OpenAPI spec do not use them, because those are rendered by the starlight-openapi plugin. See API reference components.