Mammoth

Warnings

• gotcha Mammoth prioritizes semantic conversion over exact visual fidelity. It converts styles like 'Heading 1' to `<h1>` elements, ignoring precise font sizes or colors. Users expecting a pixel-perfect rendition of their Word document may be disappointed by the 'clean' HTML output.
  Fix: Understand Mammoth's design philosophy: it converts semantic meaning. Use custom style mappings to fine-tune HTML output based on your DOCX styles, focusing on structure rather than visual appearance. Review the generated HTML to ensure it meets your structural requirements.
• breaking Markdown support is deprecated. The `convert_to_markdown` function still exists but is discouraged. Future versions may remove or significantly change this functionality. Generating HTML and then using a separate library for HTML to Markdown conversion is recommended for better results.
  Fix: Migrate to converting DOCX to HTML using `mammoth.convert_to_html` and then use a dedicated HTML-to-Markdown conversion library if Markdown is required.
• breaking Mammoth performs no sanitization of the source `.docx` document. Converting documents from untrusted users can introduce security vulnerabilities, such as `javascript:` links in the output HTML.
  Fix: Always sanitize the HTML output generated by Mammoth, especially if the source documents originate from untrusted users. Implement a robust HTML sanitization library (e.g., `Bleach`) after conversion to remove potentially malicious content.
• gotcha WMF images are not handled by default. If your `.docx` documents contain WMF images, they will not be correctly converted or embedded in the output HTML.
  Fix: Convert WMF images to a supported format (e.g., PNG) before conversion, or implement a custom image converter using `mammoth.images.img_element` that leverages external tools like LibreOffice as demonstrated in the Mammoth recipes.
• gotcha Custom style mappings using `p[style-name='...'] => ...:fresh` can lead to unexpected HTML structures if not fully understood. The `:fresh` option forces a new HTML element, rather than appending content to an existing one, which can be critical for layout.
  Fix: Carefully test custom style mappings, especially when using `:fresh`. Understand when you want content appended to an existing HTML element versus when a new element should be created. Refer to the official documentation for advanced style mapping syntax.

Install

• pip install mammoth Install latest version

Imports

• convert_to_html

  import mammoth
  
  mammoth.convert_to_html(...)

  Primary function for DOCX to HTML conversion.
• extract_raw_text

  import mammoth
  
  mammoth.extract_raw_text(...)

  Used for extracting plain text, ignoring all formatting.
• images

  import mammoth.images

  Accesses image handling utilities, e.g., for custom image converters.

Quickstart

This quickstart demonstrates how to convert a `.docx` file to HTML using `mammoth.convert_to_html`. It also shows how to access any messages (warnings or errors) generated during the conversion process. The input file must be opened in binary read mode (`'rb'`). For this example, a dummy `.docx` file is created using the `python-docx` library.

import mammoth

# Create a dummy docx file for demonstration
from docx import Document
document = Document()
document.add_heading('My Document Title', level=1)
document.add_paragraph('This is a paragraph with some **bold** and *italic* text.')
document.add_paragraph('A second paragraph.')
document.save('document.docx')

# Convert docx to HTML
with open('document.docx', 'rb') as docx_file:
    result = mammoth.convert_to_html(docx_file)
    html = result.value
    messages = result.messages

print('Generated HTML:')
print(html)

if messages:
    print('\nMessages during conversion:')
    for message in messages:
        print(message)

# Clean up the dummy file
import os
os.remove('document.docx')