Pipes draw the columns, dashes draw the header rule
GFM tables are three pieces: a header row, a separator row of dashes, and any number of body rows. Pipes (|) divide columns. Outer pipes are optional; the parser is permissive about whitespace.
Alignment lives in the separator row
:---— left align (default):---:— center---:— right align (use this for numeric columns)
What cells can hold
Cells accept inline Markdown: bold, italic, code, links, even inline HTML. Cells cannot hold block content — no headings, lists, fenced code blocks, or paragraphs. If you need that, build the table in HTML instead.
Pipes inside cells
Escape with \|. Or wrap the offending text in <code>|</code> if it's literal pipe code. The renderer respects both.
The 'pretty source' trap: editors and tools auto-align table source by padding cells with spaces. The padding is harmless to the renderer but a nightmare for diffs — every cell-width change rewrites every row. Pick a side: align by hand for stable diffs, or accept that table edits will produce noisy commits.