fix: keep an XLSX cell from breaking the markdown table

[chrikrah]

Related Issues

• No open issue covers this. Found while comparing the XLSX converter against the DOCX one after fix: keep a DOCX cell from breaking the markdown table #12779 landed.

Proposed Changes:

XLSXToDocument writes cell values straight into a pipe table when table_format="markdown", with no escaping. A cell containing | gains a column and loses its tail to any Markdown reader. A cell containing an Alt+Enter line break is split across two table rows.

DOCXToDocument already solves exactly this. _escape_markdown_cell at haystack/components/converters/docx.py:314-328 handles the same two patterns and was added in #12779, merged 2026-09-24. This ports it to the XLSX converter.

Three-row sheet with B2 = "blue | red" and B3 = "line1\nline2":

$ python repro.py
markdown:                            csv (the control, same commit):
|  2 | widget  | blue | red |         2,widget,"blue | red"
|  3 | gadget  | line1      |         3,gadget,"line1
|    |         | line2      |         line2"

Rendered through markdown-it with commonmark plus tables, that Markdown reads as:

['2', 'widget', 'blue']      <- "| red" is gone
['3', 'gadget', 'line1']     <- phantom extra row
['',  '',       'line2']

The class docstring at xlsx.py:30 says the content "is the table which can be saved in CSV or Markdown format", so the two formats have to describe the same table. Here they do not.

There is an implementation note for the reviewer, below.

How did you test it?

$ .venv/bin/python -m pytest test -m "not integration" -q
6588 passed, 8 skipped, 338 deselected, 6 warnings in 45.19s

Baseline on 8a5406e is 6586 passed, 8 skipped, 338 deselected, so the delta is the two new parametrised cases. Reverting haystack/components/converters/xlsx.py and keeping the test gives 2 failed, 6586 passed, both of them test_run_markdown_escapes_cell_content, on the pipe and line-break cases. The test mirrors the merged DOCX one.

ruff check and ruff format --check are clean on both touched files, and mypy --python-version 3.12 is clean on xlsx.py.

What I did not run: hatch is not installed here, so ruff and mypy ran directly instead of through hatch run test:types and hatch run fmt, and mypy covered the touched file instead of the whole tree. The integration, e2e and slow suites did not run.

Notes for the reviewer

The .map() placement matters, and the obvious version breaks two existing tests. pandas re-infers StringDtype after .map(), so the later .where(notna(), None) can no longer store None. That undoes #12776 and fails test_run_markdown and test_run_markdown_missing_value. The patch inserts .astype(object) between the two, and both stay green.

Checklist

• I have read the contributors guidelines and the code of conduct.
• I have updated the related issue with new insights and changes.
  No related issue exists, as noted above.
• I have added unit tests and updated the docstrings.
• I've used one of the conventional commit types for my PR title: fix:, and there are no breaking changes.
• I have documented my code.
• I have added a release note file, following the contributors guidelines.
• I have run pre-commit hooks and fixed any issue.

@sjrl you merged #12779, the DOCX half of this. Would you rather the escaping lived in one shared helper both converters import, instead of the copy this adds?

[vercel]

@chrikrah is attempting to deploy a commit to the deepset Team on Vercel.

A member of the Team first needs to authorize it.

[CLAassistant]

All committers have signed the CLA.