Markdown Table Generator

From grid to Markdown: a worked example

Say you need a small pricing table with four columns and four data rows. The header cells are Plan, Seats, Price and Support. Two columns stay left aligned because they hold names, Seats is centered because the values are short, and Price is set right so the numbers line up on their last digit.

Fill in the four data rows and the generator produces exactly this:

| Plan       | Seats | Price | Support   |
| :--------- | :---: | ----: | :-------- |
| Starter    |   3   |    $0 | Community |
| Team       |  25   |   $49 | Email     |
| Business   |  100  |  $149 | Priority  |
| Enterprise | 500+  |  $299 | Dedicated |

Three details in that block are worth a closer look.

Three details in the output

• The second line is the delimiter row, and it is not decoration. Without it the block is not a table at all, only six lines of text with pipe characters in them.
• The colons carry the alignment. :--- means left, :---: means center, and ---: means right.
• The padding spaces are cosmetic. Renderers strip them, which is exactly why editing a wide table by hand is such a chore.

The same table in five steps

1. Set the grid to four columns and four data rows.
2. Type the four header cells along the top row.
3. Click center above Seats and right above Price.
4. Fill in the data rows, one plan per row.
5. Copy the Markdown pane and paste it where the table belongs.

Paste that block into the editor and the preview confirms the result before it ever reaches your README. If any of the syntax looks unfamiliar, the cheat sheet has the whole language on one page, and what Markdown actually is explains why punctuation turns into formatting.

Alignment: the one row that does the work

Alignment lives entirely in the delimiter row, the second line of every Markdown table. Each cell in that row describes the column above and below it.

Every delimiter cell, valid and invalid

This reference covers every form you are likely to meet, including the four that quietly break the table.

Two habits that keep alignment useful

• Right align anything numeric. A column of prices or counts is far easier to compare when the digits stack up.
• Treat alignment as presentation only. Some static-site themes override it in CSS, and plain-text viewers ignore it. Use it to help people scan, never to carry meaning.

Watch out: A malformed delimiter cell does not produce a wonky table. It produces no table at all, and the whole block drops back to plain text with visible pipes.

Why tables are an extension, not core Markdown

Tables came to Markdown through GitHub, not through the original 2004 specification, so they belong to the GitHub Flavored Markdown dialect. Almost everything modern supports them, but a strict CommonMark parser with no extensions will not. For the full picture of what can go inside a cell, see the Markdown tables guide, and how to make a table in Markdown answers the question in short form.

Pasting from Excel, Google Sheets or a CSV

Some tables are half invented and half copied. You are drafting a comparison here, but the numbers already sit in a sheet somewhere. The grid takes those rows directly.

Tab-separated cells from a spreadsheet

Copy a block of cells out of Excel, Numbers or Google Sheets and the clipboard carries them as tab-separated values: one line per row, a tab between columns. Paste that into the grid and it splits back into cells on its own. A forty-row table then costs one keystroke instead of forty careful lines.

Comma-separated CSV text

CSV behaves the same way. This is what a small export looks like:

Region,Q1,Q2
North,1420,1655
South,980,1130
East,2075,1980

Paste it in, set the two number columns to right alignment, and you get:

| Region |   Q1 |   Q2 |
| :----- | ---: | ---: |
| North  | 1420 | 1655 |
| South  |  980 | 1130 |
| East   | 2075 | 1980 |

Two kinds of cell need attention before you paste.

Two cells that need care

• A cell holding a pipe character. | is the column separator, so the row splits in two. Escape it as \| and the cell survives. This bites anyone documenting keyboard shortcuts, regular expressions or command-line syntax.
• A cell holding a line break. A table row has to sit on one line, so replace the break with <br>.

Already have the whole table? Use the converter

There is a line worth drawing here. If the table is finished and you only want it as Markdown, this grid is the long way round. Send it to the table to Markdown converter instead, which reads spreadsheet cells, CSV text or a raw HTML <table> and returns the syntax in one paste.

Tip: Building something new, cell by cell? Stay here. Translating something that already exists? Convert it. That single question decides which page saves you time.

For whole documents rather than single tables, the HTML to Markdown converter handles a pasted page, and Markdown to HTML covers the reverse trip.

What goes wrong, and the fix

A broken Markdown table almost always fails in one of four ways, and each has a symptom you can see.

The table renders as text with visible pipes

Nine times out of ten the delimiter row is missing or malformed, or the table has no blank line above it. A table needs an empty line between it and the paragraph before, and its second line must be the dashes-and-colons row.

The column counts do not match

If the header has four cells and the delimiter row has three, most parsers refuse to build the table at all. A pipe inside your data causes the same fault from the other direction, since it adds a cell where you did not want one. Escape it as \|. Backticks will not save you, because inline code does not protect a pipe inside a table cell.

Generating the grid removes this failure mode completely, which is the main reason to use a generator on anything wider than three columns.

Alignment appears to be ignored

Check the destination rather than the syntax. Some documentation themes and email clients strip table CSS, and a few older parsers support tables without supporting alignment. Preview the result in the Markdown viewer or the editor to confirm the syntax is right before you blame it.

The table is too wide, or a cell is too big

• Nine columns. Unreadable on a phone, and clipped when the page is saved as a PDF. Cut optional columns, shorten the headers, or turn the table on its side so the long axis runs down the page.
• Line breaks vanishing inside a cell. That is expected behaviour. Use <br> instead.
• A cell that wants paragraphs, a list or a code block. The content has outgrown a table. Split it into headed sections, or write that part as raw markup, a trade-off Markdown versus HTML discusses.