mammoth vs docxtemplater vs jszip-utils vs docx-templates vs officegen
Document Generation Libraries Comparison
1 Year
mammothdocxtemplaterjszip-utilsdocx-templatesofficegenSimilar Packages:
What's Document Generation Libraries?

These libraries are designed to facilitate the creation and manipulation of Microsoft Word documents in web applications. They provide various functionalities such as templating, document generation, and conversion, allowing developers to automate document workflows and enhance productivity. Each library has its unique features and use cases, catering to different needs in document generation and manipulation.

Package Weekly Downloads Trend
Github Stars Ranking
Stat Detail
Package
Downloads
Stars
Size
Issues
Publish
License
mammoth472,5455,2442.14 MB562 months agoBSD-2-Clause
docxtemplater134,9903,2211.15 MB67 days agoMIT
jszip-utils41,835232-276 years ago(MIT OR GPL-3.0)
docx-templates31,6729491.22 MB59a year agoMIT
officegen14,9132,6672.73 MB200-MIT
Feature Comparison: mammoth vs docxtemplater vs jszip-utils vs docx-templates vs officegen

Templating Support

  • mammoth:

    mammoth does not support templating but excels at converting HTML content into Word documents, preserving the formatting and structure, which can be useful for importing web content into Word.

  • docxtemplater:

    docxtemplater offers advanced templating capabilities, allowing for complex structures, loops, and conditions within templates. This flexibility makes it suitable for generating documents that require dynamic content based on various conditions or data sets.

  • jszip-utils:

    jszip-utils does not provide templating support directly, as it focuses on ZIP file manipulation. However, it can be used in conjunction with templating libraries to handle the binary data of Word documents effectively.

  • docx-templates:

    docx-templates provides a simple templating mechanism that allows you to define placeholders in a Word document template. You can easily replace these placeholders with dynamic data, making it ideal for generating standardized documents like invoices or reports.

  • officegen:

    officegen allows for basic templating through its API, where you can programmatically create document elements, but it lacks the advanced templating features found in docx-templates and docxtemplater.

Document Format Compatibility

  • mammoth:

    mammoth converts HTML to DOCX, making it a great choice for applications that need to transform web content into Word documents. It focuses on maintaining the integrity of the original HTML structure during conversion.

  • docxtemplater:

    docxtemplater also focuses on the DOCX format, providing robust support for generating documents that maintain compatibility with Microsoft Word, ensuring that generated documents look as intended.

  • jszip-utils:

    jszip-utils is designed for working with ZIP files, which is essential for handling DOCX files since they are essentially ZIP archives containing XML files. It enables reading and writing binary data efficiently.

  • docx-templates:

    docx-templates specifically targets the DOCX format, making it suitable for generating Word documents that are compatible with Microsoft Word and other DOCX readers.

  • officegen:

    officegen supports multiple Office document formats, including DOCX, XLSX, and PPTX, making it versatile for applications that need to generate various types of Office documents.

Ease of Use

  • mammoth:

    mammoth is easy to use for converting HTML to DOCX, with a simple API that allows developers to quickly implement document conversion without extensive setup.

  • docxtemplater:

    docxtemplater has a slightly steeper learning curve due to its advanced features, but it provides comprehensive documentation and examples to help developers utilize its full potential effectively.

  • jszip-utils:

    jszip-utils is relatively easy to use for those familiar with handling binary data and ZIP files. However, it requires some understanding of how DOCX files are structured as ZIP archives.

  • docx-templates:

    docx-templates is user-friendly and straightforward, making it easy for developers to get started with document generation without a steep learning curve. Its simple API allows for quick integration into projects.

  • officegen:

    officegen offers a straightforward API for generating Office documents, making it accessible for developers who need to create documents programmatically without complex configurations.

Performance

  • mammoth:

    mammoth performs well in converting HTML to DOCX, but the performance can be affected by the complexity of the HTML being converted, especially if it contains a lot of styling and elements.

  • docxtemplater:

    docxtemplater is optimized for performance, especially with large documents and complex templates, as it efficiently handles dynamic content generation without significant slowdowns.

  • jszip-utils:

    jszip-utils is efficient for reading and writing binary data, but performance can be impacted by the size of the ZIP files being processed, particularly with large DOCX documents.

  • docx-templates:

    docx-templates performs well for generating documents with simple templates, but performance may vary with highly complex documents due to the overhead of processing placeholders.

  • officegen:

    officegen is generally performant for generating documents, but the speed can vary depending on the complexity and size of the documents being created.

