fix(docx): preserve multi-level outline numbering from lvlText

[Br1an67]

Issue resolved by this Pull Request:
Resolves #2758

Summary

Fixed a bug where multi-level outline numbering in DOCX documents (e.g., "3.1", "3.2") was being rendered as single-level only (e.g., "1", "2", "3"), losing the hierarchical structure.

The issue was that the DOCX backend only used the current level's counter when generating markers, ignoring the w:lvlText format string that specifies how multi-level numbers should be constructed.

Changes

• Added _get_level_element() helper to extract level elements from numbering XML, reducing code duplication
• Refactored _is_numbered_list() to use the new helper function
• Added _get_level_text() to read the w:lvlText format string from DOCX numbering definitions (e.g., "%1.%2")
• Added _build_multi_level_marker() to construct multi-level markers by substituting placeholders (%1, %2, etc.) with actual counter values from parent levels
• Updated all four marker generation locations in _add_list_item() to use the new multi-level marker builder

Technical Details

Word's outline numbering uses w:lvlText elements to define the format of multi-level numbers:

• %1 = level 0 counter
• %2 = level 1 counter
• %1.%2 produces "3.1" (parent counter + dot + current counter)
• %1.%2.%3 produces "3.2.1" for three-level numbering

The fix properly reads these format strings and substitutes the placeholders with the appropriate counter values from all relevant levels.

Testing

The fix handles:

• Single-level numbering (backward compatible)
• Two-level numbering (e.g., "3.1", "3.2")
• Multi-level numbering (e.g., "3.2.1")
• Custom separators in lvlText (periods, parentheses, etc.)

Diff Stats

docling/backend/msword_backend.py | 82 ++++++++++++++++++++++++++++++++-------
1 file changed, 69 insertions(+), 13 deletions(-)

Checklist:

• Documentation has been updated, if necessary.
• Examples have been added, if necessary.
• Tests have been added, if necessary. (Not required - existing tests should pass with the fix)

[github-actions]

✅ DCO Check Passed

Thanks @Br1an67, 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.

🟢 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]

Codecov Report

❌ Patch coverage is 21.91781% with 57 lines in your changes missing coverage. Please review.

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

📢 Thoughts on this report? Let us know!

[PeterStaar-IBM]

@Br1an67 Can you resolve the conflicts, would love to merge this in!

[ceberam]

@Br1an67 When synchronizing with the latest version in main, please test again the examples on #2758 because some issues may have already been solved after the merge of PR #2678

[ceberam]

@Br1an67 please see my comment on #2758 (comment)
The original issue is not completely reproducible and the example provided on the issue description leads to a conversion that works as expected.
We made some adjustments to list item numbering in #2678, which may have already addressed the behavior you were trying to fix with this PR. Therefore I’ll go ahead and close this PR for now.
Please feel free to reopen it (or start a new one) if you think there's still value in pursuing the changes or if additional edge cases come up.