Skip to content
markdown→html

Syntax Reference

Markdown Tables

Markdown tables use pipes for columns and a required dash divider row for the header. Colons in the divider set column alignment. Tables are a GitHub Flavored Markdown feature that converts to an HTML table element.

Key facts

Column separator
Pipe character (|)
Required structure
Header row plus a dash divider row
Alignment markers
Colons: :--- left, :---: centre, ---: right
Specification
GitHub Flavored Markdown (not CommonMark)

How do you write a table in Markdown?

A Markdown table uses pipes (|) to separate columns and a divider row of dashes (---) beneath the header. Each line is one row; the first row is the header, and every following row is a data row.

A table needs 3 parts: a header row, a divider row of dashes, and one or more data rows. The pipes mark column boundaries and the divider row separates the header from the body. Paste a table into the Markdown Table to HTML to see its HTML instantly.

Outer pipes at the start and end of each line are optional, but cell counts must match across every row for the table to render.

markdown
| Name | Role |
| --- | --- |
| Ada | Engineer |
html
<table>
  <thead>
    <tr><th>Name</th><th>Role</th></tr>
  </thead>
  <tbody>
    <tr><td>Ada</td><td>Engineer</td></tr>
  </tbody>
</table>

Why does a Markdown table need a divider row?

The divider row of dashes is required because it marks where the header ends and the body begins. Without it, the parser treats the lines as plain paragraph text and no table renders.

The divider sits directly below the header row and uses at least one dash (-) per column. It produces the <thead> and <tbody> split in the HTML output. The header cells become <th> elements and data cells become <td>.

markdown
| Column |
| --- |
| Value |
html
<table>
  <thead>
    <tr><th>Column</th></tr>
  </thead>
  <tbody>
    <tr><td>Value</td></tr>
  </tbody>
</table>

How do you align Markdown table columns?

Add a colon to the divider row to set alignment. Use :--- for left, :---: for centre, and ---: for right. Each colon maps to a text-align value on that column's HTML cells.

3 alignment options exist: left (:---), centre (:---:), and right (---:). A column with no colon defaults to left alignment. The colon position in the divider, not the data rows, controls the alignment for the whole column.

markdown
| Left | Centre | Right |
| :--- | :---: | ---: |
| a | b | c |
html
<table>
  <thead>
    <tr>
      <th style="text-align:left">Left</th>
      <th style="text-align:center">Centre</th>
      <th style="text-align:right">Right</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td style="text-align:left">a</td>
      <td style="text-align:center">b</td>
      <td style="text-align:right">c</td>
    </tr>
  </tbody>
</table>

What can you put inside a table cell?

Table cells accept inline Markdown: bold, italic, inline code, and links. Block elements like lists, headings, and fenced code blocks are not allowed inside a cell. Escape a literal pipe as \|.

Inline formatting converts inside cells exactly as it does in a paragraph, so **bold** becomes <strong> and `code` becomes <code>. To show a pipe character as content rather than a column boundary, write it as \|.

markdown
| Style | Example |
| --- | --- |
| Bold | **text** |
| Code | `x = 1` |
html
<table>
  <thead>
    <tr><th>Style</th><th>Example</th></tr>
  </thead>
  <tbody>
    <tr><td>Bold</td><td><strong>text</strong></td></tr>
    <tr><td>Code</td><td><code>x = 1</code></td></tr>
  </tbody>
</table>

Are tables part of standard Markdown?

No. Tables are a GitHub Flavored Markdown (GFM) extension. The original CommonMark specification defines no table syntax, so pipe tables only render where GFM is enabled.

GitHub, GitLab, and most modern editors enable GFM, so pipe tables work in those environments. CommonMark-only parsers pass the pipe text through as a plain paragraph. See the full Markdown cheat sheet for every element and its HTML output.

Frequently Asked Questions

Why is my Markdown table not rendering?
A table needs a divider row of dashes directly below the header and an equal number of pipe-separated cells in every row. A missing divider or mismatched column counts stops the table from rendering.
How do I align a single column in a Markdown table?
Place a colon in that column's segment of the divider row. Use :--- for left, :---: for centre, and ---: for right. The colon controls alignment for the whole column, not just one cell.
Can a Markdown table cell span multiple rows or columns?
No. Markdown table syntax does not support rowspan or colspan. Every row has the same number of cells. Merged cells require writing raw HTML table markup instead of Markdown.
Do Markdown tables need outer pipes at the start and end of each line?
No. Leading and trailing pipes are optional. The cell boundaries are the pipes between columns, so a table renders correctly with or without the outer pipes on each row.