feat(xlsx): render sheet names as headings in markdown export

[Smeet23]

Summary

Closes #3229

Sheet names in Excel workbooks are meaningful structure — this PR surfaces them as Markdown headings when converting XLSX files, giving users readable output like:

## Sheet1

| Col A | Col B |
|-------|-------|
| 1     | 2     |

## Sheet2

| Col C | Col D |
|-------|-------|
| 3     | 4     |

Implementation (reworked per @PeterStaar-IBM's feedback)

The original approach injected a SectionHeaderItem heading node into the document model in the backend. Per the reviewer's suggestion, this has been replaced with a cleaner serializer-based approach:

• msexcel_backend.py: switched from GroupLabel.SECTION / "sheet: <name>" to GroupLabel.SHEET / plain sheet name — no synthetic heading nodes injected
• docling/utils/markdown.py (new): adds MsExcelMarkdownFallbackSerializer (renders GroupLabel.SHEET groups as ## <name> headings) and MsExcelMarkdownDocSerializer (drop-in replacement for MarkdownDocSerializer when exporting Excel documents)
• Ground truth files regenerated to reflect the cleaner document structure

Open question: doc.export_to_markdown() uses MarkdownDocSerializer by default. To get headings automatically, callers currently need to use MsExcelMarkdownDocSerializer explicitly. If automatic heading output via doc.export_to_markdown() is preferred, a small companion PR to docling-core would be needed. Happy to pursue that path if you think it's right.

[github-actions]

✅ DCO Check Passed

Thanks @Smeet23, all your commits are properly signed off. 🎉

[mergify]

Merge Protections

Your pull request matches the following merge protections and will not be merged until they are valid.

🔴 Require two reviewer for test updates

Waiting for:

• #approved-reviews-by >= 2

This rule is failing.

When test data is updated, we require two reviewers

• #approved-reviews-by >= 2

🟢 Enforce conventional commit

Wonderful, this rule succeeded.

Make sure that we follow https://www.conventionalcommits.org/en/v1.0.0/

• title ~= ^(fix|feat|docs|style|refactor|perf|test|build|ci|chore|revert)(?:\(.+\))?(!)?:

[dosubot]

Related Documentation

1 document(s) may need updating based on files changed in this PR:

Docling

What are the detailed pipeline options and processing behaviors for PDF, DOCX, PPTX, and XLSX files in the Python SDK?

View Suggested Changes

@@ -112,6 +112,32 @@
     - Each sheet is treated as a page
     - Table detection via flood-fill, image extraction (bounding box based on cell anchor)
     - Includes provenance (location info), auto page size calculation
+    - Sheet names are stored in the document model using `GroupLabel.SHEET` for sheet grouping
+- **Markdown Export**: Sheet names are rendered as level-2 Markdown headings (`## <sheet_name>`) when using the `MsExcelMarkdownDocSerializer` class. This provides readable output that reflects the workbook's visual structure:
+
+```python
+from docling.utils.markdown import MsExcelMarkdownDocSerializer
+
+serializer = MsExcelMarkdownDocSerializer(doc=result.document)
+md = serializer.serialize().text
+```
+
+Example output format:
+
+```markdown
+## Sheet1
+
+| Col A | Col B |
+|-------|-------|
+| 1     | 2     |
+
+## Sheet2
+
+| Col C | Col D |
+|-------|-------|
+| 3     | 4     |
+```
+
 - **Notes**: Table detection algorithm and singleton cell handling are configurable. [Backend options code](https://github.com/docling-project/docling/blob/ae4fdbbb09fd377bb271e9b2efe541873eeb2990/docling/datamodel/backend_options.py#L80-L97).
 
 ---

[Accept] [Decline]

Note: You must be authenticated to accept/decline updates.

^{How did I do? Any feedback?}  

[PeterStaar-IBM]

This file needs to be in docling-core in this folder https://github.com/docling-project/docling-core/tree/main/docling_core/transforms/serializer

[Smeet23]

Done! Moved the serializer to docling-core in docling-project/docling-core#587. Removed docling/utils/markdown.py from this PR and updated all imports to docling_core.transforms.serializer.markdown_excel. Will bump the dependency once the docling-core PR is merged.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[Smeet23]

Thanks for the review @PeterStaar-IBM! Moved the serializer to docling-core in docling-project/docling-core#587.

Removed docling/utils/markdown.py from this PR and updated all imports to use docling_core.transforms.serializer.markdown_excel. Will update the dependency once the docling-core PR is merged.

[PeterStaar-IBM]

lgtm!

[Smeet23]

Hi @PeterStaar-IBM — the DCO sign-off has been fixed on all commits, and the test failures have been resolved by guarding the docling_core.transforms.serializer.markdown_excel imports with pytest.importorskip (they will skip gracefully until docling-core#587 is merged and released). CI is re-running on the fresh push. Could you please re-review and merge once everything looks good? Happy to address any feedback. Thanks! 🙏

[Smeet23]

Hi @PeterStaar-IBM — following up on the earlier feedback, here's what was addressed in the latest push:

• DCO: Fixed sign-off on all commits — all now carry Signed-off-by: Smeet23 <smeetagrawal2003@gmail.com> ✅
• Test failures: The ModuleNotFoundError for docling_core.transforms.serializer.markdown_excel was caused by docling-core#587 not yet being merged/released. Fixed by guarding both test imports with pytest.importorskip so they skip gracefully in CI until that lands.

DCO ✅ is now passing. Could you re-approve when you get a chance so Mergify can proceed? Happy to address any remaining concerns. Thanks!

[cau-git]

@Smeet23 docling-core 2.74.0 is now released with your changes. Can you please update the uv.lock so the test diff in this PR reflects the state you get with docling-core 2.74.0?

This should do it:

uv lock --upgrade-package docling-core

[Smeet23]

Hi @cau-git — done! Updated uv.lock with uv lock --upgrade-package docling-core, which bumped it to 2.74.0. Thanks for the heads-up!

[PeterStaar-IBM]

and re-do the DCO:

To add your Signed-off-by line to every commit in this branch:

1. Ensure you have a local copy of your branch by [checking out the pull request locally via command line](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/checking-out-pull-requests-locally).
2. In your local branch, run: git rebase HEAD~5 --signoff
3. Force push your changes to overwrite the branch: git push --force-with-lease origin feat/excel-sheet-names-as-headings

[cau-git]

@Smeet23 now that the updated docling-core is pinned, we are seeing CI tests fail - as expected. This is because the test ground truth encodes the old truth that has no sheet names in the markdown. You need to re-generate the test-ground truth for this PR and submit the changed test files as below. Then we see if the diff is correct and can approve.

DOCLING_GEN_TEST_DATA=1 uv run pytest tests/ -s -v

[Smeet23]

Hi @cau-git and @PeterStaar-IBM — pushed two follow-up commits:

1. chore: bump docling-core to 2.74.0 — updated uv.lock as requested
2. test: update markdown golden files for docling-core 2.74.0 table alignment — the bump caused 16 markdown golden files to diff due to tabulate now right-aligning numeric columns (a side effect of docling-core#588). Regenerated all .md golden files from the existing .json ground truth without re-running ML inference.

CI should be green now. Could you re-approve when you get a chance? Thanks!

[cau-git]

@Smeet23 I think the test diff looks right. It is a bit noisy because it also brings an update from handling tabulate output in, but no worry.

The part we're missing now is just the DCO signoff. As shown by the DCO bot please make one commit like this:

git commit --allow-empty -s -m "DCO Remediation Commit for Smeet23 <smeetagrawal2003@gmail.com>

I, Smeet23 <smeetagrawal2003@gmail.com>, hereby add my Signed-off-by to this commit: 0929fa81c9290617bb5769b2fd9145bea2a3bc9b
I, Smeet23 <smeetagrawal2003@gmail.com>, hereby add my Signed-off-by to this commit: eeed70c4e97b757ec5debadeed3502004b728117"
git push

FYI: If you let claude make commits, it will usually ignore the -s (signoff) flag and hence create unsigned commits.