GitHub README files are the front door of every open-source project. A well-formatted Markdown table can communicate API parameters, feature comparisons, or configuration options more clearly than paragraphs of prose. Here's what you need to know.
Markdown Table Syntax
A GitHub Markdown table consists of a header row, a separator row, and one or more data rows. Columns are delimited by pipe characters (|). The separator row uses hyphens (---) and optional colons for alignment.
Left-aligned: :--- | Center-aligned: :---: | Right-aligned: ---: | Default (left): ---
Escaping Special Characters
If a cell value contains a pipe character (|), escape it with a backslash: \|. Otherwise it will break the table structure. MDFileConverter handles this automatically when converting from Excel or CSV.
Line breaks inside cells are not supported in standard GFM. If you need multi-line cells, use HTML br tags — but be aware that not all Markdown renderers support inline HTML.
Common Pitfalls
Missing separator row: GitHub requires the separator row between the header and data. Omitting it causes the entire block to render as plain text.
Unequal column counts: Every row must have the same number of columns as the header. Mismatched counts cause unpredictable rendering. MDFileConverter normalizes column counts automatically.
Keeping Tables Readable in Source
Padded tables (where each column is manually aligned with spaces) are easier to read in source but harder to maintain. Compact tables (minimal spacing) are more common in practice. GitHub renders both identically.
For large tables with many columns, consider splitting them into multiple smaller tables or using a list format instead — very wide tables wrap awkwardly on mobile.