Community and Support

  • mammoth:

    mammoth has a supportive community and clear documentation, making it easy for developers to get assistance and examples for converting HTML to DOCX.

  • docxtemplater:

    docxtemplater has a strong community and extensive documentation, with many examples and use cases available, ensuring that developers can find the support they need.

  • jszip-utils:

    jszip-utils is a utility library that benefits from the popularity of JSZip, with community support available through GitHub, although it may not have as extensive documentation as the others.

  • docx-templates:

    docx-templates has a growing community and good documentation, providing support through GitHub issues and discussions, making it easier for developers to find help and resources.

  • officegen:

    officegen has a decent community and documentation, but it may not be as extensive as the other libraries, which could make finding support slightly more challenging.

How to Choose: mammoth vs docxtemplater vs jszip-utils vs docx-templates vs officegen
  • mammoth:

    Use mammoth if you need to convert HTML documents to Word format while preserving the structure and styling. It is particularly useful for applications that require importing content from web pages into Word documents, ensuring a high-quality conversion process.

  • docxtemplater:

    Opt for docxtemplater if you require a more powerful templating engine that supports complex document structures and dynamic content. It is suitable for generating documents with advanced features like conditional content and loops, making it ideal for applications with intricate document generation needs.

  • jszip-utils:

    Select jszip-utils if your primary focus is on manipulating ZIP files and you need to handle binary data efficiently. This library is often used in conjunction with other libraries for tasks like reading and writing Word documents, but it is not a standalone document generation tool.

  • docx-templates:

    Choose docx-templates if you need a straightforward templating solution that allows you to create Word documents using simple templates with placeholders. It is ideal for generating documents based on predefined formats and is easy to integrate into existing applications.

  • officegen:

    Choose officegen if you want a library that can generate various types of Office documents (including Word, Excel, and PowerPoint) from scratch. It is suitable for applications that require multi-format document generation and offers a simple API for creating documents programmatically.

README for mammoth

Mammoth .docx to HTML converter

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 Heading 1 to h1 elements, rather than attempting to exactly copy the styling (font, text size, colour, etc.) of the heading.

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.

  • Customisable mapping from your own docx styles to HTML. For instance, you could convert WarningHeading to h1.warning by providing an appropriate style mapping.

  • 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, underlines, strikethrough, superscript and subscript.

  • Links.

  • Line breaks.

  • Text boxes. The contents of the text box are treated as a separate paragraph that appears after the paragraph containing the text box.

  • Comments.

Web demo

The easiest way to try out mammoth is to use the web demo:

  • Clone this repository
  • Run make setup
  • Open browser-demo/index.html in a web browser

Installation

npm install mammoth

Other supported platforms

Usage

CLI

You can convert docx files by passing the path to the docx file and the output file. For instance:

mammoth document.docx output.html

If no output file is specified, output is written to stdout instead.

The output is an HTML fragment, rather than a full HTML document, encoded with UTF-8. Since the encoding is not explicitly set in the fragment, opening the output file in a web browser may cause Unicode characters to be rendered incorrectly if the browser doesn't default to UTF-8.

Images

By default, images are included inline in the output HTML. If an output directory is specified by --output-dir, the images are written to separate files instead. For instance:

mammoth document.docx --output-dir=output-dir

Existing files will be overwritten if present.

Styles

A custom style map can be read from a file using --style-map. For instance:

mammoth document.docx output.html --style-map=custom-style-map

Where custom-style-map looks something like:

p[style-name='Aside Heading'] => div.aside > h2:fresh
p[style-name='Aside Text'] => div.aside > p:fresh

A description of the syntax for style maps can be found in the section "Writing style maps".

Markdown

Markdown support is deprecated. Generating HTML and using a separate library to convert the HTML to Markdown is recommended, and is likely to produce better results.

Using --output-format=markdown will cause Markdown to be generated. For instance:

mammoth document.docx --output-format=markdown

Library

In node.js and the browser, mammoth can be required in the usual way:

var mammoth = require("mammoth");

Alternatively, you may use the standalone JavaScript file mammoth.browser.js, which includes both mammoth and its dependencies. This uses any loaded module system. For instance, when using CommonJS:

var mammoth = require("mammoth/mammoth.browser");

If no module system is found, mammoth is set as a window global.

The file can be generated using make setup during development.

Basic conversion

To convert an existing .docx file to HTML, use mammoth.convertToHtml:

var mammoth = require("mammoth");

