Markdown Table Generator - From CSV or Excel

Markdown table syntax in 30 seconds

A Markdown table is three things: a header row, a separator row, and data rows. Each row starts and ends with a pipe (|), and pipes separate the cells. The separator row sits directly under the header and contains at least three dashes per column. That is the whole spec in GitHub Flavored Markdown, which is what GitHub, GitLab, Bitbucket, Notion, Obsidian, VS Code, and most static site generators follow.

The outer pipes are technically optional and the columns do not have to line up. Renderers do not care. But a padded table where every pipe sits in the same column is far easier to review in a pull request diff, which is why the generator pads every cell to the widest value in its column.

Alignment with colons

Alignment lives in the separator row. :--- aligns left, ---: aligns right, :---: centers, and plain --- leaves it to the renderer (left in almost every case). Right-aligning numbers is the one rule worth following: prices, counts, and percentages are easier to compare when their last digits line up.

Auto mode does that for you. It checks each column, and if every data cell is a number, a price like $12 or €9.50, or a percentage, the column is right-aligned. Everything else goes left. Header text is ignored in that check, so a column called Price with values like $0, $12, and $49 still counts as numeric.

Worked example

Paste four rows from a pricing spreadsheet: Plan, Price, Storage, Users as the header, then Free, $0, 5 GB, 1 and two more plans. With Auto alignment, Price and Users come out right-aligned (their separators end in a colon) and Plan and Storage stay left, because "5 GB" contains letters. The widest value in each column sets the width, with a minimum of three characters so the separator is always valid.

The result pastes straight into a README and renders as a real table on GitHub. Because the source is padded, it also reads cleanly as plain text in a terminal or code review.

Characters that break tables

The pipe. Any | inside a cell ends that cell early and shifts everything after it one column to the right. The fix is a backslash: \|. The generator escapes pipes automatically, which matters for things like shell commands (grep foo | wc -l) and type unions (string | null) in API docs.

Line breaks. A newline ends the row, full stop. If a spreadsheet cell contains multiple lines, the generator replaces the breaks with <br>, which GitHub and most renderers display as a line break inside the cell. Avoid block content in cells entirely: lists, code blocks, and headings are not supported inside Markdown tables.

Ragged rows. If one row has fewer cells than the header, some renderers drop the row or misalign it. The generator counts the widest row and fills short rows with empty cells, so every row has the same number of columns.

Common mistakes

No blank line before the table. On GitHub a table directly under a paragraph line may render as plain text. Leave an empty line above it.

Splitting CSV on commas by hand. "Portland, OR" becomes two columns. The generator parses quotes properly, so quoted commas stay in one cell.

Using a table for layout. Tables are for data with rows and columns. If you only have two columns of label and value, a simple list is often easier to read on mobile, where wide Markdown tables scroll sideways.

Markdown or HTML?

Markdown tables cover about 90% of documentation needs and stay readable as source. Switch to an HTML table when you need merged cells (colspan or rowspan), multiple header rows, captions, or block content inside cells. GitHub renders a subset of raw HTML in Markdown files, so you can drop an HTML table into a README when Markdown runs out. The HTML table generator on this site builds that markup from the same CSV input.