Mammoth converts semantically marked up .docx documents to simple and clean HTML, allowing pasting from Word documents and Google Docs without the usu …
Mammoth is designed to convert .docx documents, such as those created by Microsoft Word, Google Docs and LibreOffice, and convert them to HTML. Mammoth aims to produce simple and clean HTML by using semantic information in the document, and ignoring other details. For instance, Mammoth converts any paragraph with the style Heading1
to h1
elements, rather than attempting to exactly copy the styling (font, text size, colour, etc.) of the heading. This allows you to paste from Word documents without the usual mess.
There’s a large mismatch between the structure used by .docx and the structure of HTML, meaning that the conversion is unlikely to be perfect for more complicated documents. Mammoth works best if you only use styles to semantically mark up your document.
The following features are currently supported:
Headings.
Lists.
Tables. The formatting of the table itself, such as borders, is currently ignored, but the formatting of the text is treated the same as in the rest of the document.
Footnotes and endnotes.
Images.
Bold, italics, superscript and subscript.
Links.
Text boxes. The contents of the text box are treated as a separate paragraph that appears after the paragraph containing the text box.
By default, Mammoth maps some common .docx styles to HTML elements. For instance, a paragraph with the style name Heading 1
is converted to a h1
element. If you have a document with your own custom styles, you can use an embedded style map to tell Mammoth how those styles should be mapped. For instance, you could convert paragraphs with the style named WarningHeading
to h1
elements with class="warning"
with the style mapping:
p[style-name='WarningHeading'] => h1.warning:fresh
An online tool can be used to embed style maps into an existing document. Details of how to write style maps can be found on the mammoth.js documentation.
A style map to be used for all documents can be set by configuring Mammoth (see below).
Mammoth can be configured by writing a separate plugin. For instance, this example plugin adds a custom style map, and uses a document transform to detect paragraphs of monospace text and converts them to paragraphs with the style “Code Block”.
As a WordPress plugin, Mammoth uses the JavaScript library mammoth.js to convert documents. Mammoth will use the JavaScript global MAMMOTH_OPTIONS
whenever calling mammoth.js, which allows for some customisation. MAMMOTH_OPTIONS
should be defined as a function that returns an options object. This options object will then be passed in as the options
argument to convertToHtml
. The mammoth.js docs describe the various options available.
The global MAMMOTH_OPTIONS
will be called with mammoth
as the first argument. This can be useful if you need to use a function from mammoth.js, such as mammoth.transforms.getDescendantsOfType
.
Answers to some frequently asked questions about Mammoth.
If you’d like to say thanks, feel free to make a donation through Ko-fi.
If you use Mammoth as part of your business, please consider supporting the ongoing maintenance of Mammoth by making a weekly donation through Liberapay.
Install the plugin in the usual way, and you should be able to use the Mammoth .docx converter when adding a post. If you can’t see the meta box, make sure that it’s selected by taking a look at the “Screen Options” for adding a post.
Add basic Gutenberg support.
Update mammoth.js to 1.4.7.
Allow MAMMOTH_OPTIONS to override idPrefix.
Update mammoth.js to 1.4.0. This includes improved handling of hyperlinks, and converts table headers into thead elements.
Handle unsuccessful image uploads where the HTTP request succeeds, but WordPress rejects the file. Fixes an issue where documents with EMF images couldn’t be imported.
Update mammoth.js to 1.3.2. This includes a fix for documents where images are referenced by a URI relative to the base URI.
Update mammoth.js to 1.3.1. This includes new ways to map styles, such as style name prefixes.
Improve styling of preview to match the editor.
Fix a bug where images wouldn’t upload on certain server configurations.
Allow options to be passed to mammoth.js through a MAMMOTH_OPTIONS global variable.
Include wp-image-* class when inserting images. This allows the WordPress editor to correctly identify the image and show appropriate editing options.
If an image has an alt text description in the original document, set the alt text in the media library when uploading that image.
If an image has an alt text description in the original document, use it to generate the filename.
Set image filename extension based on the image content type.
Show a message while the document is being inserted.
Update mammoth.js to 0.3.30. This includes better support for lists made in LibreOffice.
Fix JavaScript error on admin pages without editors.
Update mammoth.js to 0.3.18. Includes support for hyperlinks to bookmarks in the same document.
Add support for CKEditor.
Support any post type that supports the WordPress editor.
Generate consistent footnote and endnote IDs based on the post ID.
Update mammoth.js to 0.3.15.
Fix preview rendering on Chrome.
Update mammoth.js to 0.3.12.
Update to mammoth.js 0.2.2
Pretty print HTML output
Hide inline image data in raw HTML preview