Render multiline cells as <br> instead of breaking the table

[timvink]

Closes #83.

The issue's diagnosis was off

The report asks for csv.reader from the stdlib as a new reader, because "the pandas readers don't recognize multiline cells in CSV". They actually do — pd.read_csv parses the reporter's own example correctly:

{'id': 23456, 'severity': 'low', 'description': 'Sometimes the cell text is quoted.\n\nBut not always'}

What broke was rendering. df.to_markdown(tablefmt="pipe") emits the embedded newline literally, so one logical row shatters into three broken ones:

| 23456 | low        | Sometimes the cell text is quoted. |
|       |            |                                    |
|       |            | But not always                     |

Adding csv.reader would have changed nothing — it returns the identical cell value.

The fix

In convert_to_md_table, newlines in cells and column names are replaced with <br>, alongside the pipe escaping that was already there. Both now run in a single escape() pass.

This is guarded on tablefmt: it only applies to pipe and github, which put a row on one line. Formats like grid render multiline cells natively, and injecting <br> there would be visible junk.

Because the fix sits in the markdown conversion rather than in a reader, it benefits every reader — read_excel, read_yaml, read_json and friends, not just read_csv.

No new config option: a cell with a newline produces a broken table today, so there's no working behaviour to preserve.

Note on the second example in the issue

The first block in the report isn't valid CSV — the line break isn't inside quotes:

12345,medium,Example description text.

With line breaks in cell content

csv.reader splits that into three separate records too, so no reader change could have helped. Multiline cells have to be quoted, which the docs note now says.

Tests

• test_replace_newlines — unit coverage for the new helper
• test_convert_to_md_table_multiline — asserts the table stays 4 lines
• test_convert_to_md_table_multiline_other_tablefmt — asserts grid output is untouched
• test_csv_with_multiline_cells — full mkdocs build over a new tests/fixtures/csv_multiline/ fixture, asserting 3 <tr> in the rendered table

Full suite passes (38), mkdocs build --strict is clean.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Uz8oZU8gDib9swRkLKSoXe