CSV to Markdown Table Converter
A clean Markdown table makes a README readable both as rendered output and as raw source. The trick is the column-width padding: GitHub does not require it, but a table whose pipe separators are aligned in the source file is dramatically easier to maintain than one where every row is a different length. This tool emits the padded form by default, with optional per-column alignment markers and automatic header detection.
Why Padded GFM Output Matters
GitHub-flavored Markdown accepts unpadded tables (every cell snug against the pipes, no alignment in the source) and renders them fine. But the moment a colleague opens the file in a plain-text editor to fix a typo, they have to count pipes to find the right column. A padded table — every cell padded with spaces so the pipes line up vertically — reads as a real table in the raw view too, and diff tools show row-level changes cleanly instead of a single mass-changed line. This tool calculates the width of every column (display width, not byte length, so wide CJK characters and emoji are handled correctly) and pads each cell to match.
Header Row Detection and Alignment
By default, the first row of the CSV is treated as the table header. You can override this if your file has no header. GFM requires a divider row right under the header (|---|---|---|), and that divider also encodes per-column alignment: :--- for left, :---: for center, ---: for right. The tool lets you set alignment per column from a dropdown, and the divider row is generated accordingly. If you do not set alignment, GitHub defaults to left for the body and bold for the header — which is what most READMEs want.
Use Cases for Tabular Markdown
Common cases: drop a metrics export into a project status update, paste a price list into a documentation site, summarize benchmark results in a GitHub issue, or convert a spreadsheet of API endpoints to a doc-site reference table. Markdown tables also render in Slack, Discord (via embed), Notion, Obsidian, and most static-site generators (MkDocs, Docusaurus, Astro). The same CSV becomes the source of truth and the table is generated each time the data changes — the markdown version updates from the same script that updates the CSV.
Edge Cases Handled by the Renderer
Pipes inside cells: GFM does not allow literal | inside a table cell because that ends the column. The tool escapes them to \|, which renders as a literal pipe character. Newlines inside cells: GFM does not support multiline cells either. The tool replaces in-cell newlines with <br>, which most GFM renderers respect (GitHub, Gitea, MkDocs, Docusaurus all do). Empty cells: rendered as empty padded space, which keeps the source aligned. Wide CJK and emoji: the column-width calculator uses Unicode East Asian Width data so wide characters count as two display columns and the table stays aligned visually.
Pair this with other Markdown tools on the site: Markdown Preview to see the rendered table, HTML to Markdown if your source is an HTML table instead, Markdown Table Generator for tables built by hand, and CSV Viewer to verify the input CSV first. The CSV-side cleaning passes from CSV Cleaner also pair well — normalize the source, then convert.
Frequently Asked Questions
Built by Derek Giordano · Part of Ultimate Design Tools