Markdown Tables: Readable Syntax, Alignment and the Mistakes That Break Them
How to write tables in Markdown that render correctly on GitHub, in docs and in blogs, including alignment, escaping pipes, long cells and when to avoid tables altogether.
Published October 18, 2026 · By Sudip Bhowmick
Markdown tables are handy for README files, documentation and notes, but the syntax is fussy. One missing pipe or a separator row with the wrong number of columns and the whole table collapses into plain text. This guide walks through the format, explains the usual failures and suggests how to keep tables readable in the source as well as in the rendered page.
The Basic Structure
A Markdown table has three parts: a header row, a separator row and the data rows. Columns are divided by vertical bars (pipes). The separator row is made of hyphens and tells the renderer that a table follows.
Example: a header line such as | Name | Role |, then | --- | --- |, then rows such as | Ana | Editor |. The number of cells in every row should match the header.
Alignment
Colons in the separator row set the alignment of each column.
- ▸A colon on the left (:---) aligns the column to the left, which is the default.
- ▸Colons on both sides (:---:) center the column.
- ▸A colon on the right (---:) aligns to the right. Use this for numbers so digits line up.
Alignment is applied to the whole column, header included.
Mistakes That Break Tables
- ▸Missing separator row: without it, the lines are rendered as ordinary paragraphs.
- ▸Unequal column counts: some renderers pad short rows, others fail. Keep every row the same width.
- ▸A pipe character inside a cell: it is read as a column break. Escape it with a backslash or replace it with the HTML entity for a pipe.
- ▸A blank line in the middle of the table: this ends the table and starts a new paragraph.
- ▸Line breaks in cells: standard Markdown tables do not allow them. Many renderers accept an HTML br tag as a workaround.
- ▸No blank line before the table: some parsers need an empty line separating the table from the paragraph above it.
Keeping the Source Readable
You do not need to pad cells with spaces for the table to render, but aligned columns make the raw file much easier to edit and review in a pull request. Padding by hand is tedious, which is where the Markdown Table Generator helps: enter your rows and columns, and it outputs a correctly formed, aligned table to paste into your document.
Converting an existing table works too. If your data is in a spreadsheet, export it and use the CSV to JSON or list tools to reshape it first, then generate the Markdown.
When Not to Use a Table
Tables are for comparing the same attributes across several items. If a cell contains paragraphs, code blocks or lists, the table will be hard to read and hard to maintain. A heading with a short list under each item is usually clearer. Wide tables also suffer on phones, where they scroll sideways. Keep the number of columns small, and put the most important column first.
Conclusion
A Markdown table works when the structure is exact: matching column counts, a proper separator row, escaped pipes and no stray blank lines. Add alignment for numbers, use a generator to save effort, and choose a list instead whenever the content is too heavy for a grid.
Free Tool
Open the Markdown Table Generator