Incorrect list hierarchy when converting DOCX with nested numbered lists

[zmdo]

When converting a DOCX document that contains nested lists with specific numbering styles commonly used in documents, the resulting HTML loses the correct hierarchy. The nested items are lifted to the top level instead of remaining nested.

Example

Original content in DOCX :

(1) Level 1 heading 1
(2) Level 1 heading 2
    a) Subheading a of heading 2
    b) Subheading b of heading 2
        i. Subheading i of b
        ii. Subheading ii of b

After conversion with mammoth, the output HTML becomes:

<ol>
  <li>Level 1 heading 1</li>
  <li>Level 1 heading 2
    <ol>
      <li>Subheading a of heading 2</li>
      <li>Subheading b of heading 2</li>
    </ol>
  </li>
  <li>Subheading i of b</li>
  <li>Subheading ii of b</li>
</ol>

As you can see, the last two items (Subheading i of b and Subheading ii of b) are incorrectly placed as top-level list items instead of being nested under b) Subheading b of heading 2. The intended hierarchy should be:

- (1) Level 1 heading 1
- (2) Level 1 heading 2
  - a) Subheading a of heading 2
  - b) Subheading b of heading 2
    - i. Subheading i of b
    - ii. Subheading ii of b

I do not care about preserving the exact numbering styles (i.e., whether they are rendered as (1), a), i. etc.), but the list hierarchy must be maintained.

Steps to Reproduce

1. Create a DOCX file with the following content using Word's built-in list numbering:
   • First level: numbered as (1), (2), …
   • Second level: numbered as a), b), …
   • Third level: numbered as i., ii., …
2. Apply the numbering to the text exactly as shown in the example above.
3. Run mammoth to convert the DOCX to HTML.
4. Observe the output.

Expected Behavior

The HTML should reflect the correct nesting:

<ol>
  <li>Level 1 heading 1</li>
  <li>Level 1 heading 2
    <ol>
      <li>Subheading a of heading 2</li>
      <li>Subheading b of heading 2
        <ol>
          <li>Subheading i of b</li>
          <li>Subheading ii of b</li>
        </ol>
      </li>
    </ol>
  </li>
</ol>

Actual Behavior

The third-level items are lifted out of their parent list and become top-level items after the second-level list closes.

Thank you for looking into this!

[mwilliamson]

Could you provide a minimal example document demonstrating the issue, along with the expected HTML and the actual HTML?

[zmdo]

Could you provide a minimal example document demonstrating the issue, along with the expected HTML and the actual HTML?

Minimal Example Docx : order-error-example.docx

Python Code :

import mammoth

if __name__ == '__main__':
    with open("order-error-example.docx", "rb") as docx_stream:
        result = mammoth.convert_to_html(
            fileobj=docx_stream,
            ignore_empty_paragraphs=False
        )

    print(result.value)

File: converter.py

Output HTML:

<ol><li>Level 1 heading 1</li><li>Level 1 heading 2<ol><li>Subheading a of heading 2</li><li>Subheading b of heading 2</li></ol></li><li>Subheading i of heading b</li><li>Subheading ii of heading b</li></ol>

File: output.html

Expected HTML:

<ol>
  <li>Level 1 heading 1</li>
  <li>Level 1 heading 2
    <ol>
      <li>Subheading a of heading 2</li>
      <li>Subheading b of heading 2
        <ol>
          <li>Subheading i of b</li>
          <li>Subheading ii of b</li>
        </ol>
      </li>
    </ol>
  </li>
</ol>

File: expected.html

---

Thank you for taking the time to look into this—I've just added the case file, and please let me know if there's anything else you need.

[mwilliamson]

The problem is that so far as the document itself is concerned, the final two list items are top level list items that happen to have more indentation, rather than being nested list items.

I don't have a copy of Microsoft Word to hand, but I can see this in LibreOffice by placing the caret inside (say) the fifth item and seeing that the "Decrease Indent" option is disabled. This is the same as the first and second list items (also top-level list items), whereas the third and fourth list items do have the "Decrease Indent" option enabled.

If you want Mammoth to treat the final two list items as being children of the fourth list item, you'll need to mark them up as third-level list items.

[zmdo]

Thank you very much for your explanation. So essentially, this issue stems from the formatting of the lists in the provided docx file itself, rather than being a problem with Mammoth's parsing. In other words, I cannot change the list level simply by adjusting indentation; instead, I must set the list level directly through the list's own hierarchy settings.

[mwilliamson]

Yes, exactly. I'll close this since I don't think there's anything for Mammoth to do here.