Mammoth

Mammoth uses a style_map to decide how Word styles (like Heading 1) map to HTML elements (like <h1>). You can pass this as a string to convert_to_html.

Common mapping patterns:

• Paragraph styles: p[style-name='Style Name'] => element:modifier (e.g., p[style-name='Aside Heading'] => div.aside > h2:fresh)
• Inline styles: b => em (changes bold from <strong> to <em>), i => strong, u => em, strike => del.
• Comments: comment-reference => sup (appends comments to the end of the document).

User-defined mappings take precedence over defaults. To use only your mappings, set include_default_style_map=False.

import mammoth

# Map specific Word styles to HTML elements
style_map = """
    p[style-name='Section Title'] => h1:fresh
    p[style-name='Subsection Title'] => h2:fresh
"""

with open("document.docx", "rb") as docx_file:
    result = mammoth.convert_to_html(docx_file, style_map=style_map)

Mammoth allows you to modify the document structure before it is converted to HTML using the transform_document argument.

Warning: This API is considered unstable and may change between versions.

Available Transform Helpers:

• mammoth.transforms.paragraph(transform_func): Applies transform_func to every paragraph. The function should return the modified (or original) paragraph.
• mammoth.transforms.run(transform_func): Applies transform_func to every run (inline text segment).
• mammoth.transforms.get_descendants(element): Returns all descendants of an element.
• mammoth.transforms.get_descendants_of_type(element, type): Returns descendants of a specific type (e.g., mammoth.documents.Run).

import mammoth.transforms
import mammoth.documents

# Example: Transform center-aligned paragraphs into Heading 2
def transform_paragraph(element):
    if element.alignment == "center" and not element.style_id:
        return element.copy(style_id="Heading2")
    else:
        return element

transform_document = mammoth.transforms.paragraph(transform_paragraph)

mammoth.convert_to_html(docx_file, transform_document=transform_document)

Converts a .docx file (provided as a binary file-like object) to an HTML fragment.

Returns: A result object containing:

• value: The generated HTML string.
• messages: A list of message objects (e.g., warnings).

Key Arguments:

• fileobj: The source file opened in binary mode.
• style_map: A string defining how Word styles map to HTML elements.
• include_default_style_map: (bool) If False, only your style_map is used.
• include_embedded_style_map: (bool) If False, ignores style maps embedded in the document.
• external_file_access: (bool) Set to True to allow access to files referenced outside the document (use only with trusted input).
• convert_image: An image converter function to override default inline behavior.
• ignore_empty_paragraphs: (bool) If False, preserves empty paragraphs.
• id_prefix: (str) A prefix for generated IDs (bookmarks, footnotes, etc.).
• transform_document: A function to modify the document structure before conversion (unstable API).

import mammoth

with open("document.docx", "rb") as docx_file:
    result = mammoth.convert_to_html(docx_file)
    html = result.value
    messages = result.messages

By default, images are converted to inline Base64-encoded <img> elements. To change this (e.g., to save files to disk or use a different format), provide a custom converter to the convert_image argument via mammoth.images.img_element(func).

Your function func receives an image object with:

• open(): Returns a file-like object of the image bytes.
• content_type: The MIME type (e.g., image/png).

func must return a dict of attributes for the <img> tag, including a src key.

import mammoth
import base64

def convert_image(image):
    with image.open() as image_bytes:
        encoded_src = base64.b64encode(image_bytes.read()).decode("ascii")

    return {
        "src": "data:{0};base64,{1}".format(image.content_type, encoded_src)
    }

# Use the converter
with open("document.docx", "rb") as docx_file:
    result = mammoth.convert_to_html(
        docx_file, 
        convert_image=mammoth.images.img_element(convert_image)
    )