Skip to content

fix: preserve DOCX heading numbering - #5270

Open
lvhua6352 wants to merge 1 commit into
opendatalab:masterfrom
lvhua6352:fix/docx-heading-numbering-squashed
Open

fix: preserve DOCX heading numbering#5270
lvhua6352 wants to merge 1 commit into
opendatalab:masterfrom
lvhua6352:fix/docx-heading-numbering-squashed

Conversation

@lvhua6352

@lvhua6352 lvhua6352 commented Jul 15, 2026

Copy link
Copy Markdown

Motivation

DOCX heading outline levels and Word numbering levels represent different concepts.

For example, a paragraph can have:

  • outlineLvl=1, meaning it is a semantic level-2 heading and should render as ##.
  • numId=3, ilvl=0, and lvlText=%1., meaning it uses the first numbering level and should display 1., 2., etc.

Previously, the DOCX converter only preserved the semantic heading level. The middle-JSON conversion then reconstructed the section number from level=2, incorrectly producing 1.1, 1.2, etc.
image

This PR preserves the heading level while deriving the displayed section number from the actual Word numbering definition.

Modification

  • Generate an explicit section_number for numbered DOCX Heading blocks.
  • Resolve numbering rules using numId and ilvl from word/numbering.xml.
  • Reuse the existing Word list counters and configured start values.
  • Render %1 to %9 placeholders from lvlText while preserving punctuation.
  • Propagate section_number through the Office MagicModel.
  • Prefer an explicit DOCX section_number during middle-JSON conversion.
  • Keep the existing level-based section counter as a compatibility fallback when no explicit number is provided.
  • Add an in-memory synthetic DOCX regression test without relying on external documents or business-specific content.
  • Add a compatibility test for legacy Office title blocks without an explicit section_number.
  • Include the new regression test in the configured coverage command.
  • Add comments and a method docstring describing the numbering resolution process.

BC-breaking (Optional)

No backward-incompatible changes are introduced.

section_number was already used by the Office middle-JSON and Markdown rendering code. This PR only provides the existing field earlier in the DOCX conversion pipeline and preserves it through MagicModel.

Inputs without an explicit section_number continue to use the existing level-based numbering fallback. The additional field in DOCX model output is additive and does not change the existing public API.

Use cases (Optional)

This fixes automatically numbered DOCX headings whose semantic outline level differs from their numbering level.

Example:

  • Semantic heading level: outlineLvl=1 → Markdown ##
  • Word numbering level: ilvl=0, lvlText=%1.1., 2.

Before:

## 1.1 Virtual heading A
## 1.2 Virtual heading B

After:

## 1. Virtual heading A
## 2. Virtual heading B

Checklist

Before PR:

  • Pre-commit or other linting tools are used to fix the potential lint issues.
  • Bug fixes are fully covered by unit tests, and a synthetic case reproducing the issue has been added.
  • The modification is covered by focused unit tests, including legacy fallback behavior.
  • The relevant method docstring and inline comments have been updated. No public documentation change is required.

After PR:

  • No downstream validation is required because this change is additive and preserves the existing fallback behavior.
  • CLA has been signed and all committers have signed the CLA in this PR.

@dosubot dosubot Bot added size:M This PR changes 30-99 lines, ignoring generated files. bug Something isn't working labels Jul 15, 2026
@github-actions

github-actions Bot commented Jul 15, 2026

Copy link
Copy Markdown
Contributor

All contributors have signed the CLA ✍️ ✅
Posted by the CLA Assistant Lite bot.

@lvhua6352

Copy link
Copy Markdown
Author

I have read the CLA Document and I hereby sign the CLA

github-actions Bot added a commit that referenced this pull request Jul 15, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working size:M This PR changes 30-99 lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant