fix(docx): Missing list items after numbered header (#2665) by emreclsr · Pull Request #2678 · docling-project/docling

emreclsr · 2025-11-25T10:42:57Z

Description

This commit fixes an issue where list items immediately following headings (especially numbered headings) were not being processed correctly in Word documents.

While working with Word document conversion, I encountered a similar issue to #2665 where list items after headings were missing from the output. This PR addresses the root cause of this problem.

Changes

Clear list history after headings to allow new lists to start
Reset level tracking when heading resets hierarchy
Reset level_at_new_list when a heading is added
Replace else block with explicit elif condition for new list sequences
- Only continue existing list if parent is actually a ListGroup
- Handle different numid or missing ListGroup parent by creating new list

Testing

Added test case test_list_items_after_numbered_heading to verify:

List items appear correctly after numbered headings
Heading has ListGroup as child
List group contains the expected list items
Document structure is properly maintained

All existing tests continue to pass. No groundtruth files were modified, indicating the fix addresses the bug without breaking existing functionality.

Related Issues

This fix may also resolve #2665 as it addresses the same underlying problem.

Checklist

Documentation has been updated, if necessary. (N/A - internal fix)
Examples have been added, if necessary. (N/A - bug fix)
Tests have been added, if necessary. Added test_list_items_after_numbered_heading

github-actions · 2025-11-25T10:43:08Z

✅ DCO Check Passed

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

dosubot · 2025-11-25T10:43:17Z

Related Documentation

Checked 4 published document(s) in 1 knowledge base(s). No updates required.

^{How did I do? Any feedback?}

mergify · 2025-11-25T10:43:34Z

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

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)(?:\(.+\))?(!)?:

codecov · 2025-11-26T16:38:05Z

Codecov Report

❌ Patch coverage is 88.40580% with 8 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
docling/backend/msword_backend.py	88.40%	8 Missing ⚠️

📢 Thoughts on this report? Let us know!

emreclsr · 2025-11-27T08:37:36Z

Description

This PR improves test coverage for the list-after-heading fix by adding test cases for enumerated (numbered) lists following headings, achieving 100% code coverage for the related changes.

Changes

Test Data

Extended list_after_num_headers.docx with enumerated list test case
- Added "Title 2" → "Sub Title 1" heading with numbered list items

Test Code

Enhanced test_list_items_after_numbered_heading to verify both:
- Bullet lists after numbered headings (existing)
- Enumerated lists after numbered headings (new)

Groundtruth Files

Updated .md, .itxt, and .json files to reflect new test content

mkhludnev · 2026-02-16T20:30:30Z

I've tried this fix on one .docx file it falls with

    def _add_list_item(
        self,
        *,
        doc: DoclingDocument,
        numid: int,
        ilevel: int,
        elements: list,
        is_numbered: bool = False,
    ) -> list[RefItem]:
....
        ):  # Open indented list
            for i in range(
                self.level_at_new_list + prev_indent + 1,
                self.level_at_new_list + ilevel + 1,
            ):
                list_gr1 = doc.add_list_group(
                    name="list",
>                   parent=self.parents[i - 1],
                           ^^^^^^^^^^^^^^^^^^^
                    content_layer=self.content_layer,
                )
E               KeyError: 18

docling/backend/msword_backend.py:1272: KeyError

sigh

emreclsr · 2026-02-17T09:23:02Z

@mkhludnev Thanks for testing could you share the .docx file (or a minimal reproducer) that triggers this KeyError? I'd like to debug and fix it.

ceberam · 2026-03-06T12:02:15Z

@emreclsr we recently merged this PR #3070 and it could be that it fixed the issue described in this conversation. Could you please try the current version in main and see if the issues are gone?

mkhludnev · 2026-03-06T17:52:01Z

@ceberam
I've got to my ill docx

(.venv)(base) ~/git/docling git:[main]
git log
commit b7815658d12390343669869a5065e80e5038369f (HEAD -> main, tag: v2.77.0, origin/main, origin/HEAD)
Author: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
Date:   Fri Mar 6 13:45:28 2026 +0000

    chore: bump version to 2.77.0 [skip ci]

I've checked out recently

uv pip install .
Resolved 112 packages in 607ms

launch script

converter = DocumentConverter()
result = converter.convert(source)

failure

Parent element of the list item is not a ListGroup. The list item will be ignored.
Parent element of the list item is not a ListGroup. The list item will be ignored.
Parent element of the list item is not a ListGroup. The list item will be ignored.
Parent element of the list item is not a ListGroup. The list item will be ignored.
Parent element of the list item is not a ListGroup. The list item will be ignored.
Traceback (most recent call last):
  File "/home/git/docling/docling/pipeline/base_pipeline.py", line 74, in execute
    conv_res = self._build_document(conv_res)
  File "/home/git/docling/docling/pipeline/simple_pipeline.py", line 40, in _build_document
    conv_res.document = conv_res.input._backend.convert()
                        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^
  File "/home/git/docling/docling/backend/msword_backend.py", line 168, in convert
    doc, _ = self._walk_linear(self.docx_obj.element.body, doc)
             ~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/git/docling/docling/backend/msword_backend.py", line 362, in _walk_linear
    te = self._handle_text_elements(element, doc)
  File "/home/git/docling/docling/backend/msword_backend.py", line 982, in _handle_text_elements
    li = self._add_list_item(
        doc=doc,
    ...<3 lines>...
        is_numbered=is_numbered,
    )
  File "/home/git/docling/docling/backend/msword_backend.py", line 1318, in _add_list_item
    parent=self.parents[i - 1],
           ~~~~~~~~~~~~^^^^^^^
KeyError: 18

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "/home/git/docling/docling/launch.py", line 8, in <module>
    result = converter.convert(source)
  File "/home/git/docling/.venv/lib/python3.13/site-packages/pydantic/_internal/_validate_call.py", line 39, in wrapper_function
    return wrapper(*args, **kwargs)
  File "/home/git/docling/.venv/lib/python3.13/site-packages/pydantic/_internal/_validate_call.py", line 136, in __call__
    res = self.__pydantic_validator__.validate_python(pydantic_core.ArgsKwargs(args, kwargs))
  File "/home/git/docling/docling/document_converter.py", line 388, in convert
    return next(all_res)
  File "/home/git/docling/docling/document_converter.py", line 447, in convert_all
    for conv_res in conv_res_iter:
                    ^^^^^^^^^^^^^
  File "/home/git/docling/docling/document_converter.py", line 564, in _convert
    for item in map(
                ~~~^
        process_func,
        ^^^^^^^^^^^^^
        input_batch,
        ^^^^^^^^^^^^
    ):
    ^
  File "/home/git/docling/docling/document_converter.py", line 611, in _process_document
    conv_res = self._execute_pipeline(in_doc, raises_on_error=raises_on_error)
  File "/home/git/docling/docling/document_converter.py", line 634, in _execute_pipeline
    conv_res = pipeline.execute(in_doc, raises_on_error=raises_on_error)
  File "/home/git/docling/docling/pipeline/base_pipeline.py", line 89, in execute
    raise RuntimeError(f"Pipeline {self.__class__.__name__} failed") from e
RuntimeError: Pipeline SimplePipeline failed

Process finished with exit code 1

ceberam · 2026-03-06T18:03:02Z

Thanks @mkhludnev . It seems we hit another edge case. We should apply some safeguards to avoid the type of error you shared, in any case. Can you share the docx document? (or a version that could be publicly shared).
I will check it in more detail next week and eventually try to reuse this PR.

mkhludnev · 2026-03-06T18:19:04Z

I noticed that the problematic item in Writer numbered as
2.7.8.1..
However Tika numbers it as 1.14.8.1 so, it's rather weird doc.
I don't feel like I'm able to share that one docx.

mergify · 2026-03-06T21:38:08Z

Merge Protections

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

🟢 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)(?:\(.+\))?(!)?:

emreclsr · 2026-03-06T21:46:27Z

To help demonstrate and validate the reported issue, I prepared a test Word document specifically designed to expose numbering edge cases with interleaved list sequences.

Test Document.docx

Results comparison:

Current main branch — parses the document as shown in main.md
Previous version of this PR — produced the output in pre-changes.md
After the latest changes — the document is parsed correctly as shown in after-changes.md

@mkhludnev Could you re-test with your document to confirm the issue is resolved on your end as well?

@ceberam If everything looks good, I'd appreciate your review and approval when you get a chance — happy to make any adjustments if needed.

mkhludnev · 2026-03-06T22:08:42Z

@emreclsr the failure I've posted above is fixed with your last commit. Thanks a lot.
@ceberam I quickly skim through the conversion output I noticed that the structure goes too deep, examine xml gives 4-5 level of nesting but processing by code main goes up to 18th - see exception above. So currently main code has unnecessary depth issue.

FWIW, list items numbers are still weird, but it's rather odd doc, I'm not even sure is it worth to bother about correct numbering and fix'em.

Summary

main - fixed lost of paragraph, but introduced exception,
fix(docx): Missing list items after numbered header (#2665) #2678 fixed exception and produced good enough result. I can't spot loosing content anymore.

Please proceed with #2678

Thank you so much, collegues!

mergify · 2026-03-07T05:38:43Z

Merge Protections

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

🟢 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)(?:\(.+\))?(!)?:

mkhludnev · 2026-03-07T20:10:03Z

injected-problem.docx
@ceberam here's the doc which fails

msword_backend.py", line 1318, in _add_list_item
    parent=self.parents[i - 1],
           ~~~~~~~~~~~~^^^^^^^
KeyError: 16

at main, but converted with only one warning with this patch.

I'm sure this doc is absolutely weird. Just opening it in Libre office Writer make convertible for main branch version. Also, after I replaced text nodes in document xml, it seems like numbered items have lost. So, it's not the best reproducer, but it let to check key error exception in main branch.

mergify · 2026-03-10T12:19:46Z

Merge Protections

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

🟢 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)(?:\(.+\))?(!)?:

mergify · 2026-03-13T12:18:13Z

Merge Protections

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

🟢 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)(?:\(.+\))?(!)?:

ceberam · 2026-03-16T16:37:16Z

@emreclsr could you please resolve the current conflict? Sorry about that, since this already happened while waiting for the review, but we'll try to address this PR ASAP.

mergify · 2026-03-16T16:51:16Z

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

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)(?:\(.+\))?(!)?:

emreclsr · 2026-03-16T16:55:59Z

@ceberam I've resolved the conflict and rebased the branch onto the latest main. If everything looks good, I'd appreciate it if we could get this merged. Happy to make any adjustments if needed.

tests/test_backend_msword.py

ceberam

Thanks @emreclsr for this new iteration and for discovering another issue.

I have checked the results of the new implementation on the test case and I saw a potential inconsistency. I highlighted it on the .itxt file because it is easier to explain, but they can be found in the Docling document serialization (JSON file). Could you please check?
Plus a very minor style comment.

docling/backend/msword_backend.py

ceberam · 2026-03-18T17:34:00Z

tests/data/groundtruth/docling_v2/unit_test_headers_numbered.docx.itxt

+            item-56 at level 6: list_item: Section A.1
+            item-57 at level 6: list: group list
+              item-58 at level 7: list_item: Detail A.1.1
+            item-59 at level 6: list: group list


Not sure if we should open a new group list. The item Hardware Constraints – Egde Case appears at the same level as Detail A.1.1, even though the marker goes to 2.3.1 from 1.1.1.

mergify · 2026-03-18T17:53:53Z

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

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)(?:\(.+\))?(!)?:

…hical markers Fixes incorrect numbering and missing items in DOCX documents that use multiple interleaved numbering sequences (numIds). Changes: * Reset sub-level counters in _get_list_counter when a parent level advances, preventing counter bleed-across (e.g. "4. Functional Requirements" now correctly renders as "1. Functional Requirements") * Add _build_enum_marker helper to produce hierarchical markers in "1.2.3." format instead of flat single-level counters * Fix anchor-based level calculation in new-sequence branch: use level_at_new_list + ilevel instead of _get_level() to correctly place items from a different numId at the right document level * Only set level_at_new_list in the else case (when None) to avoid corrupting the anchor when switching between interleaved numIds * Remove _reset_list_counters_for_new_sequence from new-sequence branch so that returning to a previously seen numId continues its counter (e.g. Appendix A=1, B=2, C=3 instead of A=1, B=1, C=1) Signed-off-by: Emre Çalışır <emrecalisir95@gmail.com>

Signed-off-by: Emre Çalışır <emrecalisir95@gmail.com>

…e reset helpers Adds test_list_counter_and_enum_marker covering helper methods introduced in the list numbering fix: counter increment, sub-level reset on parent advance, hierarchical marker building, and selective sequence reset. Signed-off-by: Emre Çalışır <emrecalisir95@gmail.com>

When Word creates a new numbering definition that continues from a previous list, it embeds start values in the abstractNum XML instead of reusing the same numId. Docling previously ignored these start values and always initialized counters from 1, producing incorrect markers like "1.1.1." instead of "2.3.1.". Changes: * Add _get_level_element helper to extract level XML from abstractNum, eliminating duplicated XML traversal in _is_numbered_list * Add _get_start_value to read w:start from the numbering definition * Initialize counters in _get_list_counter using start values * Use start values as fallback in _build_enum_marker for parent levels that have not been explicitly incremented Signed-off-by: Emre Çalışır <emrecalisir95@gmail.com>

…ered Extends the existing test document with an Appendix section that uses a different numId, followed by list items that resume the original numbering sequence with Word-embedded start values (e.g. 2.3.1.). Updates groundtruth files accordingly. Signed-off-by: Emre Çalışır <emrecalisir95@gmail.com>

Signed-off-by: Emre Çalışır <emrecalisir95@gmail.com>

ceberam added bug Something isn't working docx issue related to docx backend labels Nov 26, 2025

dosubot bot mentioned this pull request Feb 9, 2026

List items after numbered headings are ignored (regression from PR #2665 #2967

Closed

emreclsr force-pushed the fix/msword-list-items-after-heading branch from 1b1e05d to 8154490 Compare March 6, 2026 21:37

ceberam self-requested a review March 10, 2026 12:19

ceberam self-assigned this Mar 10, 2026

emreclsr force-pushed the fix/msword-list-items-after-heading branch from 3a08432 to bcf17c2 Compare March 14, 2026 07:04

emreclsr force-pushed the fix/msword-list-items-after-heading branch from bcf17c2 to fe7ee9d Compare March 16, 2026 16:50

ceberam requested changes Mar 16, 2026

View reviewed changes

tests/test_backend_msword.py Show resolved Hide resolved

ceberam requested changes Mar 18, 2026

View reviewed changes

emreclsr added 6 commits March 19, 2026 17:20

style(docx): apply Ruff formatting to msword_backend

2ae1b25

Signed-off-by: Emre Çalışır <emrecalisir95@gmail.com>

style(docx): add return type annotation to _get_level_element

0777f36

Signed-off-by: Emre Çalışır <emrecalisir95@gmail.com>

emreclsr force-pushed the fix/msword-list-items-after-heading branch from b49df92 to 0777f36 Compare March 19, 2026 14:26

Conversation

emreclsr commented Nov 25, 2025

Description

Changes

Testing

Related Issues

Checklist

Uh oh!

github-actions bot commented Nov 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dosubot bot commented Nov 25, 2025

Uh oh!

mergify bot commented Nov 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merge Protections

🔴 Require two reviewer for test updates

🟢 Enforce conventional commit

Uh oh!

codecov bot commented Nov 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

emreclsr commented Nov 27, 2025

Description

Changes

Test Data

Test Code

Groundtruth Files

Uh oh!

mkhludnev commented Feb 16, 2026

Uh oh!

emreclsr commented Feb 17, 2026

Uh oh!

ceberam commented Mar 6, 2026

Uh oh!

mkhludnev commented Mar 6, 2026

Uh oh!

ceberam commented Mar 6, 2026

Uh oh!

mkhludnev commented Mar 6, 2026

Uh oh!

mergify bot commented Mar 6, 2026

Merge Protections

🟢 Enforce conventional commit

Uh oh!

emreclsr commented Mar 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mkhludnev commented Mar 6, 2026

Summary

Uh oh!

mergify bot commented Mar 7, 2026

Merge Protections

🟢 Enforce conventional commit

Uh oh!

mkhludnev commented Mar 7, 2026

Uh oh!

mergify bot commented Mar 10, 2026

Merge Protections

🟢 Enforce conventional commit

Uh oh!

mergify bot commented Mar 13, 2026

Merge Protections

🟢 Enforce conventional commit

Uh oh!

ceberam commented Mar 16, 2026

Uh oh!

mergify bot commented Mar 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merge Protections

🔴 Require two reviewer for test updates

🟢 Enforce conventional commit

Uh oh!

emreclsr commented Mar 16, 2026

Uh oh!

Uh oh!

ceberam left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Nov 25, 2025 •

edited

Loading

mergify bot commented Nov 25, 2025 •

edited

Loading

codecov bot commented Nov 26, 2025 •

edited

Loading

emreclsr commented Mar 6, 2026 •

edited

Loading

mergify bot commented Mar 16, 2026 •

edited

Loading