mammoth.convertToHtml({path: "path/to/document.docx"})
    .then(function(result){
        var html = result.value; // The generated HTML
        var messages = result.messages; // Any messages, such as warnings during conversion
    })
    .catch(function(error) {
        console.error(error);
    });

Note that mammoth.convertToHtml returns a promise.

You can also extract the raw text of the document by using mammoth.extractRawText. This will ignore all formatting in the document. Each paragraph is followed by two newlines.

mammoth.extractRawText({path: "path/to/document.docx"})
    .then(function(result){
        var text = result.value; // The raw text
        var messages = result.messages;
    })
    .catch(function(error) {
        console.error(error);
    });

Custom style map

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. You can pass in a custom map for styles by passing an options object with a styleMap property as a second argument to convertToHtml. A description of the syntax for style maps can be found in the section "Writing style maps". For instance, if paragraphs with the style name Section Title should be converted to h1 elements, and paragraphs with the style name Subsection Title should be converted to h2 elements:

var mammoth = require("mammoth");

var options = {
    styleMap: [
        "p[style-name='Section Title'] => h1:fresh",
        "p[style-name='Subsection Title'] => h2:fresh"
    ]
};
mammoth.convertToHtml({path: "path/to/document.docx"}, options);

To more easily support style maps stored in text files, styleMap can also be a string. Each line is treated as a separate style mapping, ignoring blank lines and lines starting with #:

var options = {
    styleMap: "p[style-name='Section Title'] => h1:fresh\n" +
        "p[style-name='Subsection Title'] => h2:fresh"
};

User-defined style mappings are used in preference to the default style mappings. To stop using the default style mappings altogether, set options.includeDefaultStyleMap to false:

var options = {
    styleMap: [
        "p[style-name='Section Title'] => h1:fresh",
        "p[style-name='Subsection Title'] => h2:fresh"
    ],
    includeDefaultStyleMap: false
};

Custom image handlers

By default, images are converted to <img> elements with the source included inline in the src attribute. This behaviour can be changed by setting the convertImage option to an image converter .

For instance, the following would replicate the default behaviour:

var options = {
    convertImage: mammoth.images.imgElement(function(image) {
        return image.read("base64").then(function(imageBuffer) {
            return {
                src: "data:" + image.contentType + ";base64," + imageBuffer
            };
        });
    })
};

Bold

By default, bold text is wrapped in <strong> tags. This behaviour can be changed by adding a style mapping for b. For instance, to wrap bold text in <em> tags:

var mammoth = require("mammoth");

var options = {
    styleMap: [
        "b => em"
    ]
};
mammoth.convertToHtml({path: "path/to/document.docx"}, options);

Italic

By default, italic text is wrapped in <em> tags. This behaviour can be changed by adding a style mapping for i. For instance, to wrap italic text in <strong> tags:

var mammoth = require("mammoth");

var options = {
    styleMap: [
        "i => strong"
    ]
};
mammoth.convertToHtml({path: "path/to/document.docx"}, options);

Underline

By default, the underlining of any text is ignored since underlining can be confused with links in HTML documents. This behaviour can be changed by adding a style mapping for u. For instance, suppose that a source document uses underlining for emphasis. The following will wrap any explicitly underlined source text in <em> tags:

var mammoth = require("mammoth");

var options = {
    styleMap: [
        "u => em"
    ]
};
mammoth.convertToHtml({path: "path/to/document.docx"}, options);

Strikethrough

By default, strikethrough text is wrapped in <s> tags. This behaviour can be changed by adding a style mapping for strike. For instance, to wrap strikethrough text in <del> tags:

var mammoth = require("mammoth");

var options = {
    styleMap: [
        "strike => del"
    ]
};
mammoth.convertToHtml({path: "path/to/document.docx"}, options);

Comments

By default, comments are ignored. To include comments in the generated HTML, add a style mapping for comment-reference. For instance:

var mammoth = require("mammoth");

var options = {
    styleMap: [
        "comment-reference => sup"
    ]
};
mammoth.convertToHtml({path: "path/to/document.docx"}, options);

Comments will be appended to the end of the document, with links to the comments wrapped using the specified style mapping.

API

mammoth.convertToHtml(input, options)

