From aa6b1ff2731e7d496b51f2f16c3ee5f0fe854b1e Mon Sep 17 00:00:00 2001 From: Lijia Zhang <10111038+org30h@users.noreply.github.com> Date: Thu, 20 Aug 2026 22:50:18 -0700 Subject: [PATCH] fix: nest DOCX sub-lists that Word stores as a separate numbering definition Word can express a nested list either as a deeper w:ilvl within the parent's w:numId, or as a new w:numId at w:ilvl 0 that is set apart only by its indentation. Both render identically in Word, but mammoth derives nesting from w:ilvl alone, so the second form was flattened into the parent list and its items were renumbered as siblings. Extend the existing pre_process_docx step to resolve each level's effective indentation from numbering.xml and walk the document tracking the open list levels, so nesting implied by indentation is restored before mammoth reads the file. Within one w:numId the declared w:ilvl stays authoritative, since some numbering definitions give several levels the same indentation. Indentation only ever adds nesting that the declared levels missed and never removes nesting a document states outright, which leaves documents that already convert correctly untouched. Remapped paragraphs are pointed at a generated w:abstractNum carrying their original w:numFmt, so a bulleted sub-list is not silently converted into a numbered one, and depth is capped at the last level mammoth's default style map defines. Fixes #2323 --- .../converter_utils/docx/pre_process.py | 318 ++++++++++++++++++ packages/markitdown/tests/test_docx_lists.py | 189 +++++++++++ .../tests/test_files/multilevel_lists.docx | Bin 0 -> 15305 bytes 3 files changed, 507 insertions(+) create mode 100644 packages/markitdown/tests/test_docx_lists.py create mode 100644 packages/markitdown/tests/test_files/multilevel_lists.docx diff --git a/packages/markitdown/src/markitdown/converter_utils/docx/pre_process.py b/packages/markitdown/src/markitdown/converter_utils/docx/pre_process.py index c6dc303414..404f669f85 100644 --- a/packages/markitdown/src/markitdown/converter_utils/docx/pre_process.py +++ b/packages/markitdown/src/markitdown/converter_utils/docx/pre_process.py @@ -247,6 +247,309 @@ def _pre_process_styles(content: bytes) -> bytes: return etree.tostring(root.getroottree(), encoding="utf-8", xml_declaration=True) +W_NS = "http://schemas.openxmlformats.org/wordprocessingml/2006/main" + +# mammoth's default style map only defines list nesting up to five levels (see +# "p:ordered-list(5)" in mammoth.options). A paragraph promoted past the last +# mapped level matches no rule at all and drops out of the list entirely, so +# nesting is capped at the deepest level mammoth can still represent. +MAX_LIST_LEVEL = 4 + +# Word's default indentation step between consecutive list levels, in twips. +# Used only when a level definition carries no explicit indentation. +DEFAULT_LEVEL_INDENT = 720 + + +def _read_indent(element: Tag | None) -> int | None: + """ + Reads the left indentation (in twips) from the "w:ind" child of an element. + + Args: + element (Tag | None): The element whose "w:ind" child should be read. + + Returns: + int | None: The left indentation, or None if it is absent or malformed. + """ + if element is None: + return None + ind = element.find("ind", recursive=False) + if ind is None: + return None + # "w:start" is the ISO/strict equivalent of the transitional "w:left". + for attribute in ("w:left", "w:start"): + value = ind.get(attribute) + if value is not None: + try: + return int(value) + except ValueError: + pass + return None + + +def _read_numbering_definitions(numbering_soup: BeautifulSoup) -> dict: + """ + Resolves every "w:num" in numbering.xml to its per-level indentation and format. + + Args: + numbering_soup (BeautifulSoup): The parsed numbering.xml. + + Returns: + dict: Maps num_id -> level_index -> {"indent": int | None, "fmt": str | None}. + """ + abstract_nums = {} + for abstract_num in numbering_soup.find_all("abstractNum"): + levels = {} + for lvl in abstract_num.find_all("lvl"): + num_fmt = lvl.find("numFmt") + levels[lvl.get("w:ilvl")] = { + "indent": _read_indent(lvl.find("pPr")), + "fmt": num_fmt.get("w:val") if num_fmt is not None else None, + } + abstract_nums[abstract_num.get("w:abstractNumId")] = levels + + nums = {} + for num in numbering_soup.find_all("num"): + abstract_num_id = num.find("abstractNumId") + if abstract_num_id is None: + continue + levels = dict(abstract_nums.get(abstract_num_id.get("w:val"), {})) + # A "w:lvlOverride" replaces the inherited definition for a single level. + for override in num.find_all("lvlOverride"): + lvl = override.find("lvl") + if lvl is None: + continue + num_fmt = lvl.find("numFmt") + level_index = lvl.get("w:ilvl", override.get("w:ilvl")) + levels[level_index] = { + "indent": _read_indent(lvl.find("pPr")), + "fmt": num_fmt.get("w:val") if num_fmt is not None else None, + } + nums[num.get("w:numId")] = levels + return nums + + +def _iter_list_paragraphs(document_soup: BeautifulSoup): + """ + Yields each paragraph of a document alongside its numbering reference. + + Args: + document_soup (BeautifulSoup): The parsed document.xml. + + Yields: + tuple: (paragraph, ilvl_tag, num_id_tag). The tags are None for any + paragraph that does not carry direct numbering. + """ + for paragraph in document_soup.find_all("p"): + p_pr = paragraph.find("pPr", recursive=False) + num_pr = p_pr.find("numPr", recursive=False) if p_pr is not None else None + if num_pr is None: + yield paragraph, None, None + continue + ilvl_tag = num_pr.find("ilvl", recursive=False) + num_id_tag = num_pr.find("numId", recursive=False) + # A "w:numId" of 0 explicitly removes numbering from the paragraph. + if num_id_tag is None or num_id_tag.get("w:val") == "0": + yield paragraph, None, None + continue + yield paragraph, ilvl_tag, num_id_tag + + +def _is_parent_of(candidate: dict, item: dict) -> bool: + """ + Determines whether an open list level is an ancestor of the current item. + + Within a single "w:numId" the declared "w:ilvl" is authoritative, because + Word uses it directly and levels of one list are directly comparable. + Across different "w:numId" values the levels are unrelated, so only the + rendered indentation can establish which list is nested inside the other. + + Args: + candidate (dict): An open level from the stack. + item (dict): The list paragraph being placed. + + Returns: + bool: True if candidate is strictly shallower than item. + """ + if candidate["num_id"] == item["num_id"]: + return candidate["ilvl"] < item["ilvl"] + return candidate["indent"] < item["indent"] + + +def _resolve_list_depths(document_soup: BeautifulSoup, numbering: dict) -> list: + """ + Computes the true nesting depth of every numbered paragraph in a document. + + Word represents a nested list in either of two ways: as a deeper "w:ilvl" + within the parent's "w:numId", or as an entirely new "w:numId" at + "w:ilvl" 0 that is simply indented further. Both render identically, but + mammoth derives nesting from "w:ilvl" alone and so flattens the second + form. Walking the document while tracking the open levels recovers the + nesting that indentation implies. + + Args: + document_soup (BeautifulSoup): The parsed document.xml. + numbering (dict): Numbering definitions from _read_numbering_definitions. + + Returns: + list: One (paragraph, ilvl_tag, num_id_tag, depth) tuple per paragraph + whose depth differs from its declared level. + """ + remappings = [] + stack: list[dict] = [] + + for paragraph, ilvl_tag, num_id_tag in _iter_list_paragraphs(document_soup): + if num_id_tag is None: + # Body text interrupts the surrounding list, exactly as it does for + # mammoth, so no level stays open across it. + stack.clear() + continue + + num_id = num_id_tag.get("w:val") + # A missing "w:ilvl" means the first level. + raw_ilvl = ilvl_tag.get("w:val") if ilvl_tag is not None else "0" + try: + ilvl = int(raw_ilvl) + except (TypeError, ValueError): + ilvl = 0 + + level = numbering.get(num_id, {}).get(str(ilvl), {}) + indent = level.get("indent") + if indent is None: + indent = ilvl * DEFAULT_LEVEL_INDENT + # Indentation applied directly to the paragraph overrides the level's. + paragraph_indent = _read_indent(paragraph.find("pPr", recursive=False)) + if paragraph_indent is not None: + indent = paragraph_indent + + item = {"num_id": num_id, "ilvl": ilvl, "indent": indent} + while stack and not _is_parent_of(stack[-1], item): + stack.pop() + + implied_depth = stack[-1]["depth"] + 1 if stack else 0 + # Indentation is only ever used to reveal nesting the declared levels + # missed, never to remove nesting a document states outright. This + # keeps documents that mammoth already handles correctly untouched. + depth = min(max(implied_depth, ilvl), MAX_LIST_LEVEL) + + item["depth"] = depth + stack.append(item) + + if depth != ilvl: + remappings.append((paragraph, ilvl_tag, num_id_tag, depth)) + + return remappings + + +def _apply_list_depths( + document_soup: BeautifulSoup, numbering_soup: BeautifulSoup, remappings: list +) -> None: + """ + Rewrites paragraphs whose nesting depth was mis-declared, in place. + + Simply raising "w:ilvl" would make the paragraph resolve against whatever + unrelated level its numbering happens to define at that index, which can + silently flip an ordered list to a bulleted one. Instead each remapped + (num_id, ilvl, depth) combination gets a minimal generated definition that + places the original format at the required depth. + + Args: + document_soup (BeautifulSoup): The parsed document.xml. + numbering_soup (BeautifulSoup): The parsed numbering.xml. + remappings (list): Output of _resolve_list_depths. + """ + numbering_root = numbering_soup.find("numbering") + if numbering_root is None: + return + + existing_num_ids = { + int(num.get("w:numId")) + for num in numbering_soup.find_all("num") + if (num.get("w:numId") or "").isdigit() + } + existing_abstract_ids = { + int(abstract_num.get("w:abstractNumId")) + for abstract_num in numbering_soup.find_all("abstractNum") + if (abstract_num.get("w:abstractNumId") or "").isdigit() + } + next_num_id = max(existing_num_ids, default=0) + 1 + next_abstract_id = max(existing_abstract_ids, default=0) + 1 + + numbering = _read_numbering_definitions(numbering_soup) + generated: dict = {} + + for paragraph, ilvl_tag, num_id_tag, depth in remappings: + num_id = num_id_tag.get("w:val") + ilvl = ilvl_tag.get("w:val") if ilvl_tag is not None else "0" + key = (num_id, ilvl, depth) + + if key not in generated: + num_fmt = numbering.get(num_id, {}).get(ilvl, {}).get("fmt") + + abstract_num = numbering_soup.new_tag( + "abstractNum", namespace=W_NS, nsprefix="w" + ) + abstract_num["w:abstractNumId"] = str(next_abstract_id) + lvl = numbering_soup.new_tag("lvl", namespace=W_NS, nsprefix="w") + lvl["w:ilvl"] = str(depth) + if num_fmt is not None: + num_fmt_tag = numbering_soup.new_tag( + "numFmt", namespace=W_NS, nsprefix="w" + ) + num_fmt_tag["w:val"] = num_fmt + lvl.append(num_fmt_tag) + abstract_num.append(lvl) + + num = numbering_soup.new_tag("num", namespace=W_NS, nsprefix="w") + num["w:numId"] = str(next_num_id) + abstract_num_id = numbering_soup.new_tag( + "abstractNumId", namespace=W_NS, nsprefix="w" + ) + abstract_num_id["w:val"] = str(next_abstract_id) + num.append(abstract_num_id) + + # "w:abstractNum" elements must precede "w:num" elements. + first_num = numbering_root.find("num", recursive=False) + if first_num is not None: + first_num.insert_before(abstract_num) + else: + numbering_root.append(abstract_num) + numbering_root.append(num) + + generated[key] = str(next_num_id) + next_abstract_id += 1 + next_num_id += 1 + + num_id_tag["w:val"] = generated[key] + if ilvl_tag is None: + num_pr = num_id_tag.parent + ilvl_tag = document_soup.new_tag("ilvl", namespace=W_NS, nsprefix="w") + num_pr.insert(0, ilvl_tag) + ilvl_tag["w:val"] = str(depth) + + +def _pre_process_lists(document_content: bytes, numbering_content: bytes) -> tuple: + """ + Restores list nesting that is expressed through indentation rather than levels. + + Args: + document_content (bytes): The XML content of word/document.xml. + numbering_content (bytes): The XML content of word/numbering.xml. + + Returns: + tuple: The processed (document_content, numbering_content) as bytes. + """ + document_soup = BeautifulSoup(document_content.decode(), features="xml") + numbering_soup = BeautifulSoup(numbering_content.decode(), features="xml") + + numbering = _read_numbering_definitions(numbering_soup) + remappings = _resolve_list_depths(document_soup, numbering) + if not remappings: + return document_content, numbering_content + + _apply_list_depths(document_soup, numbering_soup, remappings) + return str(document_soup).encode(), str(numbering_soup).encode() + + def pre_process_docx(input_docx: BinaryIO) -> BinaryIO: """ Pre-processes a DOCX file with provided steps. @@ -274,6 +577,21 @@ def pre_process_docx(input_docx: BinaryIO) -> BinaryIO: } with zipfile.ZipFile(input_docx, mode="r") as zip_input: files = {name: zip_input.read(name) for name in zip_input.namelist()} + + # List nesting spans document.xml and numbering.xml, so both are + # rewritten together rather than one file at a time below. + if "word/document.xml" in files and "word/numbering.xml" in files: + try: + ( + files["word/document.xml"], + files["word/numbering.xml"], + ) = _pre_process_lists( + files["word/document.xml"], files["word/numbering.xml"] + ) + except Exception: + # If there is an error in processing the content, keep the original content + pass + with zipfile.ZipFile(output_docx, mode="w") as zip_output: zip_output.comment = zip_input.comment for name, content in files.items(): diff --git a/packages/markitdown/tests/test_docx_lists.py b/packages/markitdown/tests/test_docx_lists.py new file mode 100644 index 0000000000..eb1c7fa4ca --- /dev/null +++ b/packages/markitdown/tests/test_docx_lists.py @@ -0,0 +1,189 @@ +#!/usr/bin/env python3 -m pytest +import io +import os +import zipfile + +from markitdown import MarkItDown + +# Word represents a nested list in either of two ways: as a deeper "w:ilvl" +# within the parent's "w:numId", or as an entirely new "w:numId" at "w:ilvl" 0 +# that is simply indented further. Both render identically in Word, so both +# must produce a nested list in the Markdown output. + +TEST_FILES_DIR = os.path.join(os.path.dirname(__file__), "test_files") + +_W_NS = 'xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main"' + +_CONTENT_TYPES = """ + + + + + +""" + +_RELS = """ + + +""" + +_DOCUMENT_RELS = """ + + +""" + + +def _build_docx(paragraphs, abstract_nums, nums) -> io.BytesIO: + """ + Builds a minimal DOCX exercising a particular list structure. + + Args: + paragraphs: (text, num_id, ilvl) tuples. A num_id of None makes the + paragraph ordinary body text. + abstract_nums: abstract_num_id -> [(ilvl, num_fmt, indent), ...]. + nums: num_id -> abstract_num_id. + + Returns: + io.BytesIO: The generated DOCX file. + """ + body = [] + for text, num_id, ilvl in paragraphs: + if num_id is None: + body.append(f"{text}") + else: + body.append( + f'' + f'' + f"{text}" + ) + document = ( + '' + f'{"".join(body)}' + ) + + definitions = [] + for abstract_num_id, levels in abstract_nums.items(): + lvls = [] + for ilvl, num_fmt, indent in levels: + indentation = ( + f'' + if indent is not None + else "" + ) + lvls.append( + f'' + f"{indentation}" + ) + definitions.append( + f'' + f'{"".join(lvls)}' + ) + for num_id, abstract_num_id in nums.items(): + definitions.append( + f'' + f'' + ) + numbering = ( + '' + f'{"".join(definitions)}' + ) + + output = io.BytesIO() + with zipfile.ZipFile(output, "w") as docx: + docx.writestr("[Content_Types].xml", _CONTENT_TYPES) + docx.writestr("_rels/.rels", _RELS) + docx.writestr("word/_rels/document.xml.rels", _DOCUMENT_RELS) + docx.writestr("word/document.xml", document) + docx.writestr("word/numbering.xml", numbering) + output.seek(0) + return output + + +def _convert(paragraphs, abstract_nums, nums) -> str: + markitdown = MarkItDown() + result = markitdown.convert_stream( + _build_docx(paragraphs, abstract_nums, nums), file_extension=".docx" + ) + return result.text_content.strip() + + +def test_docx_multilevel_lists() -> None: + # A sub-list that Word stored as a separate numbering definition must still + # nest, rather than being flattened into its parent and renumbered. + markitdown = MarkItDown() + result = markitdown.convert(os.path.join(TEST_FILES_DIR, "multilevel_lists.docx")) + + assert ( + "1. Item 1\n" + "2. Item 2\n" + " * Item 2.1\n" + " * Item 2.2\n" + "3. Item 3\n" + " 1. Item 3.1\n" + " 2. Item 3.2" in result.text_content + ) + # Flattening previously renumbered the sub-items as siblings of Item 3. + assert "4. Item 3.1" not in result.text_content + + +def test_docx_sub_list_as_new_num_id() -> None: + # The sub-list is a different w:numId at w:ilvl 0, distinguishable from its + # parent only by indentation. + assert _convert( + [("A", 1, 0), ("B", 1, 0), ("B.1", 2, 0), ("B.2", 2, 0)], + {0: [(0, "decimal", 720)], 1: [(0, "decimal", 1080)]}, + {1: 0, 2: 1}, + ) == ("1. A\n2. B\n 1. B.1\n 2. B.2") + + +def test_docx_sub_list_preserves_bullets() -> None: + # The sub-list's own numbering defines w:ilvl 1 as decimal, so nesting it by + # raising w:ilvl alone would silently turn these bullets into numbers. + assert _convert( + [("A", 1, 0), ("A.1", 2, 0)], + {0: [(0, "decimal", 720)], 1: [(0, "bullet", 1080), (1, "decimal", 1080)]}, + {1: 0, 2: 1}, + ) == ("1. A\n * A.1") + + +def test_docx_nesting_from_declared_levels_is_unchanged() -> None: + # Lists that already declare their nesting through w:ilvl must be untouched. + assert _convert( + [("A", 1, 0), ("A.1", 1, 1), ("B", 1, 0)], + {0: [(0, "decimal", 720), (1, "bullet", 1440)]}, + {1: 0}, + ) == ("1. A\n * A.1\n2. B") + + +def test_docx_equal_level_indents_are_not_flattened() -> None: + # Both levels carry identical indentation, so indentation alone cannot + # separate them; the declared w:ilvl has to win within a single w:numId. + assert _convert( + [("A", 1, 0), ("A.1", 1, 1)], + {0: [(0, "decimal", 1080), (1, "bullet", 1080)]}, + {1: 0}, + ) == ("1. A\n * A.1") + + +def test_docx_list_interrupted_by_paragraph() -> None: + # Body text ends the surrounding list, so the following list starts over at + # the top level even though it is indented further. + converted = _convert( + [("A", 1, 0), ("break", None, None), ("B", 2, 0)], + {0: [(0, "decimal", 720)], 1: [(0, "decimal", 1080)]}, + {1: 0, 2: 1}, + ) + assert "1. A" in converted + assert "\n1. B" in converted + + +def test_docx_deep_nesting_keeps_every_item() -> None: + # mammoth's default style map only maps five levels of list nesting, and a + # paragraph promoted past the last of them would drop out of the list. + converted = _convert( + [(f"L{index}", index + 1, 0) for index in range(7)], + {index: [(0, "decimal", 720 + 360 * index)] for index in range(7)}, + {index + 1: index for index in range(7)}, + ) + for index in range(7): + assert f"L{index}" in converted diff --git a/packages/markitdown/tests/test_files/multilevel_lists.docx b/packages/markitdown/tests/test_files/multilevel_lists.docx new file mode 100644 index 0000000000000000000000000000000000000000..ba81444dfee7ad9a23d1333d524ee3086d64860b GIT binary patch literal 15305 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 literal 0 HcmV?d00001