The anatomy of a GFM table
Every GitHub Flavored Markdown table has exactly three parts, and the middle one is the one people forget:
| Name | Role |
| ----- | -------- | ← required separator row
| Alice | Engineer |Omit that separator row and the whole block renders as plain text — it’s the single most common reason a table “doesn’t work.” The separator also controls alignment, which is where colons come in.
Alignment lives in the separator
You set per-column alignment by placing colons in the separator row, not in the data:
| Separator | Alignment |
|---|---|
:--- | Left |
:---: | Center |
---: | Right |
--- | Default (usually left) |
This generator exposes alignment buttons per column and rewrites the separator for you, so you never hand-edit colons.
Source alignment is cosmetic
A frequent confusion: the neatly padded pipes you see in well-formatted Markdown source (| Alice | Engineer |) have zero effect on the rendered output. Renderers trim cell whitespace, so a ragged, unaligned source table renders identically to a perfectly padded one. The padding is purely for human readability while editing — which is why the generator pads cells, but you shouldn’t stress about matching it by hand. (One caveat: source padding only looks aligned in a monospace font; in a proportional font the pipes won’t line up even though the Markdown is valid.)
Where Markdown tables stop
Markdown tables deliberately support only flat, rectangular data. They cannot do merged cells (colspan/rowspan), nested tables, or rich multiline content. When you hit those needs, you have two honest options: drop to raw HTML <table> (works inside Markdown on most platforms) for full control, or restructure the data so it fits a simple grid. Forcing complex data into Markdown table syntax produces something that’s painful to edit and breaks across renderers — reach for HTML the moment a cell needs to do more than hold one line of text. Need to draft the surrounding prose too? The Markdown Preview tool shows the whole document rendered live.