microsoft / microsoft/markitdown

XLSX: first data row used as header → "Unnamed: N" columns + "NaN" cells; empty rows/cols not pruned

Open
#2,124 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
186k
Forks
13.7k
Avg merge
1d 4h
Merged PRs (30d)
49

Description

What happens

Converting an .xlsx whose first row isn't a clean header — a title cell, a spacer column, or merged/empty header cells, all common in real spreadsheets — produces noisy, misleading Markdown:

  • the first row is forced to be the column header, so other columns become Unnamed: N,
  • empty cells render as NaN,
  • fully empty rows/columns aren't pruned.

Real sheets expand to dozens of Unnamed: columns and NaN cells, which dominates the output and defeats the markdown-for-LLMs use case.

Minimal repro

markitdown[xlsx] 0.1.6, Python 3.12:

import openpyxl, tempfile, os
wb = openpyxl.Workbook(); ws = wb.active
ws["A1"] = "PROGRESS"                                   # a title in A1
ws["A3"] = "Task"; ws["C3"] = "Owner"; ws["D3"] = "Status"   # real headers on row 3 (col B blank)
ws["A4"] = "Design"; ws["C4"] = "Ana"; ws["D4"] = "Done"
p = os.path.join(tempfile.gettempdir(), "repro.xlsx"); wb.save(p)

from markitdown import MarkItDown
print(MarkItDown().convert(p).text_content)
Actual output
## Sheet
| PROGRESS | Unnamed: 1 | Unnamed: 2 | Unnamed: 3 |
| --- | --- | --- | --- |
| NaN | NaN | NaN | NaN |
| Task | NaN | Owner | Status |
| Design | NaN | Ana | Done |
Expected / suggestion

Faithful, denoised Markdown. The Unnamed: N / NaN strings are pandas DataFrame placeholders leaking into the output. Reading the sheet with header=None, dropping all-empty rows/columns, and rendering empty cells as blank would avoid the placeholders and make spreadsheet output usable.

Impact

For spreadsheet-heavy corpora this noise dominates the extract, undermining markitdown's stated purpose (clean Markdown for LLM/text pipelines).

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

No source file or test is named in the issue. Start by running the provided openpyxl/Python reproduction through the XLSX conversion entry point, then inspect the existing spreadsheet conversion tests if present. Done means the generated Markdown has no Unnamed or NaN placeholders and omits fully empty rows and columns.

Written by the indexing model from the issue text.

Assessment

Tech stack
pandas, python
Domain
data
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.