Upstream issue compatibility

mathml2docx is derived from pqzx/html2docx. This record maps 49 upstream issue reports (open and closed, excluding pull requests) to behavior in the 1.0 converter. The review snapshot is dated 2026-11-09; the table records reproduction evidence, fixes and remaining input-specific limits. Questions and administrative requests are distinguished from converter defects. See validation for the difference between structure checks and document-application rendering.

Verifying existing fixes

The pre-1.0 implementation at commit 89205f4 was restored in a temporary directory. All six tests/test_existing_fixes.py cases passed there: base64/inline images, missing src, leading br, UTF-8/paragraph styles, nonempty rowspan, and basic text styles. The same cases also run against the replacement engine.

Regressions and issue-specific evidence

Of the nine tests/test_regressions.py cases, the original code produced four errors and one failure. They pass with the new engine. Public API, equations, security, merging, lists, and templates are covered by tests/test_v1.py. Those are XML/relationship checks rather than direct Word screen comparisons.

Issue Status Evidence and limits
#1 failed to convert html table to docx Verified Existing datasets cover tbody and nested tables.
#2 Conversion of <ol><li>: No style with name 'List Number' Fixed Explicit numbering XML avoids dependence on a List Number style being present.
#3 Errno 36] File name too long: 'data:image/png;base64,iVBOR Existing fix verified Base64 image handling.
#4 Does it support css styles? Implemented subset Static style tags/selectors, specificity, inheritance, important, and explicit external CSS loading; applied Word properties are listed in the recipes.
#6 IndexError: list index out of range Original input tested Converted and saved the original FILE.txt input and rendered it with LibreOffice. Merging is also covered by regression tests.
#10 Issue with float margins and named (vs RGB) colors Fixed and verified Fractional lengths and named colors.
#12 <img src="data:image/png;base64,xxxx==> Existing fix verified Base64 PNG images.
#13 ValueError: invalid literal for int() with base 10: 'r' Verified hr and heading tags follow separate paths; existing hr tests pass.
#14 Renders as more or less plain text Original input tested Converted/rendered the 5,660-character Qt HTML from the issue. Preserves fonts, size, color, and emphasis; font size alone does not imply a Heading style.
#15 HTML Tag <a href=... Verified Saved/reopened link text and relationships. Older python-docx paragraph.text behavior is a separate concern.
#21 Color conversion not done when a text is in bold or italic Fixed CSS colors also inherit into bold/italic elements.
#22 Tweak to handle links without href Fixed Text in links without href is retained.
#25 Create document from Word template Implemented and verified Existing Word templates, markers across runs, and bookmarks spanning paragraphs; surrounding formatting and bookmarks are tested.
#27 UnicodeDecodeError: how to convert html documents with accented characters? Existing fix verified UTF-8 file input with non-ASCII text.
#28 Code breaks for base64 image source, saying OSError: [Errno 36] File name too long Existing fix verified Base64 image handling.
#30 <title> attribute should be rendered with the MS Word "Title" style Implemented title creates a Word Title paragraph.
#31 Addin page breaks? Implemented page-break-before/after and break-before/after.
#32 parse_dict_string raising excemptions in edge cases Fixed tinycss2 preserves URL colons, quotes, and whitespace.
#33 Tab_stops Supported with example pre tabs are preserved; recipes show Word tab stops and dotted leaders.
#35 Suggestion for HTML class to Word style mapping Implemented Paragraph classes can map to Quote; inline classes use character style names.
#36 Add support for DocxTemplate fom docxtpl package Implemented and verified Real docxtpl Jinja rendering followed by HTML insertion, save, and reopen. Also fixed reinitializing get_docx and losing rendered content.
#37 'HtmlToDocx' object has no attribute 'run' Structural fix; input unavailable Removed shared run-state dependence. Tests cover leading br, pictures, links, empty input, and cells. The original private input cannot be reproduced.
#38 Getting IndexError: list index out of range when parsing wikipedia page Current real input tested The same Wikipedia URL supplied 2,481,297 bytes, 28 tables, and 626 paragraphs and was PDF-rendered. The original 2022 snapshot was unavailable.
#40 Nested Ordered list not working correctly Original input tested Rendered the attached HTML. Examples cover starts, restarts, depth, li values, and spacing after numbers.
#41 Add the ability to make bold, italics and Underline. Also, can you look into adding superscripts and subscripts? Existing fix verified b/i/sup/sub formatting.
#42 Background Color is Not working Fixed Background colors are stored as real RGB w:shd fills.
#43 table_style = 'TableGrid' Fixed TableGrid alias and public TableStyle.GRID constant.
#44 Converting block level elements like <div> into paragraphs Fixed div, section, and other blocks create paragraphs.
#46 Add classes with specific styles Implemented Tag/class Word style mappings.
#47 Release Latest Version, so we can use paragraph_style support Available in mathml2docx 1.0.0 The published mathml2docx package includes paragraph styles. This does not change releases or publishing rights for the upstream html2docx project.
#48 Unable to convert html with rowspan to docx correctly Existing fix verified and extended The original Phone rowspan case already passed; empty merged cells are now covered too.
#49 margin handler cannot handle percentages Fixed Percent and fractional lengths; percent is relative to available document body width.
#50 Including tables Reviewed Withdrawn by the reporter as malformed HTML; no additional reproduction was requested.
#51 "IndexError: list index out of range" when using colspan attribute Fixed Column counts account for colspan, including empty merged cells.
#52 How can I render HTML-file content to specific tag/word into a template.docx file (word replacement)? Implemented and verified Inline/multi-run/cell markers and single-/multi-paragraph bookmarks. Tests retain surrounding content and inserted image/link/math relationships.
#54 "IndexError: list index out of range" when using rowspan attribute Fixed The Country/Dhaka/Sylhet example checks merge positions and text.
#55 'gbk' codec can't decode byte 0xac in position 1024: illegal multibyte sequence Existing fix verified Explicit UTF-8 reads and an encoding argument.
#57 Poor Performance for Large Tables Fixed and measured Cache the table cell grid rather than repeatedly reconstructing it with Table.cell; see measurements below.
#60 img without src will crash Existing fix verified img without src does not crash.
#61 ImportError: cannot import name 'OxmlElement' from 'docx.oxml' Verified in supported environments Import and document creation are tested with supported dependency ranges; not every historical version combination is guaranteed.
#62 parser crash with a tag without href Fixed Text in a without href is retained.
#66 [bug] tables containing a <td> whose first child is <br> results in a crash Existing fix verified A leading br inside a cell retains following text.
#67 handling base64 image Existing fix verified Data URL PNGs become real DOCX images.
#68 Underline not converting into docx Fixed CSS text-decoration:underline.
#70 ValueError: invalid literal for int() with base 10: '0.88' Fixed and verified Fractional RGBA alpha works and is composited against the inherited background; 50% red over blue is tested as purple.
#71 Images are not positioned correctly in the resulting DOCX file Original images included Loaded all six public images through an explicit loader, saved DOCX, and rendered PDF. Separate regressions check inline position, CSS dimensions, and surrounding text.
#74 Issue with Ordered List Numbering and Strikethrough Rendering in DOCX Fixed; optional frontend added Numbering restarts per list; parse_markdown handles tables/code/strike, keeps literal code tildes, and checks real Word strike properties.
#75 I continued this project on other repo Informational Announcement of a successor repository, not a product defect.
#78 Security: please enable private vulnerability reporting Code and administrative actions separated Implicit HTTP/CSS fetching was removed and local base paths restricted. Upstream Private Vulnerability Reporting requires its owner to change repository settings.

Table performance

A single 300-row × 3-column text table was converted once before and once after replacement in the same Python 3.14 environment: 10.128 seconds before and 0.057 seconds after. After additional CSS support, a repeat measured 0.089 seconds. These are individual measurements, not a performance guarantee or a benchmark of every merge pattern.

Additional checks and examples

  • tests/test_extended.py: selectors/cascade/inheritance, relative font sizes, alpha compositing, markers/bookmarks, image preservation, DOCTYPE, and nested p.
  • tests/test_examples.py: execute all 30 examples separately and reopen their output to inspect tables, math, links, markers, and templates.
  • tests/test_docx_oracles.py: compare saved equation/gallery/report content with independently authored text answers; see validation.
  • Runnable examples: full source, input, generated DOCX downloads in the deployed site, and LibreOffice reference PDFs.
  • LibreOffice 24.2.7.2 imported all 224 equations in the 30 examples; earlier checks also rendered available original issue inputs. Selected report/list/equation screens were inspected. Known visual differences and application-specific checks are documented in the limitations.
  • Qt font size alone is not inferred as heading semantics. Explicit headings and CSS formatting are preserved; Markdown is available as an optional frontend.