--number-sections for docx: option to use native Word numbering instead of text prefixes

[PascalThuet]

Summary

When using --number-sections with docx output, Pandoc inserts section numbers as text prefixes (e.g., "1.1 Heading"). This works, but prevents Word's native features (automatic renumbering, TOC field codes, outline view) from functioning correctly.

Request: Add an option to generate native Word multilevel numbering via numbering.xml instead of text prefixes.

Current behavior

pandoc -f markdown -t docx --number-sections input.md -o output.docx

Produces headings like:

<w:p>
  <w:pPr><w:pStyle w:val="Heading1"/></w:pPr>
  <w:r><w:t>1</w:t></w:r>
  <w:r><w:t> </w:t></w:r>
  <w:r><w:t>Introduction</w:t></w:r>
</w:p>

The number "1" is static text.

Desired behavior (with new option)

pandoc -f markdown -t docx --number-sections -t docx+native_numbering input.md -o output.docx

Would produce:

<w:p>
  <w:pPr>
    <w:pStyle w:val="Heading1"/>
    <w:numPr>
      <w:ilvl w:val="0"/>
      <w:numId w:val="1"/>
    </w:numPr>
  </w:pPr>
  <w:r><w:t>Introduction</w:t></w:r>
</w:p>

With corresponding abstractNum in numbering.xml:

<w:abstractNum w:abstractNumId="0">
  <w:multiLevelType w:val="multilevel"/>
  <w:lvl w:ilvl="0">
    <w:start w:val="1"/>
    <w:numFmt w:val="decimal"/>
    <w:lvlText w:val="%1."/>
    <w:pStyle w:val="Heading1"/>
  </w:lvl>
  <w:lvl w:ilvl="1">
    <w:start w:val="1"/>
    <w:numFmt w:val="decimal"/>
    <w:lvlText w:val="%1.%2."/>
    <w:pStyle w:val="Heading2"/>
  </w:lvl>
  <!-- ... -->
</w:abstractNum>

Use case

When generating technical documentation for stakeholders who edit in Word:

• They need to insert/reorder sections without manual renumbering
• Word's "Update Table of Contents" should work with field codes
• Outline view should show proper hierarchy

Currently, any structural edit requires manual renumbering of all subsequent sections.

Proposed solution

Reuse the existing native_numbering extension (already implemented for figures/tables in #7499).

When docx+native_numbering is enabled and --number-sections is used:

1. Add a multilevel abstractNum to numbering.xml (levels 0-8 for Heading 1-9)
2. Apply numPr to heading paragraphs instead of inserting text prefixes
3. Optionally: respect numbering format from reference.docx if present

This is opt-in (extension disabled by default), so no breaking change.

Minimal implementation scope

The smallest useful PR would:

1. Only handle Heading 1-3 (most common)
2. Use hardcoded format %1., %1.%2., %1.%2.%3.
3. Ignore reference.docx numbering (future enhancement)

This keeps the change small and reviewable.

Related issues

• docx and --number-sections #1413 - Original request for --number-sections in docx (closed 2020, implemented as text)
• support -native_numbering for docx #7499 - native_numbering extension for figures/tables (implemented)
• DOCX heading number format #2582 - Request to copy numbering.xml from reference.docx

Environment

Pandoc 3.8.3
macOS / Windows / Linux