{
  "id": 13263954,
  "title": "Word never stores the list numbers you see — a DOCX converter has to run a numbering engine",
  "url": "https://urgent.news/2026/10/10/word-never-stores-the-list-numbers-you-see-a-docx-converter-has-to",
  "topic": "tech",
  "section": "Tech",
  "published": "2026-10-10T00:07:25.000Z",
  "source": {
    "name": "Dev.to",
    "slug": "dev-to",
    "url": "https://dev.to/imapphelp/word-never-stores-the-list-numbers-you-see-a-docx-converter-has-to-run-a-numbering-engine-1cf2"
  },
  "original_language": "en",
  "account": "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.",
  "summary": "A law firm sent me a 60-page contract to convert, and by section 7 every cross-reference was off by one. The text said \"as set out in clause 6.3\" while the heading it pointed to read \"6.4\". I assumed a typo in the source document — until the same drift showed up in three other files that week. The root cause changed how I think about Word documents: the numbers you see in a DOCX are not stored…",
  "key_points": [
    "List numbers in DOCX files are not stored, only computed at render time.",
    "Word's numbering engine handles formatting, start values, and overrides.",
    "Accurate conversion requires implementing ECMA-376 sequence resolution rules."
  ],
  "editors_take": "Implementing a numbering engine that accurately replicates Word's display is crucial for DOCX converters to maintain correct cross-references and quoted clause references during conversion to other formats.",
  "illustration": null,
  "coverage": {
    "outlets": 1,
    "also_reported_by": []
  },
  "ai_generated": true,
  "disclaimer": "Summaries, key points and the editor’s take are written by software from other outlets’ reporting and may contain errors — always check the linked original."
}