--- title: Lists and tables description: 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: ```mdx 1. Create a project. 2. Add a `docs.json`. 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 `*`: ```mdx - Markdown pages - Generated API pages - 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: ```mdx 1. Configure the site. - Set `name` and `base`. - Add a `logo`. 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: ````mdx 1. Create a project. ```sh reed init ``` 2. Check it. ```sh reed check ``` ```` 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](/docs/reference/components/procedural). `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: ```mdx | Command | What it does | |---|---| | `reed check` | Validates config and content | | `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: ```mdx | Left | Center | Right | |:---|:---:|---:| | 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. ```mdx | Option | Default | Notes | |---|---|---| | **`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: ```mdx | Operator | Meaning | |---|---| | `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: ```mdx Maximum number of results to return. Between 1 and 100. ``` 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](/docs/reference/components/api). ## Related - [Format text](/docs/authoring/formatting/text) - [Format code](/docs/authoring/formatting/code) - [Using components](/docs/authoring/components)