Markdown Table Alignment

The separator row controls alignment

The row directly below a Markdown table header does two jobs: it proves that the block is a table, and its colons declare how each column should align. Source-code spaces do not control rendered alignment.

| Name       | Status | Monthly cost |
| :--------- | :----: | -----------: |
| Starter    | Active |            0 |
| Team       | Active |           12 |

In this example, names align left, status values center, and costs align right.

Left alignment

Put a colon at the start of the separator cell. Many GFM renderers also treat a separator with no colon as left-aligned.

| Description |
| :---------- |
| Browser-local conversion |

Left alignment is the best default for prose, names, paths, commands, option labels, and other content read in normal text order.

Center alignment

Put a colon on both sides of the dashes. Center alignment works best for compact values with similar visual width.

| Supported |
| :-------: |
| Yes       |
| No        |

Good candidates include short status words, check marks, platform labels, and small categorical values. Centering full sentences makes tables harder to scan.

Right alignment

Put a colon at the end of the separator cell. Right alignment helps users compare values by their final digit or decimal position.

| Requests | Error rate |
| -------: | ---------: |
| 1,280    |       0.4% |
| 9,450    |       0.2% |

Use it for counts, prices, percentages, durations, file sizes, and version-like numeric values. Keep the unit consistent within one column.

Minimum syntax and readable source

GFM requires a separator cell to contain dashes, with optional leading or trailing colons. Use at least three dashes for broad compatibility. You may add spaces to make the source columns line up, but those spaces do not change the rendered alignment.

| A | B | C |
|:--|:-:|--:|
| x | y | z |

The compact form may render, but the padded form is easier to review and edit. A formatter can normalize the source without changing alignment.

Common alignment mistakes

• Putting colons in data rows: only the separator row declares alignment.
• Using one separator for a different number of columns: each header column needs a corresponding separator cell.
• Expecting tabs or spaces to align rendered cells: those only affect source readability.
• Centering long prose: use left alignment for multiword descriptions.
• Testing only in the editor: confirm behavior in the repository, documentation engine, or publishing platform you use.

Choose alignment by meaning

Compatibility note

Pipe tables and alignment markers are GFM features, not part of base CommonMark. GitHub, GitLab, many editor previews, and most GFM-enabled documentation tools support them. Strict CommonMark renderers may display the source as plain text.