How to Write Markdown Tables (Without Losing Your Mind)

Markdown tables look simple until your columns drift, a stray pipe splits a row in two, and you find yourself counting dashes by hand. The good news is that the syntax is small and predictable, and once you see the pattern you can write a clean table in seconds. Here's how the syntax works, how to control alignment, and how to fix the handful of things that usually go wrong.

Quick answer

A Markdown table is three parts: a header row, a delimiter row made of hyphens, and one or more data rows. Every cell is separated by a pipe (|). The delimiter row sits directly under the header and is where alignment lives — a colon on the left, right, or both sides of the hyphens sets left, right, or center alignment.

| Language | Released | Typed   |
| -------- | -------- | :-----: |
| Swift    | 2014     | Yes     |
| Python   | 1991     | Optional|

Tables aren't part of John Gruber's original Markdown or the CommonMark core. They come from the GitHub Flavored Markdown tables extension, so they render anywhere GFM is supported. If you want the broader syntax around them, our Markdown syntax cheat sheet covers headings, lists, links, and code.

Step-by-step

1. Write the header row

List your column titles on one line, separated by pipes. Leading and trailing pipes are optional, but adding them makes the table easier to read in plain text:

| Method | Returns | Notes |

2. Add the delimiter row

The line directly beneath the header turns those titles into a table. Each column needs a cell of hyphens. The spec accepts a single hyphen per column, but three is the common convention and keeps the source legible:

| ------ | ------- | ----- |

This row is required. Without it, the renderer treats your text as ordinary paragraphs.

3. Set alignment with colons

Alignment is controlled entirely in the delimiter row by adding colons:

| :--- | :---: | ---: |
| left | center | right |

A colon on the left means left-aligned, colons on both sides mean centered, and a colon on the right means right-aligned. Plain hyphens with no colon default to left. Right alignment is handy for numbers, so the digits line up by place value.

4. Fill in the data rows

Add one row per line, matching the column order. You don't need the same number of cells in every row: if a row has fewer cells than the header, the missing ones render empty; if it has more, the extras are dropped. Matching the count anyway keeps the table predictable.

5. Stop fighting the spacing

Markdown doesn't care whether your columns line up in the raw file. Whitespace inside a cell is trimmed, so |Swift| and | Swift | render identically. Pad cells with spaces only if it helps you read the source — the rendered output is the same either way.

Common problems and fixes

The table won't render

Two causes account for nearly every broken table: a missing or malformed delimiter row, or no blank line separating the table from the text around it. Make sure the hyphen line sits immediately under the header, and leave an empty line before and after the table.

A pipe inside a cell breaks the columns

Because the pipe is the column separator, a literal pipe in your content splits the cell. Escape it with a backslash:

| Operator | Meaning |
| -------- | ------- |
| \|       | bitwise OR |

The columns look crooked in the source

The renderer ignores source alignment, but crooked columns are hard to edit by hand. You can pad cells with spaces to line them up, or use an editor that reflows the table for you so the pipes stay aligned as you type.

A cell needs more than one line

Markdown table cells are single-line by design — you can't press Enter inside one. If a cell wants a paragraph, a list, or an image, a table is the wrong tool. Keep cells short, and move anything longer into the prose beneath the table. Being honest about this trade-off saves you from wrestling layout that Markdown was never meant to do.

Doing this with Carets

Tables are a good test of an editor: you write them in plain text, but you only trust them once you see them rendered. Carets is a fast, native notes and code editor for iPhone, iPad, and Mac that handles both sides of that loop — Markdown, plain text, and code with syntax highlighting, organized into files, projects, and tags.

Because Carets keeps Markdown and plain text in one editor, you write the pipes and hyphens by hand and check the rendered table without leaving the app or exporting anything. Its syntax highlighting makes the delimiter row and escaped pipes easy to track at a glance, so a missing colon or a stray | is obvious before it breaks the layout. And since your work lives in files, projects, and tags, the reference tables you reach for again and again stay organized instead of scattered across screenshots and chat threads. Your files stay plain text, so they're portable and remain readable years from now. If you're weighing how portable your tables really are, our guide to CommonMark vs GitHub Flavored Markdown explains where they will and won't render.

Carets is built natively for iOS and Mac rather than wrapped from the web, so it stays fast on every device. Download Carets on the App Store for iPhone, iPad, and Mac.

Frequently asked questions

Do Markdown tables work everywhere?

No. Tables are a GFM extension, not part of CommonMark's core or the original Markdown specification. They render on GitHub and in most modern Markdown tools, but a strict CommonMark-only renderer will show the raw pipes and hyphens instead of a table.

How do I align a column?

Add colons to that column's cell in the delimiter row: :--- for left, :---: for center, and ---: for right. Columns with plain hyphens default to left alignment.

Can I put a pipe character inside a cell?

Yes. Escape it with a backslash so the renderer treats it as content rather than a column separator: write \| wherever you need a literal pipe.

What's the minimum a table needs to render?

A header row, a delimiter row of hyphens directly beneath it, and a blank line separating the table from the surrounding text. Miss the delimiter row and the renderer treats everything as plain paragraphs.

Can a table cell span multiple lines?

Not in standard Markdown — cells are single-line. Keep cell content short and put anything longer, such as a paragraph or a list, in the text around the table.