Publishing a CSV as a table people can read

A CSV is for machines and it shows

Comma-separated values is the smallest agreement two programs can reach about a grid, and that minimalism is the whole point. It is also why pasting one in front of a person does not work: columns only line up when something aligns them, and a CSV asks the reader to do that in their head.

So the question is never “how do I show this CSV”. It is “where is it going”, and the answer decides the format.

A web page: HTML

CSV to HTML produces table markup, which matters for two reasons that are usually stated as one.

The visible reason is alignment. A browser lays out a <table> in columns; it lays out text in a paragraph.

The less visible reason is that markup is what associates a cell with its heading. A screen reader announcing “Region: North” rather than just “North” is reading the structure, and no amount of visual alignment provides that. A table that looks right and has no headers is a table that only works for people who can see it.

Keep the first row as a header row. Almost every CSV has one, and it is the piece that carries the meaning.

A repository or an issue: Markdown

CSV to Markdown is for the places that render Markdown and nothing else: pull requests, issues, wikis, READMEs.

The constraint worth respecting is length. Markdown tables get read as raw source at least as often as they get rendered, and beyond about thirty rows the source becomes unreadable while the rendered version becomes a wall nobody scrolls. Long data belongs in an attached file, with the three interesting rows in the text.

If you are writing the surrounding prose in Markdown too, Markdown to HTML turns the whole thing into a page.

Anything printed, filed or emailed: PDF

CSV to PDF exists because a table that has to be attached to an email, filed with a court, or handed across a desk needs fixed pages. So does Excel to PDF, and both go through the same layout deliberately: a CSV and the spreadsheet somebody made from it should come out the same shape.

Here is the decision every such conversion has to make and most tools make silently. A table wider than the page has to lose something: the width of the paper, the size of the type, or some of the columns. Shrinking the type produces a table nobody can read. Truncating cells produces one where every value might be wrong.

So columns that will not fit are dropped, and the result says how many. A table visibly missing a column is a better outcome than one you cannot read or cannot trust, and you still have the CSV.

A system that demands it: XML

CSV to XML is not a format anybody chooses freshly. It is the one plenty of systems still require - banking uploads, government filings, older enterprise imports - and the reason to use a converter rather than a template is escaping.

A company name containing an ampersand breaks a hand-built XML file. So does a quote in an address, or an angle bracket in a product description. These are ordinary values, they appear in real data constantly, and the failure arrives as an import that rejects the whole file with a message about line 4,812.

What every one of them loses

It is worth being explicit, because the thing that survives is narrower than people expect.

Formulas do not survive any of them. A CSV never held a formula in the first place - it holds whatever the formula evaluated to at export time - so a total that was a live sum becomes a number that will never update again. That is usually what you want in a published table and occasionally a nasty surprise.

Types do not survive either. A CSV has no idea that one column is a date and another is a postal code; every value is text, and whatever reads it next guesses. This is where leading zeros disappear and where an identifier like 03-2024 arrives as a date in March. Converting to a fixed output like HTML or PDF is actually the safest thing you can do with such a column, because nothing downstream gets another chance to reinterpret it.

Column order survives, row order survives, and the header row survives. Plan on that and nothing else.

Clean before you convert

Every format above renders what it is given faithfully, including the mess. A stray column from a bad export becomes a stray column in the PDF.

Cleaning the CSV first is the step worth taking: check the delimiter, make the headers unique, look at what is about to be dropped as duplicate. Conversion is the easy half.

None of it is uploaded

Every tool named here runs in your browser. A CSV is usually a list of people, orders or transactions, which makes it exactly the kind of file that should not be posted to a stranger’s server to be made presentable.