How to Add Tables to a GitHub README — Generate Markdown Tables from CSV/JSON

If you need a table in your README, the fastest path is to paste your CSV into CSV to Markdown and hit Run. It produces a GFM-compatible table you can copy straight into your README, all inside the browser.

This article covers when README tables make sense, how to generate them from CSV or JSON, and what to watch out for with GitHub Flavored Markdown.

When a README needs a table

Plain text works until the information grows. The following kinds of content read much better as tables:

• API endpoint lists (path, method, description)
• Supported versions or platform compatibility matrices
• Feature comparisons (your project vs. alternatives, or free vs. paid)
• CLI option references
• Environment variable lists with defaults

Bullet lists stretch vertically and make it hard to compare across columns. A table lets readers scan horizontally and spot differences immediately.

Markdown table basics

GFM tables use pipe characters as column separators:

| Command | Description |
| --- | --- |
| install | Install dependencies |
| build | Build for production |
| test | Run the test suite |

Row one is the header, row two is the separator, and every row after that is data. Add : to the separator to control alignment (:--- left, :---: center, ---: right).

For a deeper dive into the syntax, see Markdown table syntax.

Generate a README table from CSV

When your data lives in a spreadsheet or a CSV file, use CSV to Markdown:

1. Open CSV to Markdown
2. Paste your CSV into the left editor (copy-paste from Excel or Google Sheets works too)
3. Press Run
4. Copy the Markdown table from the right pane into your README

Everything runs in the browser — no data leaves your machine. For more detail on edge cases and escaping, see How to convert CSV to a Markdown table.

Create a table from JSON data

Sometimes your data starts as JSON — an API response, a config dump, a log extract. The most reliable route to a Markdown table is to go through CSV first.

For a deeper walkthrough covering arrays, nested objects, and API responses, see How to convert JSON to a Markdown table.

Steps

1. Format the JSON with JSON Formatter to verify its structure
2. Convert the JSON array to CSV (object keys become column headers, values become row cells)
3. Paste the CSV into CSV to Markdown to generate the table

For example, given this JSON:

[
  { "name": "Node.js", "version": "20.x", "status": "LTS" },
  { "name": "Node.js", "version": "22.x", "status": "Current" }
]

The CSV equivalent is:

name,version,status
Node.js,20.x,LTS
Node.js,22.x,Current

Paste that into CSV to Markdown and the table is ready for your README.

GFM table quirks on GitHub

GitHub's Markdown renderer behaves differently from general-purpose Markdown editors in a few ways.

Limited HTML inside tables

GitHub strips most inline HTML for security. <br> works for in-cell line breaks, but <span style="..."> and similar inline styles are ignored. Do not rely on color or font-size changes inside table cells.

Column alignment

The : alignment syntax in the separator row works as expected on GitHub. Right-aligning numeric columns makes version numbers and prices easier to scan.

| Plan | Monthly |
| :--- | ---: |
| Free | $0 |
| Pro | $10 |

Wide tables and horizontal scroll

Tables with many columns trigger horizontal scrolling on GitHub. If readers will view the README on both desktop and mobile, keep tables to five or six columns, or split them into separate tables.

Frequently asked questions

Can I manage README tables in a spreadsheet?

Yes. Keep the source data in a spreadsheet, export CSV whenever the content changes, and run it through CSV to Markdown to regenerate the table. Paste the result into the README and commit.

Can I put links inside table cells?

Yes. Standard Markdown link syntax [text](url) works inside GFM table cells and renders as clickable links on GitHub.

How do I add line breaks inside a cell?

The GFM table spec does not support literal newlines inside cells. Use a <br> tag — GitHub renders it as a line break within the cell.

Wrapping up

Tables make README content scannable. Writing pipes by hand is fine for a few rows, but anything larger calls for automation. CSV to Markdown generates the table from pasted CSV in seconds, so you can spend your time on the content instead of the formatting.