Markdown vs HTML Tables: When to Drop Down

The trade-off in one paragraph

Markdown tables are easier to read and write in source. HTML tables can express things markdown can't. For 90% of tables — text, simple alignment, no merged cells — markdown is the better tool. For the remaining 10%, drop into HTML inside the markdown document.

What markdown tables can't do

1. Row spans. A cell that spans two rows. Markdown has no syntax for this.
2. Column spans. A header that spans two columns. Markdown has no syntax for this.
3. Per-cell alignment. Markdown alignment is set per column. If row 1's "Date" cell is right-aligned but row 2's needs to be left-aligned for some reason, markdown can't express it.
4. Inline cell styles. Background colors, font weights, custom borders — markdown has no concept of styling.
5. Footer rows. Markdown has no <tfoot> equivalent. Some renderers infer one from the last row's syntax, but this is non-standard.
6. Captions. The <caption> element doesn't exist in markdown. Use a paragraph above the table instead.
7. Headers on the left side. A table where the first column is itself a header (the <th scope="row"> pattern). Markdown's header is always the top row.

If your table needs any of these, drop into HTML.

What HTML tables lose

The cost is verbosity. The same table in markdown:

| Name  | Role     |
|:------|:---------|
| Alice | Engineer |
| Bob   | Designer |

And in HTML:

<table>
  <thead>
    <tr><th>Name</th><th>Role</th></tr>
  </thead>
  <tbody>
    <tr><td>Alice</td><td>Engineer</td></tr>
    <tr><td>Bob</td><td>Designer</td></tr>
  </tbody>
</table>

Five times more characters. Three times the visual noise in the source. For a tiny table this is fine; for a 30-row table it's a maintenance burden.

The decision tree

Five questions, in order. Stop at the first "yes":

1. Do you need row or column spans? If yes, HTML.
2. Do you need per-cell styling (colors, weights, borders)? If yes, HTML.
3. Will this render in a markdown environment that strips HTML (Reddit, Discord, Stack Overflow)? If yes, markdown — find a way to express the data without the HTML-only feature.
4. Will the table grow past 20 rows? If yes, markdown — the source readability matters more than the styling features.
5. Otherwise: markdown.

Embedding HTML inside markdown — the workflow

Most markdown environments (GitHub, GitLab, Notion, Obsidian, MkDocs, Docusaurus, MDX) pass through raw HTML inside a markdown document. The pattern:

# My document

Some markdown text here.

<table>
  <thead>
    <tr><th rowspan="2">Item</th><th colspan="2">Q1</th></tr>
    <tr><th>Plan</th><th>Actual</th></tr>
  </thead>
  <tbody>
    <tr><td>Revenue</td><td>$100k</td><td>$112k</td></tr>
  </tbody>
</table>

More markdown after the table.

The HTML block doesn't get parsed as markdown — anything inside it stays as raw HTML. Markdown formatting around it works normally.

Two practical notes:

• Most markdown engines require a blank line before and after the HTML block.
• Inside the HTML, markdown formatting does not work. You can't use **bold** inside an HTML cell — write <strong>bold</strong> instead.

The styled-with-HTML, content-in-markdown pattern

For documentation sites with a build step (MkDocs, Docusaurus, Astro), there's a third option: define the table structure in markdown and apply styling via CSS targeting the rendered HTML. This keeps the source clean and lets a single CSS file style every table consistently. The trade-off is that this only works in environments with a build step — it doesn't help on GitHub, Reddit, or anywhere else markdown is rendered without your CSS.

The three rules of thumb

1. Default to markdown. Easier to read, easier to maintain, works everywhere markdown does.
2. Drop to HTML when the data structure demands it. Spans, complex alignment, or styling you can't get any other way.
3. Don't mix unnecessarily. If you start a table in HTML, keep it in HTML. Mid-table mode-switching is where parsers break.

For the full markdown table reference, see The Complete Guide to Markdown Tables. For the printable cheatsheet, see Markdown Table Cheatsheet.