` tags:\n\n```javascript\nvar mammothPlus = require('mammoth-plus')\n\nvar options = {\n styleMap: ['strike => del']\n}\nmammothPlus.convertToHtml(\n {\n path: 'path/to/document.docx', // in node.js\n arrayBuffer: 'array buffer containing a .docx file' // in browser\n },\n options\n)\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 mammothPlus = require('mammoth-plus')\n\nvar options = {\n styleMap: ['comment-reference => sup']\n}\nmammothPlus.convertToHtml(\n {\n path: 'path/to/document.docx', // in node.js\n arrayBuffer: 'array buffer containing a .docx file' // in browser\n },\n options\n)\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### CLI\n\nYou can convert docx files by passing the path to the docx file and the output file.\nFor instance:\n\n mammoth-plus document.docx output.html\n\nIf no output file is specified, output is written to stdout instead.\n\nThe output is an HTML fragment, rather than a full HTML document, encoded with UTF-8.\nSince the encoding is not explicitly set in the fragment,\nopening the output file in a web browser may cause Unicode characters to be rendered incorrectly if the browser doesn't default to UTF-8.\n\n#### Images\n\nBy default, images are included inline in the output HTML.\nIf an output directory is specified by `--output-dir`,\nthe images are written to separate files instead.\nFor instance:\n\n mammoth-plus document.docx --output-dir=output-dir\n\nExisting files will be overwritten if present.\n\n#### Styles\n\nA custom style map can be read from a file using `--style-map`.\nFor instance:\n\n mammoth-plus document.docx output.html --style-map=custom-style-map\n\nWhere `custom-style-map` looks something like:\n\n p[style-name='Aside Heading'] => div.aside > h2:fresh\n p[style-name='Aside Text'] => div.aside > p:fresh\n\nA description of the syntax for style maps can be found in the section [\"Writing style maps\"](#writing-style-maps).\n\n#### Markdown\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\nUsing `--output-format=markdown` will cause Markdown to be generated.\nFor instance:\n\n mammoth-plus document.docx --output-format=markdown\n\n### API\n\n#### `mammothPlus.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#### `mammothPlus.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#### `mammothPlus.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#### `mammothPlus.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-plus,\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 `toBuffer()` on the value inside the promise to get a `Buffer` representing the new document.\n\nFor instance:\n\n```javascript\nmammothPlus\n .embedStyleMap(\n { path: sourcePath },\n \"p[style-name='Section Title'] => h1:fresh\"\n )\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 `mammothPlus.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- `read([encoding])`: read the image file with the specified encoding.\n If no encoding is specified, a `Buffer` is returned.\n\n- `contentType`: the content type of the image, such as `image/png`.\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\nmammothPlus.images.imgElement(function (image) {\n return image.read('base64').then(function (imageBuffer) {\n return {\n src: 'data:' + image.contentType + ';base64,' + imageBuffer\n }\n })\n})\n```\n\n`mammothPlus.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-plus.js,\nand test carefully before updating.**\n\nmammoth-plus 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 `mammothPlus.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: mammothPlus.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 = mammothPlus.transforms.getDescendantsOfType(paragraph, 'run')\n var isMatch =\n runs.length > 0 &&\n runs.every(function (run) {\n return (\n run.font &&\n monospaceFonts.indexOf(run.font.toLowerCase()) !== -1\n )\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: mammothPlus.transforms.paragraph(transformParagraph),\n styleMap: [\"p[style-name='Code'] => pre:separator('\\n')\"]\n}\n```\n\n#### `mammothPlus.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#### `mammothPlus.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#### `mammothPlus.transforms.getDescendants(element)`\n\nGets all descendants of an element.\n\n#### `mammothPlus.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 = mammothPlus.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-plus finds the first style mapping where the document element matcher matches the current paragraph.\nmammoth-plus then ensures the HTML path is satisfied.\n\n### Freshness\n\nWhen writing style mappings, it's helpful to understand mammoth-plus's notion of freshness.\nWhen generating, mammoth-plus 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-plus 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","readmeFilename":"README.md"}