Word never stores the list numbers you see — a DOCX converter has to run a numbering engine

A law firm sent the reporter a 60-page contract to convert, but every cross-reference was off by one section. The text referenced clauses 6.3, 6.4, and so on, while the headings pointed to seemingly different sections. This discrepancy led the reporter to question the integrity of the document. After encountering the issue in three other files, the reporter realized that list numbers in DOCX files are not stored but computed at render time.

A numbered paragraph contains only the `w:numPr` with a `numId` and a nesting level. The visible number is generated by Word's numbering engine using the abstract numbering definition in the `numbering.xml`. This engine handles various formatting, start values, restart rules, and per-instance overrides. The reporter's first converter simply counted paragraphs and incremented digits, but this approach failed to account for legal formatting requirements like (a), (iv), or decimal-within-upper-level numbering.

To accurately render list numbers, the reporter implemented the sequence resolution rules from ECMA-376, including one counter per level, resetting deeper levels when a higher one increments, applying startOverride per numbering instance, and formatting every number through the level's pattern. This fix ensured that heading numbers matched Word's display exactly.

To verify the conversion process, the reporter used a regression test: converting the file, exporting the same file to PDF from Word, and diffing just the clause headings. Any drift indicated a bug in the conversion process. The key takeaway is that list numbers in DOCX are a virtual layer, computed rather than stored. If a converter renders lists as bullets or renumbers with its own logic, quoted clause references in the body text may point to the wrong clause.

The reporter now incorporates this numbering engine into their DOCX-to-Markdown API, ensuring that cross-references remain intact during conversion.