.DOCX File Format – Numbering and lists

Office Open XML Document

WordprocessingML has no list element. A list is an ordinary run of paragraphs that each name a numbering definition and a level in w:numPr. The definitions are in word/numbering.xml, reached by the main document’s numbering relationship.

In a paragraph

<w:p>
  <w:pPr>
    <w:numPr>
      <w:ilvl w:val="0"/>
      <w:numId w:val="1"/>
    </w:numPr>
  </w:pPr>
  <w:r><w:t>A list item</w:t></w:r>
</w:p>
A numId of 0 means no list, which is how a style's list is turned off for one paragraph.

A paragraph style can carry w:numPr too, so that every paragraph in the style is numbered; this is how numbered headings work. In that case the level comes from the numbering definition’s level that names the style in w:pStyle.

The two layers

There are two layers. A w:abstractNum defines the appearance of up to nine levels. A w:num is an instance of a definition that paragraphs refer to. Several w:num can share one abstract definition.

<w:numbering xmlns:w="…">
  <w:abstractNum w:abstractNumId="0">
    <w:multiLevelType w:val="hybridMultilevel"/>
    <w:lvl w:ilvl="0">
      <w:start w:val="1"/>
      <w:numFmt w:val="decimal"/>
      <w:lvlText w:val="%1."/>
      <w:lvlJc w:val="left"/>
      <w:pPr><w:ind w:left="720" w:hanging="360"/></w:pPr>
    </w:lvl>
    <w:lvl w:ilvl="1">
      <w:start w:val="1"/>
      <w:numFmt w:val="lowerLetter"/>
      <w:lvlText w:val="%2."/>
    </w:lvl>
  </w:abstractNum>
  <w:num w:numId="1">
    <w:abstractNumId w:val="0"/>
  </w:num>
</w:numbering>
One abstract definition and one instance.

A level: w:lvl

ElementMeaning
w:startThe first number at this level.
w:numFmtThe number format. Common values: decimal, decimalZero, lowerLetter, upperLetter, lowerRoman, upperRoman, bullet, none. There are many more for other numbering systems.
w:lvlTextThe label: %1 is level 0’s number, %2 level 1’s and so on, so %1.%2 gives “2.1”. For a bullet, it is the bullet character, often in a symbol font with a private-use code.
w:lvlJcAlignment of the label.
w:pStyleThe paragraph style tied to this level.
w:suffWhat follows the number: tab (the default), space or nothing.
w:lvlRestartThe level whose increase restarts this one.
w:isLglShow all the level’s numbers as decimals, as in legal numbering.
w:pPr, w:rPrIndents for the level, and formatting of the label.

How numbers are counted

Each level keeps a counter. An item at a level adds one to that level’s counter and resets the counters of the deeper levels, so a new 1. under a following 2. restarts its sub-items. Word counts per list, which is why continuing a list only needs the same w:numId; a w:num sharing an abstract definition continues the same counters unless it restarts them.

A w:num can change this with w:lvlOverride: w:startOverride restarts a level from a new number, and a w:lvl inside it replaces the level’s definition.

Paragraph style lists also use w:styleLink and w:numStyleLink: an abstract definition can be named by a numbering style, and others can point to it through that style.