Convert CSV or JSON to a Markdown table without corrupting data

Problem

Spreadsheet exports and API examples look simple until a quoted comma, embedded newline, uneven row, late JSON key, nested object, null value, large identifier, pipe character, or HTML-shaped string changes the table. A converter can still emit plausible Markdown while moving data into the wrong column or rounding a number. The task is therefore not just to create pipe syntax; it is to preserve the intended records, disclose unavoidable normalization, remove sensitive fields, and prove that the destination renders the same table readers are meant to see.

When to use this

• A reviewed spreadsheet export needs to become a compatibility matrix, release table, inventory excerpt, or README reference.
• A small API response fixture should be documented as rows while preserving false, zero, null, and keys that appear in later objects.
• A support runbook or incident appendix needs a compact table from scrubbed operational records without uploading source data to a conversion service.
• A data-contract change needs a before-and-after Markdown fixture whose row count, column count, escaping, and mobile rendering can be reviewed in a pull request.

Steps

1. Step 1

   Define the audience and isolate a safe representative fixture

   Decide what question the table must answer and keep only the rows and columns needed for that answer. Remove access tokens, email addresses, customer identifiers, internal hosts, unpublished prices, and unrelated metadata. Preserve difficult but non-sensitive cases such as a quoted delimiter, multiline note, false, zero, null, later-added key, long value, and literal pipe so the fixture tests the real contract instead of an unrealistically clean sample.

2. Step 2

   Confirm whether the source contract is CSV or JSON

   For CSV, identify the export delimiter, quote character, header policy, line ending, and encoding. Do not infer structure by visually splitting on commas because quoted fields can contain commas and newlines. For JSON, require a strict top-level array of objects and decide whether nested arrays or objects are acceptable as compact cell text. Convert exact large identifiers to JSON strings at the source rather than allowing JavaScript number parsing to round them.

3. Step 3

   Convert with explicit delimiter, header, and alignment choices

   Open Data Table Workbench and select CSV or JSON. In CSV mode, use automatic delimiter detection only when the export contract is unknown, then verify the detected character; otherwise select the known comma, tab, semicolon, pipe, or one-character custom delimiter. Set the first-row header option accurately. Choose alignment for presentation, not as a substitute for typing or validating numeric data, and run the conversion manually.

4. Step 4

   Resolve every parser, shape, and precision finding

   Stop on malformed quotes, invalid JSON, primitive JSON rows, duplicate keys, unsafe integers, lossy decimals, or resource-limit errors. Review warnings for blank rows, uneven CSV records, generated or duplicate headers, nested values, null cells, multiline content, edge whitespace, and HTML-shaped text. Compare reported row and column counts with the source fixture and explain every difference before accepting the output.

5. Step 5

   Compare the visual preview with the generated Markdown

   Scan the preview by row and column, including the last record and every field that was missing in some objects. Then inspect the Markdown source for escaped pipes, backslashes, generated <br> markers, non-breaking space entities, encoded HTML characters, alignment markers, and compact nested JSON. Confirm that false and zero are visible and that null, missing, and empty-string cells are not being treated as the same business state without an explicit label.

6. Step 6

   Render, review, and publish in the real destination

   Copy or download the .md file and render it with the exact GitHub, wiki, static-site, or documentation build that will publish it. Check table semantics, long cells, code-like values, links, raw HTML policy, 390px mobile overflow, dark mode, keyboard reading order, and the final diff. Run the repository formatter, linter, link checker, accessibility check, and production build where applicable, then publish only from the reviewed artifact.

Example

[{"name":"Ada","active":true,"owner":{"team":"Docs"}},{"name":"Grace","active":false,"score":0,"owner":null}]

A GFM table with name, active, owner, and score columns in first-seen order. The nested owner is compact JSON, false and zero remain visible, null becomes an empty owner cell with a warning, and the table is checked in the destination renderer before publication.

Common mistakes

FAQ