word-to-markdown 0.2.0 → 0.4.0

package/README.md

@@ -1,6 +1,11 @@
 # Word to Markdown
 
-Convert Word documents to beautiful Markdown. Via command line or in your browser. An even better version of the original [`word-to-markdown`](https://github.com/benbalter/word-to-markdown).
+[![npm version](https://img.shields.io/npm/v/word-to-markdown.svg)](https://www.npmjs.com/package/word-to-markdown)
+[![npm downloads](https://img.shields.io/npm/dm/word-to-markdown.svg)](https://www.npmjs.com/package/word-to-markdown)
+[![CI](https://github.com/benbalter/word-to-markdown-js/actions/workflows/ci.yml/badge.svg)](https://github.com/benbalter/word-to-markdown-js/actions/workflows/ci.yml)
+[![License: Apache-2.0](https://img.shields.io/npm/l/word-to-markdown.svg)](https://github.com/benbalter/word-to-markdown-js/blob/main/LICENSE)
+
+Convert Word documents to beautiful Markdown. Via command line, as a Node library, or in your browser. An even better version of the original [`word-to-markdown`](https://github.com/benbalter/word-to-markdown).
 
 Try it in your browser at [word2md.com](https://word2md.com), or use it from the command line — no clone required:
 
@@ -8,22 +13,46 @@ Try it in your browser at [word2md.com](https://word2md.com), or use it from the
 npx word-to-markdown input.docx > output.md
 ```
 
-## Supports
+## What it converts
 
-- Paragraphs
-- Numbered lists
-- Bullet lists
-- Nested Lists
+- Paragraphs and line breaks
 - Headings
-- Lists
+- Bold, italic, and strikethrough
+- Superscript and subscript — preserved as inline `<sup>`/`<sub>` tags
+- Bullet lists, and numbered lists (kept as `1./2./3.` by default)
+- Nested lists
 - Tables
-- Footnotes and endnotes
-- Images
-- Bold, italics, underlines, strikethrough, superscript and subscript.
 - Links
-- Line breaks
-- Text boxes
-- Comments
+- Footnotes and endnotes — converted to GFM/Pandoc `[^1]` footnotes
+- Images — embedded inline as base64 data URIs, or extracted to files
+
+### Notes and limitations
+
+- **Numbered lists** are kept as `1./2./3.` ordered lists. Pass
+  `{ numberedLists: 'bullets' }` (library) or `--bullet-lists` (CLI) to convert
+  them to bullet lists instead (matching the original word-to-markdown).
+- **Images** are inlined as base64 data URIs by default. To extract them to
+  files with relative links instead, use `{ images: 'extract' }` (library — the
+  bytes come back on `ConvertResult.images`) or `--image-dir <dir>` (CLI). Drop
+  them entirely with `{ images: 'strip' }` / `--strip-images`. On the web,
+  documents with images offer a **Download .zip** (Markdown + an `images/`
+  folder). For full control, pass a custom [Mammoth image handler](https://github.com/mwilliamson/mammoth.js/#images)
+  via `options.mammoth`.
+- **Underline** is dropped by default (Mammoth's default, since underlines are
+  easily confused with links). Pass `{ underline: 'preserve' }` (library) or
+  `--underline` (CLI) to keep it as an inline `<u>` tag.
+- **Footnotes and endnotes** become standard GFM/Pandoc footnotes — a `[^1]`
+  reference in the body and a `[^1]: …` definition at the end — which render on
+  GitHub and in the web preview. Pass `{ footnotes: 'preserve' }` (library) or
+  `--preserve-footnotes` (CLI) to instead keep Mammoth's raw `<sup>` links and
+  numbered note list (useful for CommonMark targets that lack footnote support).
+  A note whose body spans multiple paragraphs (a rare Word construct) is left in
+  Mammoth's raw form rather than converted, so its reference and body stay
+  linked.
+- **Comments, text boxes, and equations are not converted** — Mammoth drops
+  them during the `.docx` → HTML step. When content is dropped this way,
+  `convertWithWarnings` surfaces a warning.
+- Heading levels come from Word's paragraph styles, not from font size.
 
 ## How is this different from the original?
 
@@ -56,8 +85,28 @@ npm install -g word-to-markdown
 w2m path/to/your/file.docx > output.md
 ```
 
+The converted Markdown is written to **stdout** and any document warnings (encryption, sensitivity labels, and the like) to **stderr**, so a redirect captures only the Markdown. The command exits with a non-zero status and a friendly message if the file is missing, unreadable, or not a valid `.docx`. Only `.docx` is supported — re-save older `.doc` files as `.docx` first.
+
+Options:
+
+- `-o, --output <file>` — write the Markdown to `<file>` instead of stdout
+  (warnings still go to stderr).
+- `--bullet-lists` — convert numbered lists to bullets instead of keeping `1./2./3.`.
+- `--underline` — preserve underlined text as inline `<u>` tags (dropped by default).
+- `--strip-images` — remove images instead of embedding them as base64 data URIs.
+- `--image-dir <dir>` — extract images to `<dir>` and link them relatively, instead
+  of embedding base64. Links resolve relative to where you save the Markdown, e.g.
+  `w2m --image-dir images report.docx > report.md`, or with `-o`,
+  `w2m -o out/report.md --image-dir images report.docx` (images land in
+  `out/images/`).
+- `--preserve-footnotes` — keep Word footnotes as raw `<sup>` links and a
+  numbered note list instead of GFM `[^1]` footnotes.
+- `-V, --version` — print the version.
+
 ## Use as a library
 
+Published to npm as [`word-to-markdown`](https://www.npmjs.com/package/word-to-markdown). It ships as an ES module with TypeScript declarations and requires Node 22.13 or later.
+
 ```console
 npm install word-to-markdown
 ```
@@ -74,7 +123,63 @@ const { markdown, warnings } = await convertWithWarnings(
 );
 ```
 
-In the browser, pass an `ArrayBuffer` instead of a file path.
+Both functions accept either a file-path string (Node) or an `ArrayBuffer` (Node or the browser):
+
+```js
+const { markdown } = await convertWithWarnings(arrayBuffer);
+```
+
+### API
+
+- **`convert(input, options?): Promise<string>`** — resolves to the Markdown.
+- **`convertWithWarnings(input, options?): Promise<{ markdown: string; warnings: string[]; images? }>`** — also returns human-readable warnings for encrypted, protected, or sensitivity-labeled documents, and (in `extract` mode) the extracted images.
+
+`input` is a file-path `string` (Node) or an `ArrayBuffer`. `options` (type `ConvertOptions`) is optional:
+
+- **`images`** — `'inline'` (default) embeds images as base64 data URIs; `'strip'` removes them; `'extract'` replaces each with a relative `![](imageDir/imageN.ext)` link and returns the bytes on `ConvertResult.images` (use `convertWithWarnings` to retrieve them).
+- **`imageDir`** — link/path prefix for extracted images (default `'images'`); only applies with `images: 'extract'`.
+- **`numberedLists`** — `'ordered'` (default) keeps `1./2./3.`; `'bullets'` converts numbered lists to bullets.
+- **`underline`** — `'ignore'` (default) drops underlines; `'preserve'` keeps them as inline `<u>` tags.
+- **`footnotes`** — `'gfm'` (default) converts footnotes and endnotes to `[^1]` references and definitions; `'preserve'` keeps Mammoth's raw `<sup>` links and numbered note list.
+- **`mammoth`** / **`turndown`** — escape hatches forwarded to [Mammoth](https://github.com/mwilliamson/mammoth.js/) and [Turndown](https://github.com/mixmark-io/turndown) respectively.
+
+```js
+// Extract images to files and write them out yourself:
+const { markdown, images } = await convertWithWarnings('file.docx', {
+  images: 'extract',
+});
+// markdown → ![](images/image1.png); images → [{ path, contentType, bytes }]
+```
+
+### Error handling
+
+Conversion throws typed errors so you can respond to each failure precisely. All of them extend `WordToMarkdownError`, so `error instanceof WordToMarkdownError` catches any of them.
+
+```js
+import convert, {
+  UnsupportedFileError,
+  FileNotFoundError,
+  InvalidFileError,
+  FilePermissionError,
+  ConversionError,
+} from 'word-to-markdown';
+
+try {
+  const markdown = await convert('path/to/your/file.docx');
+} catch (error) {
+  if (error instanceof UnsupportedFileError) {
+    // a .doc or password-protected file — only unprotected .docx is supported
+  } else if (error instanceof FileNotFoundError) {
+    // the path doesn't exist (or runs through something that isn't a directory)
+  } else if (error instanceof InvalidFileError) {
+    // not a valid or parseable .docx (or the path is a directory)
+  } else if (error instanceof FilePermissionError) {
+    // the file couldn't be read, or is in a blocked system directory
+  } else if (error instanceof ConversionError) {
+    // something failed mid-conversion — see error.cause
+  }
+}
+```
 
 ## Running Locally
 
@@ -98,7 +203,7 @@ To self-host the static site using Docker Compose:
 
 1. Clone the repository
 2. Run `npm install && npm run build`
-3. Run `docker-compose up -d`
+3. Run `docker compose up -d`
 4. Access at http://localhost:3000
 
 ## More context
@@ -111,12 +216,12 @@ See the README of [the original Word to Markdown](https://github.com/benbalter/w
 
 1. Use [LibreOffice](https://www.libreoffice.org/) to convert the Word document to HTML.
 2. Use a bunch of RegEx to clean up the HTML
-3. User [Premailer](https://github.com/premailer/premailer) to inline the CSS
+3. Use [Premailer](https://github.com/premailer/premailer) to inline the CSS
 4. Use [Nokogiri](https://nokogiri.org) to manipulate the HTML further
 5. Use [Reverse Markdown](https://github.com/xijo/reverse_markdown) to convert the HTML to Markdown
 6. Use a bunch of RegEx to clean up the Markdown
 
-Not only did this process require installing and shelling out to a huge binary (LibreOffice), but it was very fragile, and key projects like Reverse Markdown are no longer maintained. I tried experimenting with Pandoc, but it had many of the same limitation.
+Not only did this process require installing and shelling out to a huge binary (LibreOffice), but it was very fragile, and key projects like Reverse Markdown are no longer maintained. I tried experimenting with Pandoc, but it had many of the same limitations.
 
 ### The new way
 
@@ -126,6 +231,6 @@ Not only did this process require installing and shelling out to a huge binary (
 
 All three of these projects are actively maintained and heavily used, and allows us to convert the document faster, and entirely in JavaScript. Heck, I think theoretically, this could run in the browser for added privacy.
 
-It's still in beta, but so far, I've found the output to be better, with much less manual cleanup required. Notice something is off? Please [open an issue](https://github.com/benbalter/word-to-markdown-js/issues/new).
+It's still young, but so far, I've found the output to be better, with much less manual cleanup required. Notice something is off? Please [open an issue](https://github.com/benbalter/word-to-markdown-js/issues/new).
 
 One note: This project does not yet attempt to guess heading levels based on font size. It could, but it's not yet implemented.

package/build/cli.js

@@ -1,16 +1,59 @@
 #!/usr/bin/env node
-import { __awaiter } from "tslib";
 import { Command } from 'commander';
-import { convertWithWarnings, UnsupportedFileError, FileNotFoundError, InvalidFileError, FilePermissionError, ConversionError, } from './main.js';
+import { createRequire } from 'module';
+import { mkdir, writeFile } from 'fs/promises';
+import path from 'path';
+import { convertWithWarnings } from './main.js';
+// Read our own version from package.json. createRequire resolves relative to
+// this module, so `../package.json` points at the package root both from the
+// TypeScript source (src/) and the compiled CLI (build/) after publish. This
+// avoids JSON import attributes, which node16 module resolution would require.
+const require = createRequire(import.meta.url);
+const { version } = require('../package.json');
 const program = new Command();
 program.name('w2m');
 program.description('Convert Word documents to beautiful Markdown');
+program.version(version);
 program
     .command('convert', { isDefault: true })
     .argument('<file>', 'The Word document to convert')
-    .action((file) => __awaiter(void 0, void 0, void 0, function* () {
+    .option('-o, --output <file>', 'Write the Markdown to <file> instead of stdout. Warnings still print to ' +
+    'stderr.')
+    .option('--strip-images', 'Remove images instead of embedding them as base64 data URIs')
+    .option('--image-dir <dir>', 'Extract images to <dir> and link them relatively, instead of embedding ' +
+    'them as base64. Links resolve relative to where you save the Markdown.')
+    .option('--bullet-lists', 'Convert numbered lists to bullets rather than keeping them as 1./2./3.')
+    .option('--underline', 'Preserve underlined text as inline <u> tags (dropped by default)')
+    .option('--preserve-footnotes', 'Keep Word footnotes as raw <sup> links and a numbered note list instead ' +
+    'of converting them to GFM [^1] footnotes')
+    .action(async (file, options) => {
     try {
-        const result = yield convertWithWarnings(file);
+        // --image-dir (extract) takes precedence over --strip-images.
+        if (options.imageDir && options.stripImages) {
+            console.error('Ignoring --strip-images because --image-dir is set.');
+        }
+        const images = options.imageDir
+            ? 'extract'
+            : options.stripImages
+                ? 'strip'
+                : 'inline';
+        const result = await convertWithWarnings(file, {
+            images,
+            imageDir: options.imageDir,
+            numberedLists: options.bulletLists ? 'bullets' : 'ordered',
+            underline: options.underline ? 'preserve' : 'ignore',
+            footnotes: options.preserveFootnotes ? 'preserve' : 'gfm',
+        });
+        // Write extracted images to disk before emitting the Markdown that links
+        // them. The links are relative to the Markdown file, so resolve them
+        // against its directory (the working directory when writing to stdout).
+        if (result.images && result.images.length > 0) {
+            const markdownDir = options.output ? path.dirname(options.output) : '.';
+            const imageDir = path.resolve(markdownDir, options.imageDir);
+            await mkdir(imageDir, { recursive: true });
+            await Promise.all(result.images.map((image) => writeFile(path.resolve(markdownDir, image.path), image.bytes)));
+            console.error(`Wrote ${result.images.length} image(s) to ${path.relative('.', imageDir) || '.'}/`);
+        }
         // Display warnings to stderr if any
         if (result.warnings.length > 0) {
             result.warnings.forEach((warning) => {
@@ -18,23 +61,21 @@ program
             });
             console.error(''); // Empty line for separation
         }
-        // Output markdown to stdout
-        console.log(result.markdown);
+        // Write the Markdown to the requested file, or stdout by default.
+        if (options.output) {
+            await mkdir(path.dirname(options.output), { recursive: true });
+            await writeFile(options.output, result.markdown);
+            console.error(`Wrote Markdown to ${options.output}`);
+        }
+        else {
+            console.log(result.markdown);
+        }
     }
     catch (error) {
-        // Handle our custom errors with user-friendly messages
-        if (error instanceof UnsupportedFileError ||
-            error instanceof FileNotFoundError ||
-            error instanceof InvalidFileError ||
-            error instanceof FilePermissionError ||
-            error instanceof ConversionError) {
-            console.error(`Error: ${error.message}`);
-            process.exit(1);
-        }
-        // Handle unexpected errors (including non-Error objects)
+        // Converter errors carry user-friendly messages; print anything else as-is
         console.error('Error:', error instanceof Error ? error.message : String(error));
         process.exit(1);
     }
-}));
-program.parse();
+});
+await program.parseAsync();
 //# sourceMappingURL=cli.js.map

package/build/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";;AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EACL,mBAAmB,EACnB,oBAAoB,EACpB,iBAAiB,EACjB,gBAAgB,EAChB,mBAAmB,EACnB,eAAe,GAChB,MAAM,WAAW,CAAC;AAEnB,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;AAC9B,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AACpB,OAAO,CAAC,WAAW,CAAC,8CAA8C,CAAC,CAAC;AACpE,OAAO;KACJ,OAAO,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;KACvC,QAAQ,CAAC,QAAQ,EAAE,8BAA8B,CAAC;KAClD,MAAM,CAAC,CAAO,IAAI,EAAE,EAAE;IACrB,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,mBAAmB,CAAC,IAAI,CAAC,CAAC;QAE/C,oCAAoC;QACpC,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC/B,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;gBAClC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;YACzB,CAAC,CAAC,CAAC;YACH,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,4BAA4B;QACjD,CAAC;QAED,4BAA4B;QAC5B,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC/B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,uDAAuD;QACvD,IACE,KAAK,YAAY,oBAAoB;YACrC,KAAK,YAAY,iBAAiB;YAClC,KAAK,YAAY,gBAAgB;YACjC,KAAK,YAAY,mBAAmB;YACpC,KAAK,YAAY,eAAe,EAChC,CAAC;YACD,OAAO,CAAC,KAAK,CAAC,UAAU,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;YACzC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;QACD,yDAAyD;QACzD,OAAO,CAAC,KAAK,CACX,QAAQ,EACR,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CACvD,CAAC;QACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC,CAAA,CAAC,CAAC;AAEL,OAAO,CAAC,KAAK,EAAE,CAAC"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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","sourcesContent":["#!/usr/bin/env node\n\nimport { Command } from 'commander';\nimport { createRequire } from 'module';\nimport { mkdir, writeFile } from 'fs/promises';\nimport path from 'path';\nimport { convertWithWarnings } from './main.js';\n\n// Read our own version from package.json. createRequire resolves relative to\n// this module, so `../package.json` points at the package root both from the\n// TypeScript source (src/) and the compiled CLI (build/) after publish. This\n// avoids JSON import attributes, which node16 module resolution would require.\nconst require = createRequire(import.meta.url);\nconst { version } = require('../package.json') as { version: string };\n\nconst program = new Command();\nprogram.name('w2m');\nprogram.description('Convert Word documents to beautiful Markdown');\nprogram.version(version);\nprogram\n  .command('convert', { isDefault: true })\n  .argument('<file>', 'The Word document to convert')\n  .option(\n    '-o, --output <file>',\n    'Write the Markdown to <file> instead of stdout. Warnings still print to ' +\n      'stderr.',\n  )\n  .option(\n    '--strip-images',\n    'Remove images instead of embedding them as base64 data URIs',\n  )\n  .option(\n    '--image-dir <dir>',\n    'Extract images to <dir> and link them relatively, instead of embedding ' +\n      'them as base64. Links resolve relative to where you save the Markdown.',\n  )\n  .option(\n    '--bullet-lists',\n    'Convert numbered lists to bullets rather than keeping them as 1./2./3.',\n  )\n  .option(\n    '--underline',\n    'Preserve underlined text as inline <u> tags (dropped by default)',\n  )\n  .option(\n    '--preserve-footnotes',\n    'Keep Word footnotes as raw <sup> links and a numbered note list instead ' +\n      'of converting them to GFM [^1] footnotes',\n  )\n  .action(async (file, options) => {\n    try {\n      // --image-dir (extract) takes precedence over --strip-images.\n      if (options.imageDir && options.stripImages) {\n        console.error('Ignoring --strip-images because --image-dir is set.');\n      }\n      const images = options.imageDir\n        ? 'extract'\n        : options.stripImages\n          ? 'strip'\n          : 'inline';\n      const result = await convertWithWarnings(file, {\n        images,\n        imageDir: options.imageDir,\n        numberedLists: options.bulletLists ? 'bullets' : 'ordered',\n        underline: options.underline ? 'preserve' : 'ignore',\n        footnotes: options.preserveFootnotes ? 'preserve' : 'gfm',\n      });\n\n      // Write extracted images to disk before emitting the Markdown that links\n      // them. The links are relative to the Markdown file, so resolve them\n      // against its directory (the working directory when writing to stdout).\n      if (result.images && result.images.length > 0) {\n        const markdownDir = options.output ? path.dirname(options.output) : '.';\n        const imageDir = path.resolve(markdownDir, options.imageDir);\n        await mkdir(imageDir, { recursive: true });\n        await Promise.all(\n          result.images.map((image) =>\n            writeFile(path.resolve(markdownDir, image.path), image.bytes),\n          ),\n        );\n        console.error(\n          `Wrote ${result.images.length} image(s) to ${path.relative('.', imageDir) || '.'}/`,\n        );\n      }\n\n      // Display warnings to stderr if any\n      if (result.warnings.length > 0) {\n        result.warnings.forEach((warning) => {\n          console.error(warning);\n        });\n        console.error(''); // Empty line for separation\n      }\n\n      // Write the Markdown to the requested file, or stdout by default.\n      if (options.output) {\n        await mkdir(path.dirname(options.output), { recursive: true });\n        await writeFile(options.output, result.markdown);\n        console.error(`Wrote Markdown to ${options.output}`);\n      } else {\n        console.log(result.markdown);\n      }\n    } catch (error) {\n      // Converter errors carry user-friendly messages; print anything else as-is\n      console.error(\n        'Error:',\n        error instanceof Error ? error.message : String(error),\n      );\n      process.exit(1);\n    }\n  });\n\nawait program.parseAsync();\n"]}

package/build/main.d.ts

@@ -0,0 +1,88 @@
+export interface ConvertOptions {
+    mammoth?: object;
+    turndown?: object;
+    /**
+     * How to handle images. `'inline'` (default) keeps Mammoth's base64 data
+     * URIs; `'strip'` removes images entirely (useful to avoid multi-MB output
+     * from image-heavy documents); `'extract'` replaces each image with a
+     * relative `![](imageDir/imageN.ext)` link and returns the image bytes on
+     * `ConvertResult.images` (use `convertWithWarnings` to retrieve them).
+     */
+    images?: 'inline' | 'strip' | 'extract';
+    /**
+     * Directory prefix used for extracted image links and paths (default
+     * `'images'`). Only applies when `images` is `'extract'`. The same value is
+     * used for the Markdown link (`![](imageDir/imageN.ext)`) and the returned
+     * `ExtractedImage.path`, so links and files always agree.
+     */
+    imageDir?: string;
+    /**
+     * How to render Word's numbered lists. `'ordered'` (default) keeps them as
+     * `1.`/`2.`/… ordered lists; `'bullets'` converts them to bullet lists
+     * (matching the classic word-to-markdown behavior).
+     */
+    numberedLists?: 'bullets' | 'ordered';
+    /**
+     * How to handle underlined text. `'ignore'` (default) drops the underline —
+     * Mammoth's default, since underlines are easily confused with links in HTML.
+     * `'preserve'` keeps it as an inline `<u>…</u>` tag (rendered by GitHub-flavored
+     * Markdown). Note that superscript and subscript are always preserved as
+     * `<sup>`/`<sub>` and need no option.
+     */
+    underline?: 'ignore' | 'preserve';
+    /**
+     * How to render Word's footnotes and endnotes. `'gfm'` (default) rewrites
+     * Mammoth's superscript reference links plus trailing note list into standard
+     * GitHub-flavored/Pandoc footnote syntax (`[^1]` references and `[^1]:`
+     * definitions). `'preserve'` keeps Mammoth's raw `<sup>` links and numbered
+     * note list (useful for CommonMark targets that don't support `[^1]`).
+     */
+    footnotes?: 'gfm' | 'preserve';
+}
+export interface ExtractedImage {
+    path: string;
+    contentType: string;
+    bytes: Uint8Array;
+}
+export interface ConvertResult {
+    markdown: string;
+    warnings: string[];
+    /** Present (possibly empty) when converting with `images: 'extract'`. */
+    images?: ExtractedImage[];
+}
+export interface DocumentProperties {
+    sensitivity?: string;
+    confidentiality?: string;
+    encryption?: boolean;
+    protection?: boolean;
+}
+export declare class WordToMarkdownError extends Error {
+}
+export declare class UnsupportedFileError extends WordToMarkdownError {
+    constructor(message: string);
+}
+export declare class FileNotFoundError extends WordToMarkdownError {
+    constructor(filePath?: string);
+}
+export declare class InvalidFileError extends WordToMarkdownError {
+    constructor(filePath?: string);
+}
+export declare class FilePermissionError extends WordToMarkdownError {
+    constructor(filePath?: string);
+}
+export declare class ConversionError extends WordToMarkdownError {
+    constructor(message: string, originalError?: Error);
+}
+export declare function validateFileExtension(filePath: string): void;
+export declare function htmlToMd(html: string, options?: object, keepTags?: string[]): string;
+export declare function extractDocumentProperties(input: string | ArrayBuffer): Promise<DocumentProperties>;
+export declare function generateWarnings(properties: DocumentProperties): string[];
+interface MammothMessage {
+    type: string;
+    message: string;
+}
+export declare function extensionForContentType(contentType: string): string;
+export declare function extractMammothWarnings(messages: readonly MammothMessage[]): string[];
+export declare function convertWithWarnings(input: string | ArrayBuffer, options?: ConvertOptions): Promise<ConvertResult>;
+export default function convert(input: string | ArrayBuffer, options?: ConvertOptions): Promise<string>;
+export {};