Proposal: optional source maps from Markdown back to document locations

[Jabrail (jabrailkhalil)]

I would like to add optional provenance output alongside converted Markdown. A consumer should be able to trace a passage back to a DOCX paragraph or an XLSX sheet/cell range without guessing from the rendered text.

My first scope would be DOCX and XLSX only: Markdown plus a JSON sidecar linking output spans to source locations. I would mark unsupported or ambiguous mappings explicitly, keep ordinary conversion unchanged, and add fixtures for repeated text, tables, and merged cells. I would not promise page geometry for formats where the converter cannot recover it.

I am proposing a library/CLI capability within MarkItDown's contribution scope. Is a sidecar the right starting point, or would you prefer an extension to the conversion result? I can develop the first converters once that contract is agreed.

I have experience taking a new upstream direction from maintainer agreement to reviewed implementation, including Qwen Code's merged Android connection profiles.