API and options
Install with python -m pip install mathml2docx. See getting started
for the optional LaTeX and Markdown dependencies.
Public API
from mathml2docx import convert, MathmlToDocx, TableStyle, ParagraphStyle
convert('<p>Content</p>', 'output.docx', paragraph_style=ParagraphStyle.NORMAL)
parser = MathmlToDocx(table_style=TableStyle.GRID)
HtmlToDocx remains available under its original name. Use MathmlToDocx in new code.
| Method | Result |
|---|---|
convert(html, output=None, **options) |
Return a Document; save it when an output path is supplied |
parser.convert(html, output=None) |
Convert using the instance's settings |
parse_html_string(html) |
Return a new Document |
parse_html_file(input, output=None, encoding='utf-8') |
Return the saved Path; add the extension only once |
parse_mathml(source) |
Return a Document containing native OMML equations |
parse_markdown(source) |
Use optional Markdown to convert headings, tables, code, and strike |
parse_latex(source) |
Return a Document using optional latex2mathml; requires Python 3.6.2+ |
add_html_to_document(html, document) |
Add to a Document, table cell, or DocxTemplate |
add_html_to_cell(html, cell) |
Add to a table cell |
add_image_to_cell(cell, image) |
Add a BytesIO image to a document or cell |
copy_settings_from(other) |
Independently copy options and style mappings |
replace_html(document, marker, html) |
Replace a unique marker, including across runs, with inline or block HTML |
replace_bookmark(document, name, html) |
Replace a bookmark range with HTML |
get_origin() |
Return the current converter instance |
Constructor options
| Argument | Default | Behavior |
|---|---|---|
fix_html |
True |
Compatibility argument; tree parsing always runs |
images |
True |
Enable image handling |
tables |
True |
Enable table handling |
mathml |
True |
Enable MathML handling |
styles |
True |
Enable formatting |
img_src_base_path |
None |
Allow local images only below this directory |
image_loader |
None |
Explicit callback returning bytes or a file object for an asset source |
table_style |
None |
Word table style name or TableStyle constant |
paragraph_style |
None |
Word paragraph style name or ParagraphStyle constant |
stylesheet |
"" |
Additional CSS stylesheet text |
stylesheet_loader |
None |
Explicit callback returning CSS text for an external source |
style_map |
None |
Tag → class → Word style name mapping |
default_math_display |
'inline' |
Layout when the MathML display attribute is omitted; 'block' restores the older behavior |
unsupported_math |
'error' |
'error' raises; 'text' visibly preserves the unsupported formula's XML |
mathml_preprocessor |
None |
Callback accepting and returning a complete MathML string |
mathml_fallback |
None |
Callback (source, error) returning literal text, image bytes or BytesIO |
math_target |
'word' |
'libreoffice' requests explicit upright identifiers and recovery for known lossy native notation |
Change options after construction with, for example, parser.options.images = False.
Set styles and mappings through parser.table_style, parser.paragraph_style, and
parser.style_map. Referenced styles must exist in the Word template.
The default image loader handles data URLs and files below an explicitly configured
base directory. It does not download URLs. If an image_loader uses the network,
the calling application must enforce its own destination, size, and time limits.
See migration and support scope, complete examples, and recipes.
Equation layout, supported enclosures, chemical notation and recovery.