Converts the source document to HTML.

  • input: an object describing the source document. On node.js, the following inputs are supported:

    • {path: path}, where path is the path to the .docx file.
    • {buffer: buffer}, where buffer is a node.js Buffer containing a .docx file.

    In the browser, the following inputs are supported:

    • {arrayBuffer: arrayBuffer}, where arrayBuffer is an array buffer containing a .docx file.
  • options (optional): options for the conversion. May have the following properties:

    • styleMap: controls the mapping of Word styles to HTML. If options.styleMap is a string, each line is treated as a separate style mapping, ignoring blank lines and lines starting with #: If options.styleMap is an array, each element is expected to be a string representing a single style mapping. See "Writing style maps" for a reference to the syntax for style maps.

    • includeEmbeddedStyleMap: by default, if the document contains an embedded style map, then it is combined with the default style map. To ignore any embedded style maps, set options.includeEmbeddedStyleMap to false.

    • includeDefaultStyleMap: by default, the style map passed in styleMap is combined with the default style map. To stop using the default style map altogether, set options.includeDefaultStyleMap to false.

    • convertImage: by default, images are converted to <img> elements with the source included inline in the src attribute. Set this option to an image converter to override the default behaviour.

    • ignoreEmptyParagraphs: by default, empty paragraphs are ignored. Set this option to false to preserve empty paragraphs in the output.

    • idPrefix: a string to prepend to any generated IDs, such as those used by bookmarks, footnotes and endnotes. Defaults to an empty string.

    • transformDocument: if set, this function is applied to the document read from the docx file before the conversion to HTML. The API for document transforms should be considered unstable. See document transforms.

  • Returns a promise containing a result. This result has the following properties:

    • value: the generated HTML

    • messages: any messages, such as errors and warnings, generated during the conversion

mammoth.convertToMarkdown(input, options)

Markdown support is deprecated. Generating HTML and using a separate library to convert the HTML to Markdown is recommended, and is likely to produce better results.

Converts the source document to Markdown. This behaves the same as convertToHtml, except that the value property of the result contains Markdown rather than HTML.

mammoth.extractRawText(input)

Extract the raw text of the document. This will ignore all formatting in the document. Each paragraph is followed by two newlines.

  • input: an object describing the source document. On node.js, the following inputs are supported:

    • {path: path}, where path is the path to the .docx file.
    • {buffer: buffer}, where buffer is a node.js Buffer containing a .docx file.

    In the browser, the following inputs are supported:

    • {arrayBuffer: arrayBuffer}, where arrayBuffer is an array buffer containing a .docx file.
  • Returns a promise containing a result. This result has the following properties:

    • value: the raw text

    • messages: any messages, such as errors and warnings

mammoth.embedStyleMap(input, styleMap)

Given an existing docx file, embedStyleMap will generate a new docx file with the passed style map embedded. When the new docx file is read by Mammoth, it will use the embedded style map.

  • input: an object describing the source document. On node.js, the following inputs are supported:

    • {path: path}, where path is the path to the .docx file.
    • {buffer: buffer}, where buffer is a node.js Buffer containing a .docx file.

    In the browser, the following inputs are supported:

    • {arrayBuffer: arrayBuffer}, where arrayBuffer is an array buffer containing a .docx file.
  • styleMap: the style map to embed.

  • Returns a promise. Call toArrayBuffer() on the value inside the promise to get an ArrayBuffer representing the new document. Call toBuffer() on the value inside the promise to get a Buffer representing the new document.

For instance:

mammoth.embedStyleMap({path: sourcePath}, "p[style-name='Section Title'] => h1:fresh")
    .then(function(docx) {
        fs.writeFile(destinationPath, docx.toBuffer(), callback);
    });

Messages

Each message has the following properties:

  • type: a string representing the type of the message, such as "warning" or "error"

  • message: a string containing the actual message

  • error (optional): the thrown exception that caused this message, if any

Image converters

An image converter can be created by calling mammoth.images.imgElement(func). This creates an <img> element for each image in the original docx. func should be a function that has one argument image. This argument is the image element being converted, and has the following properties:

  • contentType: the content type of the image, such as image/png.

  • readAsArrayBuffer(): read the image file as an ArrayBuffer. Returns a promise of an ArrayBuffer.

  • readAsBuffer(): read the image file as a Buffer. Returns a promise of a Buffer. This is not supported in browsers unless a Buffer polyfill has been used.

  • readAsBase64String(): read the image file as a base64-encoded string. Returns a promise of a string.

  • read([encoding]) (deprecated): read the image file with the specified encoding. If an encoding is specified, a promise of a string is returned. If no encoding is specified, a promise of a Buffer is returned.

func should return an object (or a promise of an object) of attributes for the <img> element. At a minimum, this should include the src attribute. If any alt text is found for the image, this will be automatically added to the element's attributes.

For instance, the following replicates the default image conversion:

mammoth.images.imgElement(function(image) {
    return image.readAsBase64String().then(function(imageBuffer) {
        return {
            src: "data:" + image.contentType + ";base64," + imageBuffer
        };
    });
})

mammoth.images.dataUri is the default image converter.

Document transforms

The API for document transforms should be considered unstable, and may change between any versions. If you rely on this behaviour, you should pin to a specific version of mammoth.js, and test carefully before updating.

Mammoth allows a document to be transformed before it is converted. For instance, suppose that document has not been semantically marked up, but you know that any centre-aligned paragraph should be a heading. You can use the transformDocument argument to modify the document appropriately:

function transformElement(element) {
    if (element.children) {
        var children = _.map(element.children, transformElement);
        element = {...element, children: children};
    }

    if (element.type === "paragraph") {
        element = transformParagraph(element);
    }

    return element;
}

function transformParagraph(element) {
    if (element.alignment === "center" && !element.styleId) {
        return {...element, styleId: "Heading2"};
    } else {
        return element;
    }
}

var options = {
    transformDocument: transformElement
};

The return value of transformDocument is used during HTML generation.

The above can be written more succinctly using the helper mammoth.transforms.paragraph:

function transformParagraph(element) {
    if (element.alignment === "center" && !element.styleId) {
        return {...element, styleId: "Heading2"};
    } else {
        return element;
    }
}

var options = {
    transformDocument: mammoth.transforms.paragraph(transformParagraph)
};

Or if you want paragraphs that have been explicitly set to use monospace fonts to represent code:

const monospaceFonts = ["consolas", "courier", "courier new"];

function transformParagraph(paragraph) {
    var runs = mammoth.transforms.getDescendantsOfType(paragraph, "run");
    var isMatch = runs.length > 0 && runs.every(function(run) {
        return run.font && monospaceFonts.indexOf(run.font.toLowerCase()) !== -1;
    });
    if (isMatch) {
        return {
            ...paragraph,
            styleId: "code",
            styleName: "Code"
        };
    } else {
        return paragraph;
    }
}

var options = {
    transformDocument: mammoth.transforms.paragraph(transformParagraph),
    styleMap: [
        "p[style-name='Code'] => pre:separator('\n')"
    ]
};

mammoth.transforms.paragraph(transformParagraph)

Returns a function that can be used as the transformDocument option. This will apply the function transformParagraph to each paragraph element. transformParagraph should return the new paragraph.

mammoth.transforms.run(transformRun)

Returns a function that can be used as the transformDocument option. This will apply the function transformRun to each run element. transformRun should return the new run.

mammoth.transforms.getDescendants(element)

Gets all descendants of an element.

mammoth.transforms.getDescendantsOfType(element, type)

Gets all descendants of a particular type of an element. For instance, to get all runs within an element paragraph:

var runs = mammoth.transforms.getDescendantsOfType(paragraph, "run");

Writing style maps

A style map is made up of a number of style mappings separated by new lines. Blank lines and lines starting with # are ignored.

A style mapping has two parts:

  • On the left, before the arrow, is the document element matcher.
  • On the right, after the arrow, is the HTML path.

When converting each paragraph, Mammoth finds the first style mapping where the document element matcher matches the current paragraph. Mammoth then ensures the HTML path is satisfied.

Freshness

When writing style mappings, it's helpful to understand Mammoth's notion of freshness. When generating, Mammoth will only close an HTML element when necessary. Otherwise, elements are reused.

For instance, suppose one of the specified style mappings is p[style-name='Heading 1'] => h1. If Mammoth encounters a .docx paragraph with the style name Heading 1, the .docx paragraph is converted to a h1 element with the same text. If the next .docx paragraph also has the style name Heading 1, then the text of that paragraph will be appended to the existing h1 element, rather than creating a new h1 element.

In most cases, you'll probably want to generate a new h1 element instead. You can specify this by using the :fresh modifier:

p[style-name='Heading 1'] => h1:fresh

The two consecutive Heading 1 .docx paragraphs will then be converted to two separate h1 elements.

Reusing elements is useful in generating more complicated HTML structures. For instance, suppose your .docx contains asides. Each aside might have a heading and some body text, which should be contained within a single div.aside element. In this case, style mappings similar to p[style-name='Aside Heading'] => div.aside > h2:fresh and p[style-name='Aside Text'] => div.aside > p:fresh might be helpful.

Document element matchers

Paragraphs, runs and tables

Match any paragraph:

p

Match any run:

r

Match any table:

table

