word-to-markdown 0.3.0 → 0.5.0

package/README.md

@@ -3,7 +3,7 @@
 [![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: ISC](https://img.shields.io/npm/l/word-to-markdown.svg)](https://github.com/benbalter/word-to-markdown-js/blob/main/LICENSE)
+[![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).
 
@@ -23,7 +23,7 @@ npx word-to-markdown input.docx > output.md
 - Nested lists
 - Tables
 - Links
-- Footnotes and endnotes
+- Footnotes and endnotes — converted to GFM/Pandoc `[^1]` footnotes
 - Images — embedded inline as base64 data URIs, or extracted to files
 
 ### Notes and limitations
@@ -41,6 +41,14 @@ npx word-to-markdown input.docx > output.md
 - **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.
@@ -81,16 +89,23 @@ The converted Markdown is written to **stdout** and any document warnings (encry
 
 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`.
+  `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 and requires Node 22.13 or later.
+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
@@ -108,7 +123,7 @@ const { markdown, warnings } = await convertWithWarnings(
 );
 ```
 
-Both functions accept either a file-path string (in Node) or an `ArrayBuffer` (in the browser), so the same code runs in either environment:
+Both functions accept either a file-path string (Node) or an `ArrayBuffer` (Node or the browser):
 
 ```js
 const { markdown } = await convertWithWarnings(arrayBuffer);
@@ -119,12 +134,13 @@ const { markdown } = await convertWithWarnings(arrayBuffer);
 - **`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` (browser). `options` is optional:
+`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
@@ -137,7 +153,7 @@ const { markdown, images } = await convertWithWarnings('file.docx', {
 
 ### Error handling
 
-Conversion throws typed errors so you can respond to each failure precisely:
+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, {
@@ -152,13 +168,13 @@ try {
   const markdown = await convert('path/to/your/file.docx');
 } catch (error) {
   if (error instanceof UnsupportedFileError) {
-    // e.g. a .doc file — only .docx is supported
+    // a .doc or password-protected file — only unprotected .docx is supported
   } else if (error instanceof FileNotFoundError) {
-    // the path doesn't exist
+    // 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
+    // not a valid or parseable .docx (or the path is a directory)
   } else if (error instanceof FilePermissionError) {
-    // the file couldn't be read
+    // 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
   }
@@ -190,6 +206,13 @@ To self-host the static site using Docker Compose:
 3. Run `docker compose up -d`
 4. Access at http://localhost:3000
 
+This serves `dist/` with plain nginx, so it skips what the Cloudflare Worker and
+`public/_headers` add in production: the `Accept-Language` redirect on `/`, the
+`/api/event` counter (requests to it 404), the security headers, and long-lived
+caching for `/_astro/*`. Conversion itself runs in the browser and works the
+same. For a production-like local setup, run `npm run build` and then
+`npx wrangler dev`.
+
 ## More context
 
 See the README of [the original Word to Markdown](https://github.com/benbalter/word-to-markdown?tab=readme-ov-file#the-problem) for the project's motivation.

package/build/cli.js

@@ -1,39 +1,59 @@
 #!/usr/bin/env node
-import { __awaiter } from "tslib";
 import { Command } from 'commander';
+import { createRequire } from 'module';
 import { mkdir, writeFile } from 'fs/promises';
-import { convertWithWarnings, UnsupportedFileError, FileNotFoundError, InvalidFileError, FilePermissionError, ConversionError, } from './main.js';
+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')
+    .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)')
-    .action((file, options) => __awaiter(void 0, void 0, void 0, function* () {
+    .option('--preserve-footnotes', 'Keep Word footnotes as raw <sup> links and a numbered note list instead ' +
+    'of converting them to GFM [^1] footnotes')
+    .option('--verbose', 'On failure, also print the underlying error and stack trace')
+    .action(async (file, options) => {
     try {
         // --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 = yield convertWithWarnings(file, {
+        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. Paths are already prefixed with the requested directory.
+        // 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) {
-            yield mkdir(options.imageDir, { recursive: true });
-            yield Promise.all(result.images.map((image) => writeFile(image.path, image.bytes)));
-            console.error(`Wrote ${result.images.length} image(s) to ${options.imageDir}/`);
+            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) {
@@ -42,23 +62,30 @@ 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 });
+            // End with a newline, as stdout (console.log) does (markdownlint MD047).
+            await writeFile(options.output, `${result.markdown}\n`);
+            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));
+        // The friendly message hides the root cause (e.g. a ConversionError
+        // wrapping a mammoth failure); --verbose shows it for bug reports.
+        if (options.verbose && error instanceof Error) {
+            console.error('');
+            console.error(error.stack);
+            if (error.cause)
+                console.error('Caused by:', error.cause);
+        }
         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":"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"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AACvC,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAEhD,6EAA6E;AAC7E,6EAA6E;AAC7E,6EAA6E;AAC7E,+EAA+E;AAC/E,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC/C,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,iBAAiB,CAAwB,CAAC;AAEtE,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,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;AACzB,OAAO;KACJ,OAAO,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;KACvC,QAAQ,CAAC,QAAQ,EAAE,8BAA8B,CAAC;KAClD,MAAM,CACL,qBAAqB,EACrB,0EAA0E;IACxE,SAAS,CACZ;KACA,MAAM,CACL,gBAAgB,EAChB,6DAA6D,CAC9D;KACA,MAAM,CACL,mBAAmB,EACnB,yEAAyE;IACvE,wEAAwE,CAC3E;KACA,MAAM,CACL,gBAAgB,EAChB,wEAAwE,CACzE;KACA,MAAM,CACL,aAAa,EACb,kEAAkE,CACnE;KACA,MAAM,CACL,sBAAsB,EACtB,0EAA0E;IACxE,0CAA0C,CAC7C;KACA,MAAM,CACL,WAAW,EACX,6DAA6D,CAC9D;KACA,MAAM,CAAC,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE;IAC9B,IAAI,CAAC;QACH,8DAA8D;QAC9D,IAAI,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;YAC5C,OAAO,CAAC,KAAK,CAAC,qDAAqD,CAAC,CAAC;QACvE,CAAC;QACD,MAAM,MAAM,GAAG,OAAO,CAAC,QAAQ;YAC7B,CAAC,CAAC,SAAS;YACX,CAAC,CAAC,OAAO,CAAC,WAAW;gBACnB,CAAC,CAAC,OAAO;gBACT,CAAC,CAAC,QAAQ,CAAC;QACf,MAAM,MAAM,GAAG,MAAM,mBAAmB,CAAC,IAAI,EAAE;YAC7C,MAAM;YACN,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,aAAa,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS;YAC1D,SAAS,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,QAAQ;YACpD,SAAS,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK;SAC1D,CAAC,CAAC;QAEH,yEAAyE;QACzE,qEAAqE;QACrE,wEAAwE;QACxE,IAAI,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC9C,MAAM,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;YACxE,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;YAC7D,MAAM,KAAK,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YAC3C,MAAM,OAAO,CAAC,GAAG,CACf,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAC1B,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,CAC9D,CACF,CAAC;YACF,OAAO,CAAC,KAAK,CACX,SAAS,MAAM,CAAC,MAAM,CAAC,MAAM,gBAAgB,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC,IAAI,GAAG,GAAG,CACpF,CAAC;QACJ,CAAC;QAED,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,kEAAkE;QAClE,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;YACnB,MAAM,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YAC/D,yEAAyE;YACzE,MAAM,SAAS,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,MAAM,CAAC,QAAQ,IAAI,CAAC,CAAC;YACxD,OAAO,CAAC,KAAK,CAAC,qBAAqB,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;QACvD,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC/B,CAAC;IACH,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,2EAA2E;QAC3E,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,oEAAoE;QACpE,mEAAmE;QACnE,IAAI,OAAO,CAAC,OAAO,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;YAC9C,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;YAClB,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YAC3B,IAAI,KAAK,CAAC,KAAK;gBAAE,OAAO,CAAC,KAAK,CAAC,YAAY,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;QAC5D,CAAC;QACD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC,CAAC,CAAC;AAEL,MAAM,OAAO,CAAC,UAAU,EAAE,CAAC","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  .option(\n    '--verbose',\n    'On failure, also print the underlying error and stack trace',\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        // End with a newline, as stdout (console.log) does (markdownlint MD047).\n        await writeFile(options.output, `${result.markdown}\\n`);\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      // The friendly message hides the root cause (e.g. a ConversionError\n      // wrapping a mammoth failure); --verbose shows it for bug reports.\n      if (options.verbose && error instanceof Error) {\n        console.error('');\n        console.error(error.stack);\n        if (error.cause) console.error('Caused by:', error.cause);\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 {
+    constructor(message?: string, options?: ErrorOptions);
+}
+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, cause?: unknown);
+}
+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[], gfmFootnotes?: boolean): 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 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 {};