Markdown Table Syntax: How to Make a Table in Markdown

How to create a table in Markdown

1. Write the header row. Put each column name between pipes: | Name | Role | Team |.
2. Add the delimiter row directly below it, with one cell of hyphens per column: | --- | --- | --- |. The number of cells must match the header.
3. Add one line per data row, using the same pipes: | Ada | Engineer | Platform |. The pipes don't have to line up.
4. Leave a blank line before and after the table, then preview it. Escape any literal pipe in a cell as \|.

| Name   | Role      | Team     |
| ------ | --------- | -------- |
| Ada    | Engineer  | Platform |
| Grace  | Architect | Compiler |
| Hedy   | Designer  | Radio    |

Prefer clicking to typing pipes? The Markdown table generator builds the same syntax from a spreadsheet-style grid, and the converters turn CSV, Excel or HTML tables into Markdown.

Try it: live table playground

Edit the source below. The preview follows GitHub's rules and tells you when the structure would stop the table from rendering.

Table structure rules

These are the rules from the GFM specification that decide whether text becomes a table. Other flavors follow them closely.

• The header and delimiter rows must have the same number of cells. If they don't, nothing is rendered as a table.
• Each delimiter cell needs at least one hyphen, with an optional colon at either end. Spaces around the hyphens are fine.
• Data rows may have fewer or more cells than the header: missing cells render empty, and extra cells are dropped.
• Outer pipes are optional in GFM, but keep them: they make the source easier to read, and some parsers (such as kramdown) expect rows to start with a pipe. A one-column table needs them.
• Spacing doesn't matter. Padding cells so the pipes line up is only for people reading the source.
• The table ends at the first blank line. In GFM, a plain line directly under a table becomes one more row, so always end a table with a blank line.

Name|Role|Team
-|-|-
Ada|Engineer|Platform
Grace|Architect|Compiler

Column alignment

Alignment is set per column with colons in the delimiter row. The header and every cell in that column follow it.

| Default | Left    | Center  | Right   |
| ------- | :------ | :-----: | ------: |
| text    | text    | text    | 1.5     |
| longer text | longer text | longer text | 1,024.75 |

Right-align numeric columns so digits line up. Markdown has no decimal alignment, so give numbers the same number of decimal places. More detail in the column alignment guide.

What you can and can't put in a cell

A cell holds one line of inline content. Anything that would start a new block (a heading, a list, a code fence, a block quote, a second paragraph) ends the row instead.

Formatting, code and links

