Markdown Comparison Table

Comparison tables in Markdown

Markdown does not specify tables in its 2004 base syntax — they were introduced as an extension and standardised by GitHub Flavored Markdown (GFM). Today almost every renderer that matters supports them: GitHub, GitLab, Bitbucket, Obsidian, Notion (with quirks), VS Code preview, Pandoc, MkDocs, Docusaurus and Hugo. A table is a clean way to compare alternatives side by side: pricing tiers, framework features, API endpoints, schema definitions. The Markdown is editable in plain text, plays well with version control diffs and renders to a semantic <table> that screen readers expose properly.

GFM table syntax

Every table is three blocks: a header row, a separator row using dashes, and one or more body rows. Alignment is controlled by the colons in the separator:

| Framework | Bundle (kB) | Maintainer |
|-----------|:-----------:|-----------:|
| React     |     45      |       Meta |
| Vue       |     34      |  Evan You  |
| Svelte    |    1.6      |  Rich Harris |

• :--- aligns left (also the default)
• :---: centres the column
• ---: aligns right — perfect for numeric data

Common gotchas

• The pipe character inside a cell must be escaped as \| or replaced with the HTML entity |, otherwise the parser thinks the row ended.
• Markdown does not honour literal line breaks inside a cell — use <br> for a soft break and inline HTML lists (<ul><li>) when you need bullets.
• There is no Markdown syntax for rowspan or colspan — fall back to raw HTML or split the table.
• Some renderers (Reddit, Discord, several chat apps) ship a Markdown subset that strips tables entirely.
• Tables past ten columns become unreadable on mobile — break them into two or rotate them on the page.

Working at scale

For large tables that get edited by many people, hand-formatting columns is painful. tablesgenerator.com and markdowntables.online offer WYSIWYG editors that emit GFM; vim-table-mode and the VS Code extension "Markdown All in One" reformat columns as you type. Pandoc converts to and from CSV, LaTeX, HTML and DOCX tables, which is handy when you import data from a spreadsheet. Embedding an image works the same as anywhere else in Markdown — ![alt](url) inside a cell renders inline.

FAQ

Do tables render on a GitHub README? Yes. GitHub uses GFM and renders Markdown tables, with alignment, links and inline HTML.

Can I align each column independently? Yes — every separator cell controls its column independently via the colon placement.

What if my table is too wide? Break it into multiple tables grouped by theme, transpose rows and columns, or replace it with a definition list. On HTML output you can also wrap it in a <div style="overflow-x:auto"> for horizontal scrolling on mobile.

Can I embed an image inside a cell? Yes, ![alt](https://...) works inside a cell. Keep the image small or it will blow out the row height.