Markdown Table Without a Header (and Table Captions)

How do I make a Markdown table without a header?

A GFM table is recognised by a header row followed by a delimiter row, and both must have the same number of cells. There is no way to skip the header, but the header cells can be empty. That is the standard workaround on GitHub, GitLab, VS Code, Jupyter and every other GFM-based renderer:

|              |                     |
| ------------ | ------------------- |
| **Version**  | 2.4.1               |
| **License**  | MIT                 |
| **Node**     | 20 or later         |
| **Homepage** | https://example.com |

Some people fill the header with   instead of spaces. The output is the same: an empty-looking header row. Use whichever survives your formatter.

|   |   |
| :----- | :----- |
| Host   | db.internal:5432 |
| Pool   | 20 connections   |

Before reaching for a workaround, ask whether the table really has no header. A two-column settings table almost always has one (“Setting | Value”, “Field | Description”). A short real header costs one line, renders identically everywhere and gives screen-reader users context for every cell, which blank headers don't.

| Setting  | Value            |
| :------- | :--------------- |
| Host     | db.internal:5432 |
| Pool     | 20 connections   |
| SSL mode | `require`        |

Every way to get a headerless table

True headerless tables: kramdown, Pandoc and HTML

kramdown (Jekyll and GitHub Pages)

In kramdown, a row only becomes a header when a separator line follows it. Leave the separator out and every row is a body row. Start each row with a pipe. This is the syntax to use on GitHub Pages sites, which build with Jekyll and kramdown, but note that the same file viewed on github.com is parsed as GFM, where these lines are not a table.

| Host | db.internal:5432 |
| Pool | 20 connections   |
| SSL  | require          |

Pandoc, Quarto and R Markdown

Pandoc's pipe tables need a header, just like GFM; the Pandoc manual suggests blank header cells to simulate a headerless one. Its other three styles can drop the header natively. A simple table without a header must start and end with a dashed line:

-------  ----------------
Host     db.internal:5432
Pool     20 connections
SSL      require
-------  ----------------

Multiline tables work the same way, and a grid table is headerless when it has no +===+ line:

+------+------------------+
| Host | db.internal:5432 |
+------+------------------+
| Pool | 20 connections   |
+------+------------------+

HTML: a table with only a body

Wherever raw HTML is allowed (GitHub, GitLab, Obsidian, VS Code, Jupyter, most static site generators), a table without <thead> has no header row at all. Marking the label cells as <th scope="row"> keeps them bold and tells assistive technology they label their row.

<table>
  <tbody>
    <tr>
      <th scope="row">Host</th>
      <td><code>db.internal:5432</code></td>
    </tr>
    <tr>
      <th scope="row">Pool</th>
      <td>20 connections</td>
    </tr>
  </tbody>
</table>

MkDocs, Docusaurus and Hugo: hide the empty header with CSS

MkDocs (Python-Markdown), Docusaurus (remark-gfm) and Hugo (Goldmark) all follow the GFM rule, so they need the empty header row too. Because you control the site's CSS, you can hide that row. The selector below matches a <thead> in which no header cell has content, so normal tables are untouched:

/* docs/stylesheets/extra.css — hide a header row whose cells are all empty */
table thead:not(:has(th:not(:empty))) {
  display: none;
}

# mkdocs.yml
extra_css:
  - stylesheets/extra.css

Use empty cells (|  |), not  , with this rule: a cell containing a non-breaking space is not :empty. In Docusaurus add the rule to src/css/custom.css; in Hugo, to your theme's stylesheet. For Python-Markdown there are also third-party extensions, such as markdown-tables-extended, that accept tables without a header.

How do I add a caption to a Markdown table?

GFM has no caption syntax. Each toolchain that does support captions uses its own, so pick the one your renderer understands:

GitHub and other GFM renderers

Put the caption in a bold line or a small heading directly above the table. It isn't tied to the table in the HTML, but it reads correctly and works everywhere.

**Table 1.** Response time by region (p95, ms)

| Region | p95 |
| :----- | --: |
| EU     | 120 |
| US     | 95  |

