` tags:\n\n```javascript\nvar mammoth = require(\"mammoth\");\n\nvar options = {\n styleMap: [\n \"strike => del\"\n ]\n};\nmammoth.convertToHtml({path: \"path/to/document.docx\"}, options);\n```\n\n#### Comments\n\nBy default, comments are ignored.\nTo include comments in the generated HTML,\nadd a style mapping for `comment-reference`.\nFor instance:\n\n```javascript\nvar mammoth = require(\"mammoth\");\n\nvar options = {\n styleMap: [\n \"comment-reference => sup\"\n ]\n};\nmammoth.convertToHtml({path: \"path/to/document.docx\"}, options);\n```\n\nComments will be appended to the end of the document,\nwith links to the comments wrapped using the specified style mapping.\n\n### API\n\n#### `mammoth.convertToHtml(input, options)`\n\nConverts the source document to HTML.\n\n* `input`: an object describing the source document.\n On node.js, the following inputs are supported:\n\n * `{path: path}`, where `path` is the path to the .docx file.\n * `{buffer: buffer}`, where `buffer` is a node.js Buffer containing a .docx file.\n\n In the browser, the following inputs are supported:\n\n * `{arrayBuffer: arrayBuffer}`, where `arrayBuffer` is an array buffer containing a .docx file.\n\n* `options` (optional): options for the conversion.\n May have the following properties:\n\n * `styleMap`: controls the mapping of Word styles to HTML.\n If `options.styleMap` is a string,\n each line is treated as a separate style mapping,\n ignoring blank lines and lines starting with `#`:\n If `options.styleMap` is an array,\n each element is expected to be a string representing a single style mapping.\n See [\"Writing style maps\"](#writing-style-maps) for a reference to the syntax for style maps.\n\n * `includeEmbeddedStyleMap`: by default,\n if the document contains an embedded style map, then it is combined with the default style map.\n To ignore any embedded style maps,\n set `options.includeEmbeddedStyleMap` to `false`.\n\n * `includeDefaultStyleMap`: by default,\n the style map passed in `styleMap` is combined with the default style map.\n To stop using the default style map altogether,\n set `options.includeDefaultStyleMap` to `false`.\n\n * `convertImage`: by default, images are converted to `![]()
` elements with the source included inline in the `src` attribute.\n Set this option to an [image converter](#image-converters) to override the default behaviour.\n\n * `ignoreEmptyParagraphs`: by default, empty paragraphs are ignored.\n Set this option to `false` to preserve empty paragraphs in the output.\n\n * `idPrefix`:\n a string to prepend to any generated IDs,\n such as those used by bookmarks, footnotes and endnotes.\n Defaults to an empty string.\n\n * `transformDocument`: if set,\n this function is applied to the document read from the docx file before the conversion to HTML.\n The API for document transforms should be considered unstable.\n See [document transforms](#document-transforms).\n\n* Returns a promise containing a result.\n This result has the following properties:\n\n * `value`: the generated HTML\n\n * `messages`: any messages, such as errors and warnings, generated during the conversion\n\n#### `mammoth.convertToMarkdown(input, options)`\n\nMarkdown support is deprecated.\nGenerating HTML and using a separate library to convert the HTML to Markdown is recommended,\nand is likely to produce better results.\n\nConverts the source document to Markdown.\nThis behaves the same as `convertToHtml`,\nexcept that the `value` property of the result contains Markdown rather than HTML.\n\n#### `mammoth.extractRawText(input)`\n\nExtract the raw text of the document.\nThis will ignore all formatting in the document.\nEach paragraph is followed by two newlines.\n\n* `input`: an object describing the source document.\n On node.js, the following inputs are supported:\n\n * `{path: path}`, where `path` is the path to the .docx file.\n * `{buffer: buffer}`, where `buffer` is a node.js Buffer containing a .docx file.\n\n In the browser, the following inputs are supported:\n\n * `{arrayBuffer: arrayBuffer}`, where `arrayBuffer` is an array buffer containing a .docx file.\n\n* Returns a promise containing a result.\n This result has the following properties:\n\n * `value`: the raw text\n\n * `messages`: any messages, such as errors and warnings\n\n#### `mammoth.embedStyleMap(input, styleMap)`\n\nGiven an existing docx file,\n`embedStyleMap` will generate a new docx file with the passed style map embedded.\nWhen the new docx file is read by Mammoth,\nit will use the embedded style map.\n\n* `input`: an object describing the source document.\n On node.js, the following inputs are supported:\n\n * `{path: path}`, where `path` is the path to the .docx file.\n * `{buffer: buffer}`, where `buffer` is a node.js Buffer containing a .docx file.\n\n In the browser, the following inputs are supported:\n\n * `{arrayBuffer: arrayBuffer}`, where `arrayBuffer` is an array buffer containing a .docx file.\n\n* `styleMap`: the style map to embed.\n\n* Returns a promise.\n Call `toArrayBuffer()` on the value inside the promise to get an `ArrayBuffer` representing the new document.\n Call `toBuffer()` on the value inside the promise to get a `Buffer` representing the new document.\n\nFor instance:\n\n```javascript\nmammoth.embedStyleMap({path: sourcePath}, \"p[style-name='Section Title'] => h1:fresh\")\n .then(function(docx) {\n fs.writeFile(destinationPath, docx.toBuffer(), callback);\n });\n```\n\n#### Messages\n\nEach message has the following properties:\n\n* `type`: a string representing the type of the message, such as `\"warning\"` or\n `\"error\"`\n\n* `message`: a string containing the actual message\n\n* `error` (optional): the thrown exception that caused this message, if any\n\n#### Image converters\n\nAn image converter can be created by calling `mammoth.images.imgElement(func)`.\nThis creates an `![]()
` element for each image in the original docx.\n`func` should be a function that has one argument `image`.\nThis argument is the image element being converted,\nand has the following properties:\n\n* `contentType`: the content type of the image, such as `image/png`.\n\n* `readAsArrayBuffer()`: read the image file as an `ArrayBuffer`.\n Returns a promise of an `ArrayBuffer`.\n\n* `readAsBuffer()`: read the image file as a `Buffer`.\n Returns a promise of a `Buffer`.\n This is not supported in browsers unless a `Buffer` polyfill has been used.\n\n* `readAsBase64String()`: read the image file as a base64-encoded string.\n Returns a promise of a `string`.\n\n* `read([encoding])` (deprecated): read the image file with the specified encoding.\n If an encoding is specified, a promise of a `string` is returned.\n If no encoding is specified, a promise of a `Buffer` is returned.\n\n`func` should return an object (or a promise of an object) of attributes for the `![]()
` element.\nAt a minimum, this should include the `src` attribute.\nIf any alt text is found for the image,\nthis will be automatically added to the element's attributes.\n\nFor instance, the following replicates the default image conversion:\n\n```javascript\nmammoth.images.imgElement(function(image) {\n return image.readAsBase64String().then(function(imageBuffer) {\n return {\n src: \"data:\" + image.contentType + \";base64,\" + imageBuffer\n };\n });\n})\n```\n\n`mammoth.images.dataUri` is the default image converter.\n\n### Document transforms\n\n**The API for document transforms should be considered unstable,\nand may change between any versions.\nIf you rely on this behaviour,\nyou should pin to a specific version of mammoth.js,\nand test carefully before updating.**\n\nMammoth allows a document to be transformed before it is converted.\nFor instance,\nsuppose that document has not been semantically marked up,\nbut you know that any centre-aligned paragraph should be a heading.\nYou can use the `transformDocument` argument to modify the document appropriately:\n\n```javascript\nfunction transformElement(element) {\n if (element.children) {\n var children = _.map(element.children, transformElement);\n element = {...element, children: children};\n }\n\n if (element.type === \"paragraph\") {\n element = transformParagraph(element);\n }\n\n return element;\n}\n\nfunction transformParagraph(element) {\n if (element.alignment === \"center\" && !element.styleId) {\n return {...element, styleId: \"Heading2\"};\n } else {\n return element;\n }\n}\n\nvar options = {\n transformDocument: transformElement\n};\n```\n\nThe return value of `transformDocument` is used during HTML generation.\n\nThe above can be written more succinctly using the helper `mammoth.transforms.paragraph`:\n\n```javascript\nfunction transformParagraph(element) {\n if (element.alignment === \"center\" && !element.styleId) {\n return {...element, styleId: \"Heading2\"};\n } else {\n return element;\n }\n}\n\nvar options = {\n transformDocument: mammoth.transforms.paragraph(transformParagraph)\n};\n```\n\nOr if you want paragraphs that have been explicitly set to use monospace fonts to represent code:\n\n```javascript\nconst monospaceFonts = [\"consolas\", \"courier\", \"courier new\"];\n\nfunction transformParagraph(paragraph) {\n var runs = mammoth.transforms.getDescendantsOfType(paragraph, \"run\");\n var isMatch = runs.length > 0 && runs.every(function(run) {\n return run.font && monospaceFonts.indexOf(run.font.toLowerCase()) !== -1;\n });\n if (isMatch) {\n return {\n ...paragraph,\n styleId: \"code\",\n styleName: \"Code\"\n };\n } else {\n return paragraph;\n }\n}\n\nvar options = {\n transformDocument: mammoth.transforms.paragraph(transformParagraph),\n styleMap: [\n \"p[style-name='Code'] => pre:separator('\\n')\"\n ]\n};\n```\n\n#### `mammoth.transforms.paragraph(transformParagraph)`\n\nReturns a function that can be used as the `transformDocument` option.\nThis will apply the function `transformParagraph` to each paragraph element.\n`transformParagraph` should return the new paragraph.\n\n#### `mammoth.transforms.run(transformRun)`\n\nReturns a function that can be used as the `transformDocument` option.\nThis will apply the function `transformRun` to each run element.\n`transformRun` should return the new run.\n\n#### `mammoth.transforms.getDescendants(element)`\n\nGets all descendants of an element.\n\n#### `mammoth.transforms.getDescendantsOfType(element, type)`\n\nGets all descendants of a particular type of an element.\nFor instance, to get all runs within an element `paragraph`:\n\n```javascript\nvar runs = mammoth.transforms.getDescendantsOfType(paragraph, \"run\");\n```\n\n## Writing style maps\n\nA style map is made up of a number of style mappings separated by new lines.\nBlank lines and lines starting with `#` are ignored.\n\nA style mapping has two parts:\n\n* On the left, before the arrow, is the document element matcher.\n* On the right, after the arrow, is the HTML path.\n\nWhen converting each paragraph,\nMammoth finds the first style mapping where the document element matcher matches the current paragraph.\nMammoth then ensures the HTML path is satisfied.\n\n### Freshness\n\nWhen writing style mappings, it's helpful to understand Mammoth's notion of freshness.\nWhen generating, Mammoth will only close an HTML element when necessary.\nOtherwise, elements are reused.\n\nFor instance, suppose one of the specified style mappings is `p[style-name='Heading 1'] => h1`.\nIf Mammoth encounters a .docx paragraph with the style name `Heading 1`,\nthe .docx paragraph is converted to a `h1` element with the same text.\nIf the next .docx paragraph also has the style name `Heading 1`,\nthen the text of that paragraph will be appended to the *existing* `h1` element,\nrather than creating a new `h1` element.\n\nIn most cases, you'll probably want to generate a new `h1` element instead.\nYou can specify this by using the `:fresh` modifier:\n\n`p[style-name='Heading 1'] => h1:fresh`\n\nThe two consecutive `Heading 1` .docx paragraphs will then be converted to two separate `h1` elements.\n\nReusing elements is useful in generating more complicated HTML structures.\nFor instance, suppose your .docx contains asides.\nEach aside might have a heading and some body text,\nwhich should be contained within a single `div.aside` element.\nIn this case, style mappings similar to `p[style-name='Aside Heading'] => div.aside > h2:fresh` and\n`p[style-name='Aside Text'] => div.aside > p:fresh` might be helpful.\n\n### Document element matchers\n\n#### Paragraphs, runs and tables\n\nMatch any paragraph:\n\n```\np\n```\n\nMatch any run:\n\n```\nr\n```\n\nMatch any table:\n\n```\ntable\n```\n\nTo match a paragraph, run or table with a specific style,\nyou can reference the style by name.\nThis is the style name that is displayed in Microsoft Word or LibreOffice.\nFor instance, to match a paragraph with the style name `Heading 1`:\n\n```\np[style-name='Heading 1']\n```\n\nYou can also match a style name by prefix.\nFor instance, to match a paragraph where the style name starts with `Heading`:\n\n```\np[style-name^='Heading']\n```\n\nStyles can also be referenced by style ID.\nThis is the ID used internally in the .docx file.\nTo match a paragraph or run with a specific style ID,\nappend a dot followed by the style ID.\nFor instance, to match a paragraph with the style ID `Heading1`:\n\n```\np.Heading1\n```\n\n#### Bold\n\nMatch explicitly bold text:\n\n```\nb\n```\n\nNote that this matches text that has had bold explicitly applied to it.\nIt will not match any text that is bold because of its paragraph or run style.\n\n#### Italic\n\nMatch explicitly italic text:\n\n```\ni\n```\n\nNote that this matches text that has had italic explicitly applied to it.\nIt will not match any text that is italic because of its paragraph or run style.\n\n#### Underline\n\nMatch explicitly underlined text:\n\n```\nu\n```\n\nNote that this matches text that has had underline explicitly applied to it.\nIt will not match any text that is underlined because of its paragraph or run style.\n\n#### Strikethough\n\nMatch explicitly struckthrough text:\n\n```\nstrike\n```\n\nNote that this matches text that has had strikethrough explicitly applied to it.\nIt will not match any text that is struckthrough because of its paragraph or run style.\n\n#### All caps\n\nMatch explicitly all caps text:\n\n```\nall-caps\n```\n\nNote that this matches text that has had all caps explicitly applied to it.\nIt will not match any text that is all caps because of its paragraph or run style.\n\n#### Small caps\n\nMatch explicitly small caps text:\n\n```\nsmall-caps\n```\n\nNote that this matches text that has had small caps explicitly applied to it.\nIt will not match any text that is small caps because of its paragraph or run style.\n\n#### Ignoring document elements\n\nUse `!` to ignore a document element.\nFor instance, to ignore any paragraph with the style `Comment`:\n\n```\np[style-name='Comment'] => !\n```\n\n### HTML paths\n\n#### Single elements\n\nThe simplest HTML path is to specify a single element.\nFor instance, to specify an `h1` element:\n\n```\nh1\n```\n\nTo give an element a CSS class,\nappend a dot followed by the name of the class:\n\n```\nh1.section-title\n```\n\nTo require that an element is fresh, use `:fresh`:\n\n```\nh1:fresh\n```\n\nModifiers must be used in the correct order:\n\n```\nh1.section-title:fresh\n```\n\n#### Separators\n\nTo specify a separator to place between the contents of paragraphs that are collapsed together,\nuse `:separator('SEPARATOR STRING')`.\n\nFor instance, suppose a document contains a block of code where each line of code is a paragraph with the style `Code Block`.\nWe can write a style mapping to map such paragraphs to `` elements:\n\n```\np[style-name='Code Block'] => pre\n```\n\nSince `pre` isn't marked as `:fresh`,\nconsecutive `pre` elements will be collapsed together.\nHowever, this results in the code all being on one line.\nWe can use `:separator` to insert a newline between each line of code:\n\n```\np[style-name='Code Block'] => pre:separator('\\n')\n```\n\n#### Nested elements\n\nUse `>` to specify nested elements.\nFor instance, to specify `h2` within `div.aside`:\n\n```\ndiv.aside > h2\n```\n\nYou can nest elements to any depth.\n\n## Upgrading to later versions\n\n### 1.0.0\n\nThe `convertUnderline` option is no longer supported.\nUse style mappings to control how underlines are handled.\n\n### 0.3.0\n\nIf you've defined custom style maps or used a document transform,\nyou will likely need to change your usage slightly.\nOtherwise, you should be able to continue using Mammoth as before.\n\n#### Custom style maps\n\nPrior to 0.3.0, Mammoth matched docx paragraphs using style IDs e.g. `p.Heading1`.\nThese IDs are used internally in the docx format,\nand are distinct from the style name\ni.e. the name shown by Microsoft Word or LibreOffice.\nAlthough Mammoth still supports matching styles by ID,\nmatching styles by name is preferred.\nFor instance, instead of:\n\n```p.AsideHeading => h1```\n\nprefer:\n\n```p[style-name='Aside Heading'] => h1```\n\n#### Document transforms\n\nPrior to 0.3.0,\nMammoth (misleadingly) assigned the style ID to a property called `styleName`.\nThe style ID is now assigned to a more appropriate property, `styleId`.\nThe `styleName` property is now set to the name of the style.\nTo preserve existing behaviour,\nany existing document transforms should be rewritten in one of two ways:\n\n* Set the `styleId` property instead of the `styleName` property\n\n* Set the `styleName` property to the name of the style, rather than the ID\n\n### 0.2.0\n\nThe function `mammoth.style()` was renamed to `mammoth.styleMapping()`.\n\n## Acknowledgements\n\nThanks to the following people for their contributions to Mammoth:\n\n* [Craig Leinoff](https://github.com/Offlein):\n\n * Document transforms\n\n* [John McLear](https://github.com/JohnMcLear):\n\n * Underline support\n\n* [Chris Price](https://github.com/studiochris):\n\n * node.js `Buffer` support\n * UTF8 BOM handling\n\n* [Stoo Goff](https://github.com/stoogoff)\n\n * Markdown support\n\n* [Andreas Lubbe](https://github.com/alubbe)\n\n * Internal hyperlink support\n\n* [Jacob Wang](https://github.com/jaceyshome)\n\n * Supporting styles defined without names\n\n## Donations\n\nIf you'd like to say thanks, feel free to [make a donation through Ko-fi](https://ko-fi.com/S6S01MG20).\n\nIf you use Mammoth as part of your business,\nplease consider supporting the ongoing maintenance of Mammoth by [making a weekly donation through Liberapay](https://liberapay.com/mwilliamson/donate).\n","_attachments":{},"homepage":"https://github.com/mwilliamson/mammoth.js#readme","bugs":{"url":"https://github.com/mwilliamson/mammoth.js/issues"},"license":"BSD-2-Clause"}