How to Create Tables in Markdown (With Alignment)

Tables are one of the most useful features in everyday Markdown, yet they confuse more newcomers than almost anything else. Once you understand markdown table syntax, you can lay out pricing plans, API field lists, comparison matrices, and changelogs without ever leaving your text editor. This guide walks through the full syntax from scratch — including the alignment row, inline formatting inside cells, the gotchas that trip people up, and how tables render in different viewers.

If you want to follow along by typing, paste your draft into the online editor and watch the preview update as you go.

The anatomy of a markdown table

A Markdown table is built from three parts: a header row, a delimiter row, and one or more data rows. Each cell is separated by a pipe (|).

| Name      | Role       | Location |
| --------- | ---------- | -------- |
| Ada       | Engineer   | London   |
| Ben       | Designer   | Lisbon   |
| Cara      | PM         | Berlin   |

That renders as:

Name	Role	Location
Ada	Engineer	London
Ben	Designer	Lisbon
Cara	PM	Berlin

A few rules worth memorising:

• The delimiter row must contain only dashes (-) and pipes. No other characters.
• You don't strictly need leading and trailing pipes (|), but including them makes the raw text far easier to read and edit.
• Cell widths in the source don't affect rendering. Markdown is whitespace-tolerant — line the pipes up for your own sanity, not for the parser.

Markdown table syntax for alignment

The delimiter row is also where you control column alignment. This is the part of markdown table syntax people most often get wrong, because it looks cryptic at first glance. Colons (:) in the delimiter row tell the viewer how to align that column:

Syntax	Meaning
:---	Left-aligned
:---:	Centered
---:	Right-aligned
---	Default (usually left)

Here is a real example that uses all three alignments in one table:

| Product     | Price | In Stock |
| :---------- | ----: | :------: |
| Notebook    | 3.50  |   yes    |
| Pen         | 1.20  |    no    |
| USB cable   | 8.99  |   yes    |

Renders as:

Product	Price	In Stock
Notebook	3.50	yes
Pen	1.20	no
USB cable	8.99	yes

Right-alignment is especially handy for numeric columns like prices, counts, or durations. Centered alignment suits short status fields ("yes/no", badges). Left is the safe default for everything else.

Tip: The number of colons matters more than the number of dashes. :--: works exactly the same as :---------: — Markdown only cares about the position of the colons.

Formatting inside cells

Cells aren't limited to plain text. Most inline Markdown works inside table cells, including bold, italics, inline code, and links.

| Field        | Type     | Notes                                  |
| ------------ | -------- | -------------------------------------- |
| `id`         | string   | **Required.** Unique identifier.       |
| `created_at` | ISO 8601 | See [the spec](https://example.com).   |
| `count`      | integer  | Must be `>= 0`.                        |
| `tags`       | string[] | _Optional._ Defaults to an empty array.|

Field	Type	Notes
id	string	Required. Unique identifier.
created_at	ISO 8601	See the spec.
count	integer	Must be >= 0.
tags	string[]	Optional. Defaults to an empty array.

What does not work inside a cell:

• Block-level elements like headings (##), blockquotes, or nested tables.
• Multi-line content — a table row is a single line. You can't press Enter inside a cell.
• List syntax (- item) renders as literal text, not a bullet list.
• Paragraph breaks — a blank line ends the entire table.

If you genuinely need richer layouts (nested lists, multi-paragraph cells), reach for an HTML <table> instead — but raw HTML is disabled in some strict viewers, so test first.

Escaping pipes inside cells

Because the pipe character is the cell separator, a literal pipe inside your content would split the cell in two. Escape it with a backslash:

| Command          | Effect                       |
| ---------------- | ---------------------------- |
| `ls \| grep txt` | List files, then filter them |
| `a \|\| b`       | Logical OR                   |

Command	Effect
ls | grep txt	List files, then filter them
a || b	Logical OR

Note that inside an inline-code span (`…`) you technically don't need the backslash, but it doesn't hurt and keeps things consistent across parsers.

Common gotchas

These are the four mistakes I see over and over:

1. No blank line above the table. Many renderers won't recognise a table that's glued directly to a preceding paragraph. Always leave a blank line:

   Here is some text.
   
   | A | B |
   | - | - |
   | 1 | 2 |

2. No blank line below the table. The same rule applies after the table — without a blank line, the following paragraph can get swallowed into the last row.

3. Expecting cell spanning. Markdown tables have no colspan or rowspan. Every row has the same number of columns. If you need merged cells, you must use HTML.

4. Mismatched column counts. If a row has fewer or more cells than the header, some viewers quietly pad or drop cells while others render the whole table as plain text. Keep your counts consistent.

Gotcha checklist: blank line above, blank line below, equal column counts, escape any literal pipes. Tick those four boxes and your tables will render almost everywhere.

How tables render across viewers

Markdown table support is part of GitHub-Flavored Markdown (GFM), which builds on CommonMark. Pure CommonMark renders tables as literal pipe text — you need a GFM-aware viewer. Here's how common destinations behave:

Viewer / target	Tables supported?	Notes
GitHub	Yes	GFM is the reference implementation.
GitLab	Yes	GFM-compatible.
VS Code preview	Yes	Uses a GFM-aware renderer.
CommonMark strict	No	Renders the pipes as plain text.
Static site gens	Usually	Depends on the renderer; most enable it.
Email clients	Inconsistent	Tables get converted to HTML <table>.

Because rendering varies, it's smart to preview before you publish. Paste your Markdown into the MD viewer to see exactly how a GFM-aware renderer will display your table, or open the Markdown cheat sheet for a quick syntax refresher covering tables alongside every other feature.

If your goal is to ship the table as a polished document, you can also convert the same source: render to a web page with Markdown to HTML, produce a printable handout with Markdown to PDF, or hand off an editable deliverable using Markdown to Word.

A worked multi-column example

Putting it all together, here's a realistic comparison table with alignment, inline formatting, and an escaped pipe — the kind you might drop straight into a README:

| Tool         | License | Stars | Notes                                    |
| :----------- | :-----: | ----: | :--------------------------------------- |
| `rolldown`   | MIT     |  9.1k | **Fast** bundler; see [docs](#).         |
| `esbuild`    | MIT     | 38.2k | Go-based; near-instant builds.           |
| `vite`       | MIT     | 67.5k | Uses esbuild `\|\` rolldown under the hood|

Renders as:

Tool	License	Stars	Notes
rolldown	MIT	9.1k	Fast bundler; see docs.
esbuild	MIT	38.2k	Go-based; near-instant builds.
vite	MIT	67.5k	Uses esbuild |\ rolldown under the hood

Notice the three alignments in action: left for Tool and Notes, centered for License, right for Stars. The escaped pipe in the last row keeps the cell intact.

Key takeaways

• A Markdown table is a header row, a delimiter row of dashes, and data rows — all pipe-separated.
• Put colons in the delimiter row to control alignment: :--- left, :---: center, ---: right.
• Inline formatting (bold, italics, code, links) works inside cells; block elements and multi-line content do not.
• Always leave a blank line above and below the table, keep column counts consistent, and escape literal pipes with \|.
• Tables are a GFM feature — preview in a GFM-aware viewer before publishing, since pure CommonMark won't render them.

Ready to build your own? Open the Markdown editor and start typing — the live preview shows your table the moment you finish the delimiter row.