Convert CSV or TSV to a Markdown table

Decide whether the result is for reading or importing

Use this converter when a short table will make a README, issue or note easier to read. It parses delimited text and produces Markdown source. It does not generate an image, host a document or replace the original dataset. Keep the CSV or TSV if someone will need all the rows, exact field boundaries or a file they can reimport. A Markdown table is most useful when the audience needs to scan a representative excerpt.

Select just the columns and rows the reader needs. A five-column comparison can be readable where a twenty-column export forces horizontal scrolling or hides the fields that matter. For a release note, for example, a summary, an identifier and a status may be enough. Keep private notes and personal fields out of the excerpt even if they are present in the original file. Local conversion does not make the resulting document private once you post it elsewhere.

If you are documenting what an importer expects, include a small raw sample alongside the rendered table. A rendered header can help people understand a format, but it may not show exactly where a separator, quote or newline occurred. Link or attach a separate sample for actual data exchange.

Test a comma and a literal pipe in the same row

Paste the following into the editor with Comma selected and First row is the header enabled. The quoted city should stay in one cell. The pipe within the second field in the next column is not a structural separator in the CSV.

Name,City,Status
    Mia,"Portland, OR","Open | waiting"
    Noah,Paris,Ready

In the Markdown result, the header and each data row have three columns. The pipe in Open | waiting is escaped so a compatible table renderer can display it within the status cell. Notice that the Markdown uses pipes to delimit fields even though the original used commas. A literal pipe can therefore need escaping even when it had no special role in the source format.

If the sample fails to make three columns, check the chosen source separator and whether the quotes survived copying. Do not fix this by replacing every comma with a pipe. Doing so would split Portland, OR into separate cells and could turn a correct export into a misleading table. Select the destination's preview and check the visible cells before relying on the result.

Give the table useful headers and alignment

If your first row has names such as Date, Count and Reason, keep the header setting on. If your first row contains actual data, switch it off to keep that row in the table and generate labels such as Column 1. Replace generated labels with meaningful names before sharing a public table. A heading should identify the field and, where it matters, its units. “Time (ms)” is more useful than “Value.”

Use the alignment setting when it supports reading. Left alignment tends to work for text, while right alignment can make a short column of numbers easier to compare visually. Alignment adds Markdown syntax; it does not change the value type or verify that the field is numeric. Test the resulting table in the renderer you will use, since a destination may interpret or ignore alignment markers differently.

Short data rows are filled with blank cells to maintain a rectangular preview. A blank cell could represent a missing field or an explicit empty value. If that difference matters, inspect the source and annotate the presentation version. Do not treat a padded table as proof that every original record had the same shape. Use a table or schema check before handing the actual data to an importer.

Choose what a line break inside a cell should become

Quoted CSV values can contain line breaks. Markdown pipe tables are normally written as one source line per table row, so pasting those embedded breaks unchanged could disrupt the table. The converter can replace them with spaces for a compact display or output an HTML line-break element. The latter choice is only useful when the destination renderer allows and displays inline HTML.

For a short delivery instruction, replacing a break with a space may keep all the words readable. For an address, poem or list of distinct steps, the break may be significant. Use a line-break option that you have tested in the destination, or present the long cell outside the table. A small list following the table is often easier to read than a long paragraph squeezed into one cell.

When the underlying value must be preserved exactly, keep the original CSV or TSV. The table should not be your only record of the embedded newline. If the data is headed to a system that can parse structured records, use the delimiter converter or the CSV and JSON converter instead, depending on the representation the system expects.

Preview special characters in the actual destination

A pipe table may display differently between a repository viewer, a wiki editor and an issue tracker. Some renderers do not support pipe tables at all. Others support tables but remove inline HTML or interpret formatting inside cells. The converter escapes common inline punctuation and writes angle brackets as text. That protects the intended reading of many values, but you should still preview an example with a pipe, a long link or a cell containing code-like punctuation.

Paste the Markdown output into the destination as source, not into a field that expects a rendered rich-text table. Use its preview or test page to check the header, one normal row and the last row. If the pipe characters remain visible, verify that the destination supports tables and that the table begins in the right place in the document. A surrounding code block will intentionally display the Markdown source rather than render it.

If a value contains a URL, decide whether the visible text should be plain or linked. The utility does not open destinations or decide that a link is safe. A link in a shared document can still be followed by readers. For documentation examples, use fictional or approved destinations and inspect the rendered labels before publishing.

Share the table with enough context to interpret it

Add a short sentence that explains which records are shown and what the columns mean. For a status report, say whether the rows are examples or the full inventory. For a conversion example, tell the reader which separator and header settings produced it. That context is more useful than pasting a full export whose field names only make sense inside the originating application.

On a narrow screen, preview the longest heading and a row with the longest value. If it is difficult to read, reduce the number of columns, shorten the display labels without changing the source data, or split the presentation into two tables with different purposes. Keep the original identifiers when readers need to look up an item, but leave unrelated fields out. Make a second file available only when the audience actually needs the full dataset.

Before sending, verify that the visible row count matches the excerpt you intended to present. Look for a missing first record caused by a mistaken header setting, and inspect an empty cell to make sure it appears in the correct column. The structured text guide shows how to keep separate versions for a README, a machine import and HTML examples without confusing one for the other.