How-to guide

How to Make a Markdown Table

A Markdown table is rows of cells separated by pipes, with a second line of dashes that separates the header and sets alignment. Colons in that line control alignment: left, right or centred. Pipes inside a cell must be escaped as \|, and a table cannot contain block content such as lists or paragraphs.

CSV to Markdown Table

Turn a spreadsheet export into a Markdown table.

Open the tool

Markdown tables are not part of the original specification. They come from GitHub Flavored Markdown and are now supported nearly everywhere, which means they work in most places but the edge cases vary between renderers.

Writing one by hand is fine for three rows and tedious beyond that. Generating from CSV is quicker for anything real, and it also handles the escaping you would otherwise have to remember.

Step by step

Write the header row
Separate each column with a pipe. Leading and trailing pipes are optional in most renderers but including them is clearer and safer.
Add the separator line
A row of dashes, one cell per column. This line is required — without it the renderer treats everything as ordinary paragraph text, which is the most common reason a table does not appear.
Set the alignment with colons
A colon on the left aligns left, on the right aligns right, and on both sides centres. Alignment is the only formatting control the table syntax offers.
Escape pipes inside cells
A literal pipe ends the cell, so write it as \|. This catches people out with code samples and anything containing a shell pipeline.
Handle content that will not fit
Cells cannot hold lists, paragraphs or headings. A line break inside a cell has to be written as <br>, which is the one piece of HTML a table row accepts. If you need more than that, use a list instead of a table.
Generate it from CSV for anything larger
Paste the data into a CSV to Markdown converter, which pads the columns so the source stays readable in a diff and escapes the pipes for you.

Example

Padding is cosmetic — renderers ignore it — but it keeps the source readable.

Markdown

| Tool    | Runs     | Free |
| :------ | :------- | ---: |
| Format  | Browser  |  Yes |
| DNS     | Server   |  Yes |

Renders as

Tool     Runs      Free
Format   Browser    Yes
DNS      Server     Yes

Column 3 is right-aligned;
columns 1 and 2 left.

Frequently asked questions

Why is my table not rendering?

Almost always a missing or malformed separator line. It must sit directly under the header, contain only dashes, colons and pipes, and have the same number of cells as the header. Without it the renderer sees plain paragraphs.

Do the columns need to line up?

No. Renderers ignore the padding entirely, so a ragged table renders identically to a padded one. Padding is purely for whoever reads the source, which matters in a diff.

How do I put a line break in a cell?

Use <br>. Markdown tables have no syntax for it, and a real newline ends the row. Most renderers accept that one piece of inline HTML inside a cell.

Can a cell contain a list or a code block?

No. Table cells hold inline content only — text, emphasis, links, inline code. If the content needs block structure, the data probably wants a list or a set of headings rather than a table.

Are Markdown tables standard?

They are not in the original Markdown or in CommonMark. They come from GitHub Flavored Markdown and are supported very widely now, but details such as escaping and inline HTML differ between renderers, so test where it will be published.

Tools used in this guide

All tools →

All guides →

Last reviewed 7 August 2026.