For a real <caption> element, which screen readers announce with the table, write the table in HTML. GitHub keeps the element.

<table>
  <caption>Table 1. Response time by region (p95, ms)</caption>
  <thead>
    <tr><th>Region</th><th>p95</th></tr>
  </thead>
  <tbody>
    <tr><td>EU</td><td>120</td></tr>
    <tr><td>US</td><td>95</td></tr>
  </tbody>
</table>

Pandoc, R Markdown and Quarto

Pandoc reads a paragraph that starts with Table: (or just :) next to a table as its caption. The same syntax works in R Markdown documents, which are rendered by Pandoc.

| Region | p95 |
| :----- | --: |
| EU     | 120 |
| US     | 95  |

Table: Response time by region (p95, ms)

Quarto adds a label in braces so the table is numbered and can be cross-referenced:

| Region | p95 |
| :----- | --: |
| EU     | 120 |
| US     | 95  |

: Response time by region (p95, ms) {#tbl-latency}

See @tbl-latency for the numbers.

For a table produced by code, give the caption to the function or the cell. In R Markdown use knitr::kable()'s caption argument; in Quarto use the tbl-cap cell option with a tbl- label.

```{r latency}
knitr::kable(latency, caption = "Response time by region (p95, ms)")
```

```{r}
#| label: tbl-latency
#| tbl-cap: "Response time by region (p95, ms)"
knitr::kable(latency)
```

MultiMarkdown and MkDocs

MultiMarkdown takes a caption in square brackets on the line directly above or below the table, with an optional label for links:

| Region | p95 |
| :----- | --: |
| EU     | 120 |
| US     | 95  |
[Response time by region][latency]

In MkDocs, enable pymdownx.blocks.caption from PyMdown Extensions and put a caption block after the table. It wraps the table in a <figure> with a <figcaption>.

| Region | p95 |
| :----- | --: |
| EU     | 120 |
| US     | 95  |

/// table-caption
Response time by region (p95, ms)
///

Header column: making the left column a header

Searches for a “header column” or “left column header” usually mean a table whose first column labels each row, like a pricing comparison. GFM has no syntax for row headers. The common approach is to bold the first column:

| Plan     | Free | Pro   |
| :------- | :--: | :---: |
| **Seats**    | 1    | 10    |
| **Storage**  | 1 GB | 1 TB  |
| **Support**  | —    | Email |

Bold only changes the look; the cells are still <td>, so a screen reader doesn't announce them as headers. When accessibility matters, write the table in HTML with <th scope="row"> in each row (as in the HTML example above). If the labels belong on top, swap rows and columns with the table transposer.

Headerless tables and captions by platform

Common mistakes and fixes

Starting with the delimiter row

Deleting the header line leaves the delimiter row on top. GFM then finds no table and shows the pipes as text.

| --- | --- |
| Host | db.internal:5432 |
| Pool | 20 connections   |

|              |                     |
| ------------ | ------------------- |
| **Version**  | 2.4.1               |
| **License**  | MIT                 |
| **Node**     | 20 or later         |
| **Homepage** | https://example.com |

One empty header cell for a two-column table

| | is a single header cell. The delimiter row has two, so the counts don't match and nothing renders. Give the header one empty cell per column.

| |
| --- | --- |
| Host | db.internal:5432 |

Caption syntax on the wrong renderer

Table: …, : … and […] are not GFM. On GitHub they render as a stray paragraph, and [Caption] directly under a table becomes an extra row. Use a bold line there instead.

Markdown inside an HTML table

Inside <td>, **bold** and backticks are only processed if blank lines separate them from the tags. Use <b> and <code> instead. Check structure problems with the table validator.

When to switch to HTML

Stay with pipe tables and an empty or short header for READMEs and docs people edit as text. Switch to HTML when you need:

• no header row at all, on a GFM renderer
• a real <caption> or row headers (<th scope="row">) for accessibility
• merged cells as well (see merged cells)

The Markdown to HTML converter gives you a starting point to edit. For the rest of the table rules, see Markdown table syntax; to keep long key–value tables out of the way, see collapsible tables, and for widths see column width.

Frequently asked questions