Markdown tables are one of the most commonly misused features in GitHub READMEs. They're overused for data that would be clearer as a list, underused for comparison data that would be much clearer as a table, and often formatted with errors that break rendering. Here's a practical guide to using them well.
When Tables Are the Right Choice
Use a table when you're comparing multiple items across the same set of attributes. A feature comparison matrix, a benchmark results summary, an API endpoint reference, a list of configuration options with types and defaults — these are all natural tables.
Don't use a table for simple lists. A list of prerequisites, a set of steps, or a collection of links is better as a bulleted or numbered list. Tables add visual complexity that only pays off when the columnar comparison adds genuine value.
GitHub Markdown Table Format
GitHub renders pipe-delimited Markdown tables. The minimum valid format is:
| Column 1 | Column 2 | |----------|----------| | Value A | Value B |
Column widths don't need to be padded — GitHub normalises them. But padded tables are much easier to read in raw form, which matters because contributors editing the README directly see the raw Markdown.
Upload your CSV and see exactly what's wrong — Sohovi profiles quality in seconds — try Sohovi free.
Column Count and Table Width
Keep tables under 6-7 columns for readability on standard screen widths. Tables that scroll horizontally on mobile are a poor experience. If you have more than 7 attributes to compare, consider splitting into two tables or reorganising the information.
Alignment Conventions
Follow these conventions for a professional result: right-align numeric columns (sizes, counts, measurements) so digits align vertically. Left-align text columns (names, descriptions, URLs). Center-align status columns (✓, ✗, boolean values).
Generating Tables From CSV
If your data lives in a spreadsheet — benchmark results from a test run, API endpoint documentation exported from a tool, a configuration reference generated by a script — convert from CSV rather than writing the Markdown manually.
Sohovi gives you a full quality report on any spreadsheet in seconds — upload your file and see exactly what needs fixing.
The workflow: export or save as CSV → convert to Markdown in a browser tool → copy the output → paste into the README. When the data changes, re-export and re-convert. This keeps the table accurate without manual editing risk.
HTML Tables Are Not a Good Fallback
Avoid HTML tables in GitHub READMEs. They work in some contexts but break in others — the GitHub rendering pipeline sometimes strips HTML attributes, and raw HTML is much harder for contributors to edit. Stick to Markdown pipe tables unless you have a specific rendering requirement (like complex cell content) that Markdown tables can't handle.
Sohovi's free CSV to Markdown converter generates GitHub-compatible tables with alignment control and live preview.
Keep Reading
Convert CSV to Markdown Table Free →