Markdown Table Delimiter Mechanics Markdown Table Template
The delimiter row is the second line of every Markdown table, and it does two jobs at once: it tells the parser “the line above is a header, this is a table”, and it sets the horizontal alignment of each column through the position of its colons. This reference table puts the four possible delimiter forms side by side so a writer, reviewer, or linter author can see the syntax, the rendered result, and the kind of content each form suits.
Edit This Template
Edit cells, add rows, or sort — the Markdown updates livePaste cells from Excel or Google Sheets into the first header to replace the table · Tab / Enter / arrows move · Shift+F10 opens row & column actions
When to Use This Table
It is mostly read by people writing style guides, contribution docs, and lint rules — and by anyone who has just watched a table collapse into a paragraph of pipes and wants to know why. The rules are short but strict. GFM recognises a table only when the delimiter row has exactly as many cells as the header row, and each delimiter cell may contain nothing but hyphens with an optional colon at either end. One hyphen is enough; --- is a readability habit, not a requirement.
A useful version of this table goes past “colon on the left means left”. It states what happens when no colon is given, why numbers belong in right-aligned columns, and what the renderer actually emits, because the difference between an align attribute and an inline style matters once your Markdown passes through a sanitiser. A weak version just lists the three colon patterns and leaves the reader guessing about edge cases.
What Goes in Each Column
| Column | Alignment | What to put here |
|---|---|---|
| Alignment Target | left :--- | The intent in plain words — left, center, right, or unspecified. Left-aligned because these are labels that readers scan down the edge, and a ragged left margin would slow that scan. |
| GFM Delimiter Syntax | center :---: | The exact delimiter cell in a code span, such as :---:. Always wrap it in backticks so the colons and hyphens show literally instead of being read as text formatting. Centered here because the values are short, fixed-width tokens. |
| Rendered Visual Alignment | center :---: | What the reader sees after rendering. For the unspecified case, say precisely that no alignment is emitted and the stylesheet decides; many browsers center <th> cells by default while body cells start at the left. |
| Best Practice Content Type | left :--- | Which kinds of data the form suits: prose and identifiers left, short status tokens center, quantities right. Give concrete examples (“prices, byte counts”) rather than abstract categories so authors can match their own column quickly. |
How to Fill It In
- 1Start from the spec, not memory. The GFM specification’s tables section lists the delimiter rules and includes worked examples of rows that are and are not recognised; copy the edge cases you care about into test files.
- 2Render each row of your reference in the place your readers will use it — a GitHub README preview, your docs site, an IDE preview — and note any renderer that disagrees, especially for the unspecified
---header cells. - 3Inspect the rendered HTML once. cmark-gfm (GitHub) emits
align="right"on the cells, while markdown-it emitsstyle="text-align:right"; if your pipeline stripsstyleattributes, the second kind of alignment silently disappears. - 4Write the content-type guidance from your own tables: open two or three real tables in the project, check which columns hold numbers, statuses, and prose, and phrase the advice in those terms.
- 5Run the final table through the Markdown table validator to confirm the cell counts match and every delimiter cell is well formed.
Ready-to-Paste Variations
Valid and invalid delimiter cells
A lint-oriented version that shows which delimiter cells a GFM parser accepts. Useful in contributor docs when people report a table that will not render.
| Delimiter cell | Valid in GFM | Effect |
| :--- | :---: | :--- |
| `-` | Yes | Unspecified alignment; one hyphen is enough |
| `:-:` | Yes | Centered column |
| `---:` | Yes | Right-aligned column |
| `:` | No | No hyphen, so the row is not a delimiter row |
| `: ---` | No | Space between colon and hyphens breaks the cell |
| `===` | No | Equals signs are not delimiter characters |Delimiter rows for common table shapes
Copy the second column straight into a new table. Pipes inside the code spans are escaped as \| so they display instead of splitting cells.
| Table shape | Delimiter row to paste |
| :--- | :--- |
| Name, price | `\| :--- \| ---: \|` |
| Feature, status, notes | `\| :--- \| :---: \| :--- \|` |
| Metric, before, after, change | `\| :--- \| ---: \| ---: \| ---: \|` |All three alignments in one rendered table
A live demonstration: text on the left, a status token in the middle, and decimals padded to the same precision on the right so the points line up.
| Item | Status | Unit Price |
| :--- | :---: | ---: |
| USB-C cable | In stock | 9.50 |
| Mechanical keyboard | Backorder | 129.00 |
| Monitor arm | In stock | 64.25 |Common Mistakes
Putting a space between the colon and the hyphens, as in
: ---.The colon must touch the hyphens:
:---. Whitespace is allowed only around the whole cell content, between it and the pipes.Giving the delimiter row fewer cells than the header row.
GFM refuses to treat the block as a table at all when the counts differ. Count the pipes in both rows, or let a formatter regenerate the delimiter row from the header.
Expecting decimals to line up just because a column is right-aligned.
Right alignment lines up the last character, not the decimal point. Pad every value to the same number of decimal places (
9.50, not9.5) and the points will line up as a side effect.Trying to center one cell by adding colons on a body row.
Alignment is per column and lives only in the delimiter row. For a one-off cell you need an HTML table, which most hosts allow but which no longer counts as Markdown table syntax.
Showing an example delimiter row in prose without a code block.
A bare line of
---directly under a paragraph turns that paragraph into a heading (a setext underline), and on its own it becomes a horizontal rule. Put example rows in a fenced code block or a code span.
Related Markdown Table Templates
Browse all 50 templatesRegular Expression (RegEx) Syntax Reference
Comprehensive cheat sheet for regular expression metacharacters, character classes, quantifiers, anchors, and lookaround assertions.
Status Indicators & Markdown Badges
Cheat sheet of copy-pasteable Unicode symbols, emojis, and shields.io badge syntax for table cells.
Mobile Device Screen Viewports & Density
Common mobile device viewport widths, CSS logical pixels, physical resolutions, aspect ratios, and device pixel ratios (DPR).
Markdown Table Delimiter Mechanics: Frequently Asked Questions
How many hyphens does a delimiter cell need?
One. GFM accepts -, :-, -: and :-:. Three or more is a convention that makes the raw source easier to read, and formatters usually pad the hyphens to the column width so the source lines up visually.
What alignment does a plain --- produce?
None. The parser emits no alignment information, so the page stylesheet decides. Body cells normally sit at the left (or right in right-to-left scripts), while header cells may be centered by the browser default unless the site CSS overrides it.
Do the number of hyphens change column width?
Not on GitHub or most web renderers, where widths come from content and CSS. Pandoc is the notable exception: in pipe tables with long lines, the relative number of hyphens sets the relative column widths in the output document.
Can I skip the leading and trailing pipes?
GFM allows it, but keep them. Outer pipes make rows unambiguous for other parsers, make empty edge cells possible, and are expected by most formatters and diff tools. See the alignment syntax page for full examples.