To match a paragraph, run or table with a specific style, you can reference the style by name. This is the style name that is displayed in Microsoft Word or LibreOffice. For instance, to match a paragraph with the style name Heading 1:

p[style-name='Heading 1']

You can also match a style name by prefix. For instance, to match a paragraph where the style name starts with Heading:

p[style-name^='Heading']

Styles can also be referenced by style ID. This is the ID used internally in the .docx file. To match a paragraph or run with a specific style ID, append a dot followed by the style ID. For instance, to match a paragraph with the style ID Heading1:

p.Heading1

Bold

Match explicitly bold text:

b

Note that this matches text that has had bold explicitly applied to it. It will not match any text that is bold because of its paragraph or run style.

Italic

Match explicitly italic text:

i

Note that this matches text that has had italic explicitly applied to it. It will not match any text that is italic because of its paragraph or run style.

Underline

Match explicitly underlined text:

u

Note that this matches text that has had underline explicitly applied to it. It will not match any text that is underlined because of its paragraph or run style.

Strikethough

Match explicitly struckthrough text:

strike

Note that this matches text that has had strikethrough explicitly applied to it. It will not match any text that is struckthrough because of its paragraph or run style.

All caps

Match explicitly all caps text:

all-caps

Note that this matches text that has had all caps explicitly applied to it. It will not match any text that is all caps because of its paragraph or run style.

Small caps

Match explicitly small caps text:

small-caps

Note that this matches text that has had small caps explicitly applied to it. It will not match any text that is small caps because of its paragraph or run style.

Highlight

Match explicitly highlighted text:

highlight

Note that this matches text that has had a highlight explicitly applied to it. It will not match any text that is highlighted because of its paragraph or run style.

It's also possible to match specific colours. For instance, to match yellow highlights:

highlight[color='yellow']

The set of colours typically used are:

  • black
  • blue
  • cyan
  • green
  • magenta
  • red
  • yellow
  • white
  • darkBlue
  • darkCyan
  • darkGreen
  • darkMagenta
  • darkRed
  • darkYellow
  • darkGray
  • lightGray

Ignoring document elements

Use ! to ignore a document element. For instance, to ignore any paragraph with the style Comment:

p[style-name='Comment'] => !

HTML paths

Single elements

The simplest HTML path is to specify a single element. For instance, to specify an h1 element:

h1

To give an element a CSS class, append a dot followed by the name of the class:

h1.section-title

To add an attribute, use square brackets similarly to a CSS attribute selector:

p[lang='fr']

To require that an element is fresh, use :fresh:

h1:fresh

Modifiers must be used in the correct order:

h1.section-title:fresh

Separators

To specify a separator to place between the contents of paragraphs that are collapsed together, use :separator('SEPARATOR STRING').

For instance, suppose a document contains a block of code where each line of code is a paragraph with the style Code Block. We can write a style mapping to map such paragraphs to <pre> elements:

p[style-name='Code Block'] => pre

Since pre isn't marked as :fresh, consecutive pre elements will be collapsed together. However, this results in the code all being on one line. We can use :separator to insert a newline between each line of code:

p[style-name='Code Block'] => pre:separator('\n')

Nested elements

Use > to specify nested elements. For instance, to specify h2 within div.aside:

div.aside > h2

You can nest elements to any depth.

Upgrading to later versions

1.0.0

The convertUnderline option is no longer supported. Use style mappings to control how underlines are handled.

0.3.0

If you've defined custom style maps or used a document transform, you will likely need to change your usage slightly. Otherwise, you should be able to continue using Mammoth as before.

Custom style maps

Prior to 0.3.0, Mammoth matched docx paragraphs using style IDs e.g. p.Heading1. These IDs are used internally in the docx format, and are distinct from the style name i.e. the name shown by Microsoft Word or LibreOffice. Although Mammoth still supports matching styles by ID, matching styles by name is preferred. For instance, instead of:

p.AsideHeading => h1

prefer:

p[style-name='Aside Heading'] => h1

Document transforms

Prior to 0.3.0, Mammoth (misleadingly) assigned the style ID to a property called styleName. The style ID is now assigned to a more appropriate property, styleId. The styleName property is now set to the name of the style. To preserve existing behaviour, any existing document transforms should be rewritten in one of two ways:

  • Set the styleId property instead of the styleName property

  • Set the styleName property to the name of the style, rather than the ID

0.2.0

The function mammoth.style() was renamed to mammoth.styleMapping().

Acknowledgements

Thanks to the following people for their contributions to Mammoth:

Donations

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.