Writing

Markdown Table Syntax for GitHub README Files

GitHub Markdown tables use pipes and a separator row. The syntax is simple, but small mistakes can stop a README table from rendering correctly.

Start with a header row

The first line contains column names separated by pipes. A separator row with dashes goes under it, followed by the data rows.

Spaces can make the raw Markdown easier to read, but GitHub mainly needs the pipes and separator row to understand the table structure.

Before updating a README, paste or generate the table and check that each row has the expected number of columns.

Use a header row, a separator row such as | --- | --- |, and then one row for each item.

Yes. GitHub supports Markdown tables in README files, issues, pull requests, and many comments.

Common causes include missing separator rows, uneven pipe counts, or unescaped pipe characters inside cells.