Recipes
The 30 runnable examples include full source, generated DOCX downloads and LibreOffice reference PDFs. This page covers common combinations and lower-level APIs.
Convert several files
Place the HTML files to convert in an input/ directory before running this example.
from pathlib import Path
from mathml2docx import MathmlToDocx
parser = MathmlToDocx()
Path('output').mkdir(exist_ok=True)
for source in Path('input').glob('*.html'):
parser.parse_html_file(source, Path('output') / source.with_suffix('.docx').name)
Each parse_html_string() or parse_html_file() call creates a new document even
when the parser is reused. Use add_html_to_document() to append to one document.
Stylesheets and selectors
from mathml2docx import MathmlToDocx
stylesheets = {'theme.css': '.notice {color:navy} p > strong {color:teal}'}
parser = MathmlToDocx(
stylesheet='h1 {font-size:20pt}',
stylesheet_loader=stylesheets.__getitem__,
)
document = parser.parse_html_string('''
<link rel="stylesheet" href="theme.css">
<style>.notice {background-color:rgba(255,200,0,.25)}</style>
<h1>Notice</h1><p class="notice">Important <strong>content</strong></p>
''')
document.save('styled.docx')
The cascade handles selectors, specificity, source order, inheritance, inline
styles, and !important. @media print and all are applied. External <link>
and @import sources require an explicit loader. Only the Word properties in the
support table below are applied; Flexbox, Grid, JavaScript, and pixel-perfect
browser reproduction are not provided.
Inline markers and bookmarks
Prepare template.docx with exactly one {{customer}} marker and a Word bookmark
named result. This example replaces those existing locations; the
marker and bookmark examples
also show how to create the starting document in Python.
from docx import Document
from mathml2docx import MathmlToDocx
parser = MathmlToDocx()
document = Document('template.docx')
parser.replace_html(document, '{{customer}}', '<b>Alex</b>')
parser.replace_bookmark(document, 'result', '<h2>Analysis</h2><p>Details</p>')
document.save('filled.docx')
A unique marker can span runs. Multiple occurrences are refused to avoid changing unintended locations. Inline HTML stays in the paragraph; block HTML is inserted between the surrounding text. Document bodies and table cells are supported. Bookmarks may span one paragraph or several paragraphs in the same container; ranges crossing table cells are refused. Existing run formatting, pictures, and links, plus relationships for inserted HTML, are preserved. Header/footer markers are not part of the current body search.
Fonts and tab stops in a template
from docx import Document
from docx.shared import Cm, Pt
from docx.enum.text import WD_TAB_ALIGNMENT, WD_TAB_LEADER
from mathml2docx import MathmlToDocx
document = Document()
normal = document.styles['Normal']
normal.font.name = 'Noto Sans CJK KR'
normal.font.size = Pt(11)
normal.paragraph_format.tab_stops.add_tab_stop(
Cm(12), WD_TAB_ALIGNMENT.RIGHT, WD_TAB_LEADER.DOTS)
MathmlToDocx().add_html_to_document('<pre>Item\tAmount</pre>', document)
document.save('tabs.docx')
Setting a font name does not embed it; the reader's environment must provide it.
Ordinary HTML whitespace collapses. pre and white-space:pre-wrap preserve tabs
and newlines.
Insert equation XML and handle unsupported input
from docx import Document
from mathml2docx import mathml_to_omml, latex_to_omml, UnsupportedMathMLError
document = Document()
paragraph = document.add_paragraph('Calculation: ')
paragraph._p.append(mathml_to_omml('<math><msup><mi>x</mi><mn>2</mn></msup></math>'))
paragraph._p.append(latex_to_omml(r'\frac{1}{2}'))
try:
mathml_to_omml('<math><unknown/></math>')
except UnsupportedMathMLError as error:
print(error) # Report unsupported content instead of silently dropping it.
document.save('equations.docx')
The low-level APIs return lxml OMML elements. parse_mathml() and parse_latex()
return Documents and are usually simpler. LaTeX requires its optional extra and
Python 3.6.2+. See the supported math subset.
HTML support
| Area | Supported content |
|---|---|
| Structure | p, div, section, main, article, header, footer, aside, blockquote, pre, figure, figcaption, h1–h6, title |
| Text | b/strong, i/em, u, del/s/strike, sup/sub, code, span, br, hr |
| Links | External URLs, mail, internal links, id/name anchors, text in a without href |
| Tables | table, thead/tbody/tfoot, th/td, rowspan/colspan, empty merged cells, nested tables |
| Lists | ol/ul/li, start/value, nesting, independent numbering restarts |
| Images | Base64 data URLs, files below an explicit directory, asset loaders, inline width/height |
| CSS selection | Type/class/id/compound, child/sibling, static pseudo-classes, inline and important precedence |
| CSS text | color, background-color, font-family/size/weight/style, text-decoration, vertical-align |
| CSS paragraphs | text-align, margin, text-indent, line-height(%), white-space, display:none, visibility:hidden, page breaks |
| CSS tables | width, border, cell backgrounds/text/alignment, table alignment |
| Templates | Existing Document, docxtpl, class-to-paragraph/character styles, markers and bookmarks |
CLI
python -m mathml2docx input.html output.docx
mathml2docx input.html output.docx --encoding utf-8
mathml2docx equation.tex equation.docx --format latex
mathml2docx article.md article.docx --format markdown
mathml2docx equation.mathml equation.docx --format mathml
mathml2docx input.html output.docx --force
Existing output is refused by default. --force explicitly allows overwriting;
using the input path as output is still refused. Python Document.save() follows
python-docx's own save behavior.
Convert Markdown directly
from mathml2docx import MathmlToDocx
# python -m pip install "mathml2docx[markdown]"
MathmlToDocx().parse_markdown("# Title\n\n~~Removed~~ and `code`").save("article.docx")
Tables, fenced code, and strikethrough are supported. ~~ inside code is literal.
Korean and CJK fonts
Select a CJK font available in the reader. Examples 24–27 request Malgun Gothic.
For HTML fragments, target actual elements such as p, or use an inline container
style. A body selector requires a <body> element in the input.
from mathml2docx import convert
convert('<div style="font-family:Malgun Gothic"><p>한글 and English</p></div>', 'korean.docx')
CSS font families populate Latin, East Asian, and complex-script font slots. Font files are not embedded.