Numbered headings in Word documents appear as list items

[mattmalcher]

First off, thank you for docling! <3

A standard representation, maintaining context and hierarchy, for content across multiple formats, with an MIT licence is just super! Fan of features like the hybrid text chunker.

Bug

Lots of long technical documents use multilevel lists in word to have numbered sections.

These documents sometimes also include numbered paragraphs.

At the moment, in the word backend, docling checks to see if an item is a list item and handles that case separately, before checking to see if it is a heading.

see:

docling/docling/backend/msword_backend.py

Lines 244 to 297 in 3bb3bf5

	if numid is not None and ilevel is not None:
	self.add_listitem(
	element,
	docx_obj,
	doc,
	p_style_id,
	p_level,
	numid,
	ilevel,
	text,
	is_numbered,
	)
	self.update_history(p_style_id, p_level, numid, ilevel)
	return
	elif numid is None and self.prev_numid() is not None: # Close list
	for key, val in self.parents.items():
	if key >= self.level_at_new_list:
	self.parents[key] = None
	self.level = self.level_at_new_list - 1
	self.level_at_new_list = None
	if p_style_id in ["Title"]:
	for key, val in self.parents.items():
	self.parents[key] = None
	self.parents[0] = doc.add_text(
	parent=None, label=DocItemLabel.TITLE, text=text
	)
	elif "Heading" in p_style_id:
	self.add_header(element, docx_obj, doc, p_style_id, p_level, text)
	elif p_style_id in [
	"Paragraph",
	"Normal",
	"Subtitle",
	"Author",
	"DefaultText",
	"ListParagraph",
	"ListBullet",
	"Quote",
	]:
	level = self.get_level()
	doc.add_text(
	label=DocItemLabel.PARAGRAPH, parent=self.parents[level - 1], text=text
	)
	else:
	# Text style names can, and will have, not only default values but user values too
	# hence we treat all other labels as pure text
	level = self.get_level()
	doc.add_text(
	label=DocItemLabel.PARAGRAPH, parent=self.parents[level - 1], text=text
	)
	self.update_history(p_style_id, p_level, numid, ilevel)
	return

So paras/tags which are both a list item and a heading just get treated as a list item. It would probably be more useful to treat them as a heading, and convert the list index into plaintext.

I have had a go at adding a failing unit test, by adding a modified copy of unit_test_headers.docx and the expected ground truths for this case in a fork here: a544360

Have also attached the same example to this issue: unit_test_headers_numbered.docx

Current output:

# Test Document

- Section 1

Paragraph 1.1

Paragraph 1.2

Expected output:

# Test Document
## 1. Section 1

Paragraph 1.1

Paragraph 1.2

Steps to reproduce

Parse a word document with numbered headings like: unit_test_headers_numbered.docx

Docling version

Docling version: 2.12.0
Docling Core version: 2.9.0
Docling IBM Models version: 3.1.0
Docling Parse version: 3.0.0

Python version

Python 3.12.3

[mattmalcher]

I think there is also a related issue where sometimes the first item of a list that is within a numbered heading section will go missing.

If useful I can create a failing test for that too?

[cau-git]

@mattmalcher If you can provide us with failing tests that would be very helpful for checking, thanks.

[mattmalcher]

I have added two failing tests, with ground truths in a branch in a fork here: https://github.com/mattmalcher/docling/tree/issue_612_docx_numbered_headings

For the issue with text going missing where numbered headings are involved:

Original Document

Expected (Markdown)

Actual (Markdown)
Note that heading 1.2 here has gone altogether!