Markdown Tables in Hugo, Jekyll, MkDocs and Docusaurus

Which Markdown parser does each site generator use?

| Setting   | Default | Where        |
| :-------- | :------ | :----------- |
| `baseURL` | —       | site config  |
| `theme`   | none    | site config  |

Styling is always the theme's job: none of the four gives you borders, striping or widths from the Markdown itself. That is why most of this page is about CSS hooks.

Hugo: Goldmark tables, raw HTML and render hooks

Hugo renders Markdown with Goldmark, and the GitHub-style table extension is on by default. The rules are the GFM rules: a header row, a delimiter row with the same cell count, and a blank line before the table. See the Markdown table syntax guide for the details.

Raw HTML needs unsafe

Since Hugo 0.60, Goldmark omits raw HTML in Markdown files and writes an HTML comment in its place. If your table (or a <br> in a cell, or a centering <div>) vanishes, enable the setting. The name reflects the trade-off: only do this for content you trust.

# hugo.toml
[markup.goldmark.renderer]
  unsafe = true   # keep raw HTML (otherwise it is replaced by a comment)

# hugo.yaml
markup:
  goldmark:
    renderer:
      unsafe: true

Shortcodes are the alternative: they run template code, not raw HTML, so they work without unsafe.

A render hook for every table

Hugo 0.134 and later can override how Markdown tables are rendered with a render-table.html hook. It is the clean way to wrap every table in a scroll container or add a theme class without touching the content:

{{/* layouts/_default/_markup/render-table.html (a sketch; check the render hook docs for current fields) */}}
<div class="table-wrap">
  <table>
    <thead>
      {{- range .THead }}
        <tr>
          {{- range . }}
            <th{{ with .Alignment }} style="text-align: {{ . }}"{{ end }}>{{ .Text }}</th>
          {{- end }}
        </tr>
      {{- end }}
    </thead>
    <tbody>
      {{- range .TBody }}
        <tr>
          {{- range . }}
            <td{{ with .Alignment }} style="text-align: {{ . }}"{{ end }}>{{ .Text }}</td>
          {{- end }}
        </tr>
      {{- end }}
    </tbody>
  </table>
</div>

Hugo's Markdown attribute syntax ({.class}) is a separate feature that has to be enabled in the parser settings, and its support for tables has varied. For a class on a single table, wrapping it in an HTML element is the dependable route.

Jekyll: kramdown tables, classes and headerless tables

Jekyll uses kramdown, and GitHub Pages is locked to it. kramdown has its own table syntax with three extras that GFM lacks, and it also accepts the GFM style:

# _config.yml
markdown: kramdown
kramdown:
  input: GFM
  parse_block_html: true   # lets markdown="1" work inside HTML blocks

• Classes and IDs through an inline attribute list on the line directly after the table:

