CSV to Markdown Table

Why pipe escaping is the whole problem

A Markdown table cell is delimited by |, and there is no escaping mechanism in the specification — GitHub only honours a literal backslash before the pipe. So a CSV cell containing a|b silently splits into two columns, and a cell containing a line break ends the row. Both are handled here: pipes become \| and embedded newlines become <br>.

Rows shorter than the header are padded with empty cells, and rows that are longer have the extra cells dropped, so the output table never has a ragged column count.

Alignment

Alignment lives in the separator row, not in the cells: | :--- | is left, | :---: | is centre and | ---: | is right. Leaving it on None emits plain ---, which most renderers treat as left-aligned anyway — but a great many linters prefer it explicit.

Reading the source, not just the render

A Markdown table stays in your repository forever, so Pad columns rewrites the source with the pipes lined up. GitHub ignores the extra spaces, and the diff you see in a pull request becomes readable instead of a wall of ragged pipes.

Edge cases worth knowing

• A missing header row. With First row is header off, the first row becomes a data row and the table gets no header — useful for tables that continue an earlier one on the same page.
• Quoted fields containing the delimiter are parsed correctly, so "New York, NY" stays a single cell.
• A UTF-8 BOM — the invisible character Excel writes at the start of a file — is detected and stripped, otherwise the first column name would carry it into the header.
• Pipes inside the CSV itself. A pipe-delimited file is supported: choose | as the delimiter and the pipes in the cells are still escaped on output.

FAQ