The syntax
| Name | Role |
| :--- | :-------- |
| Ada | Engineer |
| Grace | Admiral |
Renders as:
| Name | Role |
|---|---|
| Ada | Engineer |
| Grace | Admiral |
Pipes (|) separate columns; the second row (dashes) is required and defines column boundaries and alignment — this row isn't optional decoration, it's what tells the parser "this is actually a table," distinguishing it from a paragraph that happens to contain pipe characters.
Alignment via colon placement
The position of colons in the separator row controls per-column text alignment:
| Left | Center | Right |
| :--- | :---: | ---: |
:---— left-aligned (also the default with no colons at all):---:— center-aligned---:— right-aligned
Alignment is purely a rendering hint — it has no effect on the underlying data, only how it's displayed.
Why tables aren't part of "plain" Markdown
Tables were never part of John Gruber's original Markdown specification, nor are they part of core CommonMark — they're a GitHub Flavored Markdown (GFM) extension, later adopted broadly by other tools and static site generators. This is exactly why table syntax that renders perfectly on GitHub can fail to render as an actual table (falling back to a literal pipe-delimited paragraph) on a Markdown processor that only implements bare CommonMark without the GFM table extension enabled.
Practical formatting tips
- Column widths in the source don't need to match visually.
| Name | Role |and| Name | Role |render identically — the raw markdown doesn't need to be manually aligned for the output to look correct, though many people align it for source readability anyway. - Escaping a literal pipe inside a cell requires
\|, since an unescaped pipe would otherwise be read as a new column separator. - Very wide tables can be genuinely hard to read in raw Markdown source, even though they render fine — some people prefer a different data format (or breaking a very wide table into multiple simpler ones) purely for source maintainability.
Common mistakes
- Forgetting the separator row entirely. Without it, pipe-separated text renders as a plain paragraph, not a table — this row is mandatory, not optional styling.
- Assuming table syntax works in every Markdown renderer. It's a GFM extension, not core CommonMark — verify your specific target renderer supports it before relying on it.
- Not escaping a literal pipe character needed inside cell content. An unescaped
|inside a cell splits it into an unintended extra column.
FAQ
Is the dashed separator row in a Markdown table required?
Yes — it's what tells the parser this is actually a table, not just paragraph text containing pipe characters; omitting it prevents the table from rendering at all.
Do Markdown tables support cell alignment?
Yes — colon placement in the separator row (left, center, or right) controls per-column alignment, purely as a display hint with no effect on the underlying data.
Will Markdown table syntax always render as an actual table?
Only if the renderer supports the GitHub Flavored Markdown table extension — plain CommonMark parsers without it will show the raw pipe-delimited text as a paragraph instead.
Learn more about Markdown's core syntax and extensions in the Complete Guide to Markdown.