Markdown Table Syntax

How to create, format, and align tables in Markdown

Basic Table Syntax

A Markdown table uses pipes (|) and hyphens (-) to define columns and rows:

| Name    | Role       | Location  |
|---------|------------|-----------|
| Alice   | Engineer   | Berlin    |
| Bob     | Designer   | Tokyo     |
| Charlie | PM         | New York  |

Renders as:

Name Role Location
Alice Engineer Berlin
Bob Designer Tokyo
Charlie PM New York

Rules:

  • The first row is always the header
  • The second row (with hyphens) separates the header from data
  • Each column is separated by a pipe |
  • Leading and trailing pipes are optional but recommended for readability
  • Columns don’t need to be perfectly aligned in the source — the renderer handles spacing

Column Alignment

Control text alignment in each column using colons (:) in the separator row:

| Left-aligned | Center-aligned | Right-aligned |
|:-------------|:--------------:|--------------:|
| Text         | Text           | Text          |
| More text    | More text      | 1,234.56      |
  • :--- or --- — left-aligned (default)
  • :---: — center-aligned
  • ---: — right-aligned

Right alignment is useful for numeric columns — prices, counts, percentages. Center alignment works well for status indicators or short labels.

Formatting Inside Tables

You can use inline Markdown formatting inside table cells:

| Feature    | Status          | Notes                     |
|------------|-----------------|---------------------------|
| Dark mode  | **Done**        | Shipped in v1.3           |
| Export PDF | ~~Cancelled~~   | Use `Cmd+Shift+E` instead |
| Search     | *In progress*   | [Tracking issue](#)       |

Supported formatting:

  • Bold — **text**
  • Italic — *text*
  • Code — `text`
  • Strikethrough — ~~text~~
  • Links — [text](url)
  • Images — ![alt](url) (though images in tables can be tricky to size)

Not supported in standard Markdown tables:

  • Headings (#)
  • Block quotes (>)
  • Lists (- or 1.)
  • Multi-line content (each cell must be on one line)
  • Cell merging (rowspan/colspan)

Escaping Pipes in Tables

If your cell content contains a pipe character, escape it with a backslash:

| Command         | Description           |
|-----------------|-----------------------|
| `a \| b`        | Logical OR            |
| `grep "error"`  | Search for errors     |

Without the backslash, the pipe would be interpreted as a column separator.

Minimal Tables

You can write very compact tables if readability isn’t a priority:

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

This is valid Markdown and renders the same way. However, aligned tables are much easier to read and maintain in source files.

GitHub Flavored Markdown Tables

GitHub, GitLab, and most modern Markdown renderers use the GFM (GitHub Flavored Markdown) table spec. This is the syntax described on this page.

Some platforms extend GFM with extras:

  • GitHub — supports standard GFM tables, no extensions
  • GitLab — same as GitHub
  • Obsidian — supports multi-line cells with <br> tags
  • Notion — uses its own table format, not standard Markdown

If you’re writing for GitHub (README.md, issues, PRs), the standard syntax on this page is all you need.

Common Mistakes

Missing separator row:

| Name  | Role     |
| Alice | Engineer |

Without the |---|---| row, this won’t render as a table — it will appear as plain text with pipes.

Inconsistent column count:

| Name  | Role     | Location |
|-------|----------|
| Alice | Engineer | Berlin   |

The separator row has 2 columns but the header has 3. Most renderers will still try, but the result may look broken.

Trailing spaces before pipes:
Some editors add trailing spaces that can break rendering in strict parsers. If your table looks wrong, check for extra whitespace.

Tools for Creating Markdown Tables

If you’re working with large tables, typing pipes by hand gets tedious. These tools help:

  • TableConvert.io — paste CSV, Excel, or HTML and get Markdown table output
  • VS Code — the Markdown All in One extension adds table formatting shortcuts
  • Pandoc — convert CSV to Markdown: pandoc input.csv -t markdown -o output.md
  • MDViewer — preview your table rendering in real time as you type

Viewing Markdown Tables

Raw Markdown tables in a text editor can be hard to read, especially with many columns. A dedicated Markdown viewer renders them as properly formatted HTML tables with borders, alignment, and styling.

MDViewer is a native macOS app that renders GitHub Flavored Markdown — including tables with alignment, inline formatting, and syntax highlighting. Open any .md file from Finder and see the table rendered instantly. Currently free for early adopters — a Pro tier is planned, but early users get the full app at no cost.

FAQ

How many columns can a Markdown table have?
There’s no official limit. Practically, more than 6–8 columns becomes hard to read in source and in rendered output. For very wide data, consider using a CSV file or a dedicated table tool instead.

Can I merge cells in a Markdown table?
Standard Markdown doesn’t support rowspan or colspan. If you need merged cells, use inline HTML: <td rowspan="2">. However, many Markdown renderers (including GitHub) will strip HTML tables in certain contexts.

How do I make a Markdown table from a spreadsheet?
Copy the cells from Excel or Google Sheets, paste into TableConvert.io, and select Markdown output. Alternatively, export as CSV and convert with Pandoc.

Can I sort a Markdown table?
Not in the Markdown source itself — tables are static. Some Markdown viewers render tables with sortable headers, but this is not standard behavior.

Try MDViewer

MDViewer is currently free for early adopters — all features included. Download it and see if it fits your workflow.

Download MDViewer

Requires macOS 13.0 or later. Intel and Apple Silicon.