How to Put a List in a Markdown Table Cell

How do I put bullet points in a table cell?

Put a <ul> element in the cell with one <li> per item, and keep the whole thing on the same line as the rest of the row. GitHub's HTML sanitizer allows these tags, so you get real bullets with the normal list indentation.

| Release | Changes                                                              |
| :------ | :------------------------------------------------------------------- |
| 2.4.0   | <ul><li>Dark mode</li><li>CSV export</li><li>Faster search</li></ul> |
| 2.3.1   | <ul><li>Fix login redirect</li></ul>                                 |

The source gets long quickly. Run the table through the Markdown table formatter to pad the columns so the HTML stays readable, or edit it in the table editor and let it handle the pipes.

Why - item doesn’t work inside a cell

In GitHub Flavored Markdown a table row is one line of text, and each cell can contain only inline content: emphasis, code spans, links, images and inline HTML. A list is a block: it needs each item to start on its own line. Typing a dash inside a cell just prints a dash, and pressing Enter to start the next item ends the row. Inline HTML is the exception, because the parser copies the tags through as text and the browser builds the list.

The same rule keeps headings, fenced code blocks and nested tables out of cells; see code blocks in tables and nested tables.

Every way to show a list in a cell

Numbered lists in a cell

<ol> works the same way and gives you real numbering. Inline Markdown inside the <li> elements, such as code spans and links, still renders.

| Task            | Steps                                                                   |
| :-------------- | :---------------------------------------------------------------------- |
| Rotate API key  | <ol><li>Create a new key</li><li>Deploy it</li><li>Revoke the old key</li></ol> |
| Restore backup  | <ol><li>Stop the app</li><li>Run `restore.sh`</li><li>Start the app</li></ol> |

For a nested list, put the inner <ul> inside the parent <li> before its closing tag. It renders on GitHub and GitLab, but the source is hard to scan, so keep nesting to one level:

| Area     | Scope                                                                                |
| :------- | :----------------------------------------------------------------------------------- |
| Frontend | <ul><li>Forms<ul><li>Validation</li><li>Autosave</li></ul></li><li>Routing</li></ul> |

Portable bullets without list tags

If the renderer strips list tags, or you want the source to read well as plain text, type the bullet character and separate items with <br>. On Windows, type • with Alt+0149; on macOS, Option+8. The HTML entity • works too.

| Plan | Includes                                   |
| :--- | :----------------------------------------- |
| Free | • 3 projects<br>• Community support        |
| Pro  | • Unlimited projects<br>• Email support<br>• SSO |
| Ops  | 1. Back up<br>2. Upgrade<br>3. Verify      |

Where even <br> is shown as text (Reddit, many chat apps), drop the line breaks and use a separator. The line breaks guide lists where <br> works.

| Plan | Includes                                 |
| :--- | :--------------------------------------- |
| Free | 3 projects · Community support           |
| Pro  | Unlimited projects · Email support · SSO |

Task lists and checklists in a cell

Task lists (- [ ] item) are list items, so they can't live in a cell either. On GitHub, [ ] and [x] in a cell are shown as literal brackets and can't be clicked. Use emoji or Unicode boxes with <br>:

| Release step   | Checklist                                      |
| :------------- | :--------------------------------------------- |
| Prepare        | ✅ Changelog<br>✅ Version bump<br>⬜ Docs     |
| Ship           | ⬜ Tag release<br>⬜ Publish package           |

GitLab 18.9 and later render [x], [ ] and [~] as checkboxes, but only when the checkbox is the only content of the cell, so one box per cell rather than a list. For a clickable task list inside a table, use an HTML table with a Markdown task list in the cell (next section). All the options are compared in checkboxes in Markdown tables.

Real Markdown lists: HTML tables, Pandoc and MkDocs

GitHub and GitLab: Markdown inside an HTML table

Write the table itself in HTML. Inside a <td>, Markdown is parsed again as long as a blank line separates it from the tags, so ordinary lists, nesting and task-list items all work:

<table>
  <tr>
    <th>Plan</th>
    <th>Includes</th>
  </tr>
  <tr>
    <td>Pro</td>
    <td>

- Unlimited projects
- Email support
  - Response within one business day
- [x] SSO

</td>
  </tr>
</table>

Keep the closing </td> unindented: four spaces of indentation after a blank line turn it into a code block. The Markdown to HTML table converter gives you the HTML for an existing pipe table, so you only have to edit the one cell.

Pandoc and Quarto: grid tables

In a Pandoc grid table, each cell is a small Markdown document. Lists, nested lists and paragraphs work, and they survive conversion to Word, LaTeX and PDF, which raw HTML does not.

+------+------------------------------+
| Plan | Includes                     |
+======+==============================+
| Free | - 3 projects                 |
|      | - Community support          |
+------+------------------------------+
| Pro  | 1. Unlimited projects        |
|      | 2. Email support             |
|      |    - One business day        |
+------+------------------------------+

The Pandoc tables guide explains grid-table borders and the = line under the header.

MkDocs and Python-Markdown: md_in_html

Python-Markdown leaves HTML blocks alone unless the md_in_html extension is on. With it, add a markdown attribute to every enclosing element: <td> and <th> default to inline parsing, so use markdown="block" on the cell that holds the list.

# mkdocs.yml
markdown_extensions:
  - md_in_html
  - tables

<table markdown="1">
<tr markdown="1">
<td>Pro</td>
<td markdown="block">

- Unlimited projects
- Email support

</td>
</tr>
</table>

Lists in table cells by platform

Common mistakes (broken vs. fixed)

Pressing Enter between items

| Plan | Includes |
| :--- | :------- |
| Pro  | - Unlimited projects
- Email support |

Dashes on one line

| Plan | Includes                             |
| :--- | :----------------------------------- |
| Pro  | - Unlimited projects - Email support |

| Plan | Includes                                   |
| :--- | :----------------------------------------- |
| Free | • 3 projects<br>• Community support        |
| Pro  | • Unlimited projects<br>• Email support<br>• SSO |
| Ops  | 1. Back up<br>2. Upgrade<br>3. Verify      |

HTML list spread over several lines

| Plan | Includes |
| :--- | :------- |
| Pro  | <ul>
  <li>Unlimited projects</li>
  <li>Email support</li>
</ul> |

Formatting the HTML nicely splits the row into fragments. Collapse it onto one line, as in the first example on this page. The table validator flags rows whose cell count changed because of a stray line break.

No blank line inside the HTML cell

<td>
- Unlimited projects
- Email support
</td>

Without a blank line after <td>, the lines belong to the HTML block and are passed through as text. Add a blank line after the opening tag and another before the closing tag.

When to restructure instead

Lists in cells are fine for two to five short items. Past that, the table gets tall and hard to compare across rows. Better shapes for the same data:

• One row per item. Repeat the key column (Plan, Release) and give each list item its own row. This sorts, filters and diffs better.
• Move the list below the table. Keep a short summary in the cell and link to a heading that holds the full list.
• Hide the detail. A <details> block can hold a long list, or the whole table; see collapsible tables.
• Switch to an HTML table when cells need several lists, paragraphs or code blocks, using the blank-line pattern above.

For the rest of the cell rules, see the Markdown table syntax guide.

Frequently asked questions