MarkdownViewer

Markdown Table Syntax: How to Write Tables in Markdown

Markdown tables let you present structured data — comparisons, feature matrices, reference tables — in a format that renders cleanly on GitHub, GitLab, wikis and most static site generators. The syntax is simple, but two small details trip people up constantly: the separator row and consistent cell counts. This guide covers both, plus alignment and the common errors that break rendering.

The three parts of a Markdown table

A Markdown table is a header row, a separator row, and body rows. Each row is written on one line with cells separated by pipe characters. The separator row — the dashes — tells the renderer that the lines above and below it form a table. Without it, the pipes are shown as literal text and nothing renders.

  1. | Name | Role |
  2. | --- | --- |
  3. | Ada | Engineer |
  4. | Grace | Admiral |

Why the separator row matters

The dashes are not decoration — they are the signal that switches the renderer into table mode. They must appear on the line immediately below the header, with the same number of cells, and they need at least three dashes per column (one dash is technically accepted by some renderers, but three is the safe, portable choice).

Aligning columns

You can align a column by placing a colon in its separator cell: a left colon aligns left, a right colon aligns right, and colons on both sides centre the column. Alignment is a hint — some renderers ignore it — but the major ones honour it. Without colons, columns default to left alignment.

  1. | Left | Centre | Right |
  2. | :--- | :---: | ---: |
  3. | a | b | c |

Formatting inside cells

Cells can contain inline Markdown: bold, italic and inline code all work. What you cannot easily do is put a block element — a list, a heading or a multi-line paragraph — inside a table cell. If a cell needs that much content, the data probably belongs in a list or a separate section rather than a table.

Common mistakes that break tables

  1. Missing the separator row, so the pipes render as text
  2. A body row with fewer cells than the header, which stops the table drawing
  3. A raw pipe character inside a cell, which splits the cell in two
  4. Blank lines between body rows, which can split one table into several
  5. Leading or trailing spaces that misalign the source, though renderers ignore them

Generate instead of hand-writing

For anything beyond a two-column table, hand-writing pipes is slow and error-prone. Paste your data from a spreadsheet or CSV into the table generator and it emits a correctly formed table — header, separator and padded rows — that you can paste straight into your document. This sidesteps every mistake listed above.

Frequently Asked Questions

Do the pipes need to line up in the source?
No. Renderers ignore whitespace, so the columns do not need to align in your text file. Aligning them is a readability choice for the source, not a requirement for the output.
How many dashes go in the separator row?
At least three per column is the safe choice. Some renderers accept fewer, but three dashes is portable across GitHub, GitLab and most static site generators.
How do I put a pipe character inside a cell?
Escape it with a backslash: write \| instead of |. The renderer then shows a literal pipe without ending the cell.
Can a Markdown table have a different number of columns per row?
Not reliably. Most renderers require every row to have the same number of cells as the header, and a mismatched row often stops the whole table from rendering. Pad short rows with empty cells to keep the count consistent.

Related Markdown Tools

Markdown ViewerMarkdown Table GeneratorMarkdown Cheat SheetAll Markdown Tools