| Plan | Price |
|:-----|------:|
| Free |    $0 |
| Pro  |   $12 |
{: .table .table-striped #pricing }

• No header. Leave out the separator line. A table with no separator has no <thead>:

| Version  | 2.4.1       |
| Released | 2026-03-02  |
| License  | MIT         |

• A footer. A line of = signs starts a <tfoot>:

| Item  | Cost |
|-------|-----:|
| Tea   |    3 |
| Cake  |    5 |
|=======|======|
| Total |    8 |

These are kramdown only. The same text on GitHub.com, GitLab or Hugo renders differently, so don't copy kramdown tables into a README. Raw HTML in Jekyll Markdown is passed through, and kramdown can parse Markdown inside an HTML block if you set parse_block_html or add markdown="1" to the element. A cell that contains {{ }} or {% %} is processed by Liquid first; wrap it in {% raw %}. GitHub-specific notes are in the GitHub Pages section of the README guide.

MkDocs and Material: Python-Markdown tables

MkDocs uses Python-Markdown. Its tables extension is enabled by default, so pipe tables work without configuration. Two extensions are worth adding:

# mkdocs.yml
markdown_extensions:
  - tables        # on by default in MkDocs
  - md_in_html    # Markdown inside <div markdown>
  - attr_list

Python-Markdown tables need a header row and a blank line before the table. A table inside a list item must be indented by four spaces. The Material theme restyles tables; its documentation covers its table classes and its use of md_in_html for HTML layouts.

Python guides. If you also generate tables from Python code, see Markdown tables in Python.

Docusaurus: tables in MDX

Docusaurus compiles .md and .mdx files as MDX, with GFM tables supported out of the box. MDX treats { as the start of a JavaScript expression and < as the start of JSX, so a table cell can fail to build for reasons that don't exist in other Markdown. If you replace the MDX pipeline, add remark-gfm yourself; the React tables guide covers that setup.

Docusaurus 3 can also treat .md files as plain CommonMark through its markdown.format setting, which avoids the JSX rules for those files. Check the current docs for the option on your version.

How do I add a class or set column widths?

Markdown has no syntax for classes or widths, so everything goes through the theme's CSS or a wrapper element. A wrapper with a class is the one technique that works on all four.

MkDocs with the Material theme: wrap the table, then give the rule extra weight so Material's default table styles (shrink-to-content) don't win:

<div class="wide-table" markdown>

| Option   | Description                       |
| :------- | :-------------------------------- |
| `site_name` | Shown in the header and title |
| `nav`       | Page order and grouping      |

</div>

/* docs/stylesheets/extra.css  (listed under extra_css in mkdocs.yml) */
.md-typeset .wide-table table:not([class]) { display: table; width: 100%; }
.md-typeset .wide-table th:nth-child(1) { width: 25%; }
.md-typeset .wide-table th:nth-child(2) { width: 75%; }

For Docusaurus, the blank lines inside the div are what make the table Markdown again:

<div className="wide-table">

| Option      | Description                              |
| :---------- | :--------------------------------------- |
| `routeBasePath` | URL prefix for the docs                |
| `sidebarPath`   | Path to the sidebar file               |

</div>

/* src/css/custom.css */
.wide-table table { display: table; width: 100%; }
.wide-table th:nth-child(1) { width: 30%; }

To wrap every table at once (for example, to scroll on phones), map the table element in src/theme/MDXComponents.js:

// src/theme/MDXComponents.js
import MDXComponents from '@theme-original/MDXComponents';

export default {
  ...MDXComponents,
  // wrap every Markdown table in a scroll container
  table: (props) => (
    <div style={{ overflowX: 'auto' }}>
      <table {...props} />
    </div>
  ),
};

More options are in column width and table styling.

Tables without a header, and merged cells

Of these four, only kramdown (Jekyll) supports a table with no header row in Markdown syntax. In Hugo, MkDocs and Docusaurus, pick one of two workarounds:

1. An empty header row plus CSS that hides it:

|     |     |
| :-- | :-- |
| Version  | 2.4.1 |
| Released | 2026-03-02 |

/* Hide a header row whose cells are all empty (needs :has() support) */
thead:not(:has(th:not(:empty))) { display: none; }

2. An HTML table with only <tr><td> rows. This also gives you merged cells. In Docusaurus use JSX attribute names:

<table>
  <thead>
    <tr>
      <th rowSpan={2}>Plan</th>
      <th colSpan={2}>Limits</th>
    </tr>
    <tr>
      <th>Users</th>
      <th>Storage</th>
    </tr>
  </thead>
  <tbody>
    <tr><td>Team</td><td>10</td><td>100 GB</td></tr>
  </tbody>
</table>

Merged cells need HTML on every generator. In Hugo that means unsafe = true, and in MkDocs md_in_html if the cells contain Markdown. See merged cells in Markdown tables and why a table might not render.

Can these tables be sortable?

None of the four sorts tables on its own, because Markdown renders to static HTML. They all accept a small JavaScript library:

• MkDocs Material: its documentation describes loading tablesort and applying it to every table that has no class:

# mkdocs.yml (Material for MkDocs)
extra_javascript:
  - https://unpkg.com/tablesort@5.3.0/dist/tablesort.min.js
  - javascripts/tablesort.js

// docs/javascripts/tablesort.js
document$.subscribe(function () {
  var tables = document.querySelectorAll("article table:not([class])");
  tables.forEach(function (table) {
    new Tablesort(table);
  });
});

• Hugo and Jekyll: add the script to your base layout and call it on tables with a chosen class.
• Docusaurus: use a client-side component, such as one registered through MDX components.
• Sort the source instead. The Markdown table sorter orders rows before you commit. See sortable tables.

Generating tables from data files

When the same data appears in several pages, keep it in a data file and generate the table. You get one source of truth and no hand-aligned pipes.

Hugo: a data file and a shortcode

# data/plans.yaml
- name: Free
  price: "$0"
  seats: 1
- name: Pro
  price: "$12"
  seats: 10

{{/* layouts/shortcodes/plans-table.html */}}
<div class="table-wrap">
  <table>
    <thead>
      <tr><th>Plan</th><th>Price</th><th>Seats</th></tr>
    </thead>
    <tbody>
      {{- range site.Data.plans }}
        <tr><td>{{ .name }}</td><td>{{ .price }}</td><td>{{ .seats }}</td></tr>
      {{- end }}
    </tbody>
  </table>
</div>

{{< plans-table >}}

Jekyll: _data and a Liquid loop

{% comment %} _includes/plans-table.html, data in _data/plans.yml {% endcomment %}
{% assign plans = site.data.plans | sort: "price" %}
<table>
  <thead>
    <tr><th>Plan</th><th>Price</th></tr>
  </thead>
  <tbody>
    {% for plan in plans %}
      <tr><td>{{ plan.name }}</td><td>{{ plan.price }}</td></tr>
    {% endfor %}
  </tbody>
</table>

{% include plans-table.html %}

MkDocs: the table-reader plugin

The mkdocs-table-reader-plugin package reads CSV, Excel, YAML and other files and inserts them as Markdown tables. Install it with pip, enable it, and call it from a page; check its documentation for how paths are resolved:

# mkdocs.yml
plugins:
  - search
  - table-reader

{{ read_csv('tables/plans.csv') }}

Docusaurus: import JSON and map it

import plans from './plans.json';

<table>
  <thead>
    <tr><th>Plan</th><th>Price</th></tr>
  </thead>
  <tbody>
    {plans.map((p) => (
      <tr key={p.name}><td>{p.name}</td><td>{p.price}</td></tr>
    ))}
  </tbody>
</table>

If the data starts life in a spreadsheet, convert it once with CSV to Markdown table or Excel to Markdown table and paste the result, or turn Markdown tables into JSON with Markdown table to JSON for a data file.

Common problems

For a table that won't render anywhere, run it through the Markdown table validator. To write the table in a grid and copy clean Markdown, use the table generator.

Frequently asked questions