Markdown Tables: How to Create and Format Them

The basic syntax

A Markdown table starts with a header row, then a separator row of dashes, then data rows. Columns are separated by pipes.

The separator row is what turns three lines into a table. Each column needs at least one hyphen there, and nothing else except optional colons. Without it, the lines render as plain paragraphs — the most common reason a table "doesn't work".

Tables are a GitHub Flavored Markdown (GFM) extension, so the renderer must support them; most modern ones do. You do not have to align the pipes in the source, either — Markdown ignores the padding, so `|Tool|Type|` and `| Tool | Type |` render identically.

| Tool | Type |
| --- | --- |
| SHA-256 | Hashing |
| AES-GCM | Encryption |

Controlling alignment

Add colons in the separator row to align columns: :--- left, :---: center, ---: right.

The colon is what matters; the hyphens around it are filler. Left alignment is the default, so `---` and `:---` look the same in most renderers.

Alignment is a rendering hint, not data. Right-aligned numbers line up at the decimal point, which helps when you compare values. Not every renderer honors it, though — some minimal ones ignore the colons and left-align everything, so check the target first.

| Left | Center | Right |
| :--- | :---: | ---: |
| 1 | 2 | 3 |
| 10 | 20 | 30 |

Escaping pipes and special content

To include a literal pipe inside a cell, escape it with a backslash: \|. Code spans and links work normally inside cells.

The backslash escape is processed before the cell is split, so \| also works inside inline code and bold text. A shell pipeline like `ps \| grep node` stays in one cell.

Links, emphasis, and inline code are all parsed inside cells. What you cannot do is nest block content — no lists, headings, or fenced code blocks in a single cell; move that outside the table.

• Escape pipes: \| inside a cell
• Use backticks for inline code: `npx tsx`
• Links work in cells: docs
• Keep cells short; long text belongs in a list or section
• A backslash-escaped pipe works inside backticks and bold text

Tables vs lists

A table earns its place when every row answers the same question with a different value: parameter lists, algorithm comparisons, changelogs with fixed columns. If the rows start reading like sentences, a list is probably the better shape.

Think about the reader on a phone. A four-column table with a long URL column becomes horizontal scrolling, and many people will not scroll — split the table or shrink the wide content to link text.

My rule of thumb: when I document a CLI tool, I keep tables to three columns and push long examples into a fenced block below.

• Use tables for comparisons, parameters, and structured data
• Use lists for sequences, options, and prose-heavy content
• Limit tables to 3-5 columns on mobile to avoid horizontal scrolling
• If a table needs nested content, split it into smaller tables or prose
• Use a list when the order matters and each item stands on its own
• Keep header cells short so screen readers announce them cleanly

Preview and refine locally

The Markdown Preview renders locally in your browser, so it is a low-friction place to experiment with colons and escaping. Keep the source on one side of the screen and the preview on the other.

1. Write your table in Markdown.
2. Open the Markdown Preview in your browser.
3. Paste the source and check the rendered alignment.
4. Adjust colons and escaping until the table reads cleanly, then export or copy.
5. Check the raw source once more: a stray pipe or a missing separator row is the usual culprit.
6. Test the same source where the docs will live — GitHub, GitLab, or your CMS — because renderers differ.

FAQ

References

• GitHub Flavored Markdown Spec – Tables: https://github.github.com/gfm/#tables-extension-
• CommonMark Specification: https://spec.commonmark.org/
• RFC 7763 – The text/markdown Media Type: https://www.rfc-editor.org/info/rfc7763/
• RFC 7764 – Guidance on Markdown: https://www.rfc-editor.org/info/rfc7764/
• Original Markdown syntax (John Gruber): https://daringfireball.net/projects/markdown/syntax
• MDN – How to write in Markdown: https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines/Howto/Markdown_in_MDN