| Syntax      | Example                         |
| ----------- | ------------------------------- |
| Bold        | **Important**                   |
| Italic      | *Optional*                      |
| Strike      | ~~Deprecated~~                  |
| Code        | `npm install`                   |
| Link        | [Docs](https://example.com)     |
| Emoji       | ✅ Done                          |

Escaping a pipe character

An unescaped | always starts a new cell, even inside backticks, because GFM splits the row into cells before it looks for code spans. Write \|; the backslash is not shown in the output.

| Operator  | Meaning     |
| --------- | ----------- |
| `a \| b`   | Bitwise OR  |
| `a \|\| b`  | Logical OR  |
| A \| B     | Plain text  |

Line breaks and lists in a cell

| Step    | Details                                  |
| ------- | ---------------------------------------- |
| Install | Run `npm install`<br>then `npm run build` |
| Ship    | <ul><li>Tag the release</li><li>Publish</li></ul> |

Limitations and workarounds

Pipe tables trade features for readable source. Each gap has a standard workaround:

• Merged cells. GFM has no colspan or rowspan. Switch to an HTML table, or use MultiMarkdown (||) or Pandoc grid tables. Merged cells guide.
• Column width. Widths follow the content and there is no width syntax. Pad a header with  , add an <img width="…"> spacer, or use HTML with CSS where it's allowed. Column width guide.
• Captions. GFM has none. Put a bold line or a heading above the table, use an HTML <caption>, or use Pandoc (Table: …) or MultiMarkdown ([…]). Captions guide.
• Headerless tables. GFM always treats the first row as the header. Use blank header cells, or kramdown and Pandoc, which allow tables without one. Headerless tables.
• Nested tables. A Markdown table can't contain another table. Split the data into two tables, link to a detail table, or write the outer table in HTML.
• Long or block content. Use <br> for short multi-line cells, hide big tables in a collapsible section, or transpose a wide table so it reads top to bottom.

Markdown table support by platform

Basic pipe tables are portable. The differences show up in the extras: headerless tables, merged cells and captions.

Markdown tables vs. HTML tables

Most Markdown renderers accept raw HTML, so you can always fall back to a <table>. Stay with Markdown when the data is a plain grid that people edit as text, such as READMEs, docs in Git and changelogs, because pipe tables are easy to read in the source and in diffs. Switch to HTML when you need any of these:

• merged cells (colspan, rowspan)
• row headers (<th scope="row">) or a <caption>
• block content in cells: lists, code blocks or several paragraphs
• fixed column widths or styling, on renderers that keep attributes

<table>
  <caption>Quarterly revenue by region</caption>
  <thead>
    <tr>
      <th scope="col">Region</th>
      <th scope="col">Q1</th>
      <th scope="col">Q2</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th scope="row">Europe</th>
      <td>$1.2M</td>
      <td>$1.4M</td>
    </tr>
    <tr>
      <th scope="row">Americas</th>
      <td colspan="2">Reported annually</td>
    </tr>
  </tbody>
</table>

Inside an HTML table, Markdown such as **bold** is only processed if a blank line separates it from the tags, so it is usually simpler to use HTML (<b>, <code>) there. GitHub strips style attributes, so CSS colors and widths won't survive. To convert in either direction, use Markdown table to HTML or HTML table to Markdown.

Why a Markdown table doesn't render

When the pipes show up as plain text, check these in order:

1. Delimiter row. It must be the second line and have exactly as many cells as the header.
2. Unescaped pipes. A | in a cell, a URL or a code span adds a column; escape it as \|.
3. Blank line before the table. GitHub can start a table right after a paragraph, but kramdown, many site generators and linters (markdownlint MD058) expect a blank line.
4. Indentation. Four or more leading spaces turn the table into a code block.
5. HTML wrappers. Inside <details> or <div>, leave a blank line after the opening tag so the table is parsed as Markdown.
6. Platform support. Discord, Slack messages and core-CommonMark renderers never draw tables.

The table validator flags each of these with the line number, and the troubleshooting guide covers platform-specific cases.

Where the table syntax comes from

John Gruber's original Markdown (2004) has no table syntax; you wrote tables in HTML. Michel Fortin's PHP Markdown Extra popularized the pipe table with a dashed separator line and colon alignment, and MultiMarkdown, Pandoc and kramdown adopted and extended the idea with column spans, captions and other table styles.

GitHub made pipe tables part of GitHub Flavored Markdown. The GFM spec (version 0.29-gfm) defines them precisely as the “Tables (extension)” on top of CommonMark. CommonMark itself, currently version 0.31.2, still has no tables, so CommonMark parsers such as markdown-it, remark (with remark-gfm) and cmark-gfm add them as an extension.

One detail often causes confusion: GitHub Docs say each delimiter cell needs at least three hyphens, but the GFM spec accepts one (|-|-|). Three is a readable convention, not a requirement.

Accessible Markdown tables

A Markdown table becomes a real HTML table, so screen readers can move through it by row and column. A few habits keep it usable:

• Write meaningful header cells. The header row becomes <th> cells that are read out with each value. Blank headers (the headerless workaround) leave cells without context.
• Know that GFM has no row headers. In a comparison table where the first column names each row, only HTML can mark those cells as <th scope="row">.
• Introduce the table. GFM has no caption, so put a heading or a sentence right before the table that says what it contains, or use an HTML <caption> where allowed.
• Avoid empty and symbol-only cells. Write “None” or “N/A” rather than leaving a cell blank, and pair icons with words (“✅ Yes”), because emoji are read out by name.
• Use tables for data, not layout. Don't use a table to put images side by side or to indent text.

Frequently asked questions

All table syntax guides and tools

Each guide covers one part of the syntax in depth, with platform notes and copyable examples.

Tools

Also see the printable Markdown table cheatsheet and the platform guides for GitHub, GitLab, Obsidian, VS Code, Pandoc, Python and React.