How to Write Markdown Tables

What a Working Table Looks Like

A Markdown table has three parts: a header row, a separator row and data rows. Header and data rows separate cells with the pipe character |; the separator row is made of hyphens -. The smallest working table:

| City | Value | Growth |
| --- | --- | --- |
| City A | 2487 | 1.2% |
| City B | 1769 | 2.8% |

Note that each cell in the separator row needs at least three hyphens to be valid — | -- | is not enough. This is the most common first failure.

The Three Places It Goes Wrong

The separator row must match the header column count

The number of pipes in the separator row determines the column count. A three-column header with a two-column separator makes most renderers either fail to render the table at all or silently drop the surplus data columns. The check is simple: count the - groups in the separator row and match them against the | count in the header.

Alignment markers belong in the separator row only

Left, centre and right alignment are all marked in the separator row, with the position of the colon : doing the work: leading colon for left, trailing colon for right, both sides for centre. These markers must not appear in the header or data rows.

| Name | Value | Note |
| --- | --- | --- |
| A | 12 | centred |

# Right-align the value column:
| Name | Value | Note |
| --- | ---: | --- |
| A | 12 | left-aligned |

Pipe characters inside cells must be escaped

The pipe is the delimiter itself, so inside content it must be escaped as | or it is read as a column separator. Escaping it in the opposite direction does not help — there is no non-table meaning of the character to fall back on.

There is also a way to avoid the problem entirely: if the table comes from Excel or a web page, let Table to Markdown generate it. The column counts, alignment markers and escaping it outputs are correct, which means fewer mistakes than by hand.

Converting Directly from Excel or a Web Table

The mistakes that come from typing a table by hand are the ones a converter removes entirely. Table to Markdown accepts both HTML tables and Excel tables and outputs standard Markdown. The separator row column count, alignment markers and pipe escaping are all computed at generation time, so there is nothing to go back and check.

1. 1HTML table: paste the whole <table> block into the input.
2. 2Excel table: upload the file and select the region to convert.
3. 3Check the alignment it produced: it defaults to content length, and right-aligning a numeric column means moving the colon in the separator row after generation.
4. 4Copy the Markdown result and paste it into your document.

When to Use a Table, and When Not To

Tables are for two things: parallel comparison across a fixed set of dimensions, and structurally fixed fields that must be quoted precisely — parameter tables, lookups. Beyond those two, a table is usually a bad trade.

• More than five columns: mobile viewports squeeze them, so switch to sections plus lists.
• Cells containing long paragraphs: the table degenerates into a layout device the reader cannot scan.
• Only one column: write a titled list instead; the table shell adds nothing.
• The data is a time series: use a chart instead, see Excel to Chart.

Tables Inside a Rich-Text Article

Rich-text editors have limited table support. Converted tables tend to break on narrow screens, and long tables especially — column widths are fixed, so extra content overflows. That is a limit of the editor, not of the converter.

If a table is essential in the article, turn it into an image: produce a Markdown table with Table to Markdown, render it, then screenshot and paste the image. The surrounding workflow is in Article Layout: From Markdown to a Ready-to-Publish Draft.

Frequently Asked Questions

The table rendered as plain text — why?

Almost always the separator row: mismatched column count, fewer than three hyphens, or a missing row. Renderers degrade an invalid table to plain text, which is the worst failure mode but the easiest to diagnose.

Can cells have inline styling?

No. Markdown tables do not support cell-level styling. For a styled table, either write an HTML table or export it as an image.

Can I convert directly from Excel?

Yes. Table to Markdown accepts both HTML tables and Excel tables and outputs standard Markdown. It does not judge column widths or alignment for you — it uses default values based on content length.

What about merged cells?

Markdown tables do not support row or column merging. If the data needs them, either restructure it so it can be expanded, or present it as an image — the latter is more common in articles.

Summary

Three hard constraints on Markdown tables: separator row column count, placement of alignment markers, and escaping pipes inside cells. Once those are remembered, the rest is taste.

If the table comes from somewhere else rather than being typed, convert it with Table to Markdown and skip the manual steps. For choosing how to present data, see Charts and Tables.