@giraffesyo/downmark

中文文档
0.10.1发布于 2026/10/22Apache-2.0TypeScriptESM + CJS零依赖构建来源已验证近 30 天下载 2933

Convert PDF, DOC, DOCX, XLSX, PPTX, HTML, CSV, ZIP, and plaintext documents to Markdown. Pure WebAssembly; runs in Node and the browser with zero dependencies.

原始使用文档
文档目录14 节
  1. Install
  2. Two implementations, one API
  3. Usage (Node)
  4. Usage (browser)
  5. API
  6. convert(data, options?) → Promise<{ markdown, title, warnin…
  7. OCR for scanned PDFs
  8. binaryPath() → string | null
  9. canConvert(hints) → Promise<boolean>
  10. init(source?) → Promise<void>
  11. version() → Promise<string>
  12. Errors
  13. Notes and limitations
  14. Development

@giraffesyo/downmark

Convert documents to Markdown in Node.js and the browser: PDF, DOCX, XLSX, PPTX, DOC (Word 97–2003), HTML, CSV, ZIP archives, and plaintext. This is the pure-Go downmark library, wrapped in a small TypeScript API. Everything runs locally, no network calls.

Install

npm install @giraffesyo/downmark

Requires Node ≥ 18 or any modern browser.

Two implementations, one API

convert() runs the same Go code either way, but there are two builds of it and the package picks between them per host:

  • The native binary, which ships inside a per-platform package (@giraffesyo/downmark-linux-x64 and five siblings) that this package declares as an optional dependency. npm installs only the one matching the host's os/cpu and skips the rest. There is no download step and no postinstall script: the binary is inside the tarball, so npm install works behind a proxy and on an air-gapped cluster, pnpm deploy carries it, and the lockfile pins it.
  • The WebAssembly build, bundled in this package, used wherever no platform package applies — browsers, an unlisted platform, an installer run with --omit=optional.

They return the same { markdown, title, warnings } for the same input. The native path is faster, runs the conversion in another process instead of on the event loop, and is the only one that can do OCR. Nothing else about your code changes.

import { binaryPath } from "@giraffesyo/downmark";

binaryPath(); // "/…/node_modules/@giraffesyo/downmark-darwin-arm64/bin/downmark", or null on wasm

Supported platforms: linux, darwin, and win32 on x64 and arm64. The Go binaries are static, so the linux packages cover glibc and musl (Alpine) alike.

Set DOWNMARK_FORCE_WASM=1, or call init({ preferWasm: true }), to ignore an installed binary — useful for comparing the two. DOWNMARK_BIN=/path/to/downmark points at a binary of your own; if it does not exist the call throws rather than quietly falling back.

Usage (Node)

import { readFile } from "node:fs/promises";
import { convert } from "@giraffesyo/downmark";

const data = await readFile("report.docx");
const { markdown, title } = await convert(data, { filename: "report.docx" });
console.log(markdown);

CommonJS works too:

const { convert } = require("@giraffesyo/downmark");

On the native path each conversion spawns the binary (about 5–10 ms of process overhead) and nothing is loaded into your process. On the wasm path the module is loaded lazily on the first call and cached, so subsequent calls reuse the same instance.

Usage (browser)

import { convert } from "@giraffesyo/downmark";

const file = input.files[0];
const data = new Uint8Array(await file.arrayBuffer());
const { markdown } = await convert(data, { filename: file.name });

Browsers have no process to spawn, so this is always the wasm build.

The browser build fetches downmark.wasm relative to the module via new URL("./downmark.wasm", import.meta.url). Bundlers that understand that pattern (Vite, webpack 5, Rollup with the url plugin) copy the wasm into the build output automatically.

If your bundler doesn't, point init() at the wasm explicitly before the first call:

// Vite
import wasmUrl from "@giraffesyo/downmark/downmark.wasm?url";
import { init, convert } from "@giraffesyo/downmark";

await init(wasmUrl);

init() accepts a string URL/path, a URL, an ArrayBuffer/Uint8Array, a Response, or a precompiled WebAssembly.Module.

No bundler at all? See example/browser.html for a plain <script type="module"> page.

Serving tip: the wasm is ~12 MB uncompressed. Serve it with Content-Encoding: br or gzip (≈4–6 MB over the wire) and a Content-Type: application/wasm header so WebAssembly.instantiateStreaming kicks in (the package falls back to buffering if the MIME type is wrong).

API

convert(data, options?) → Promise<{ markdown, title, warnings }>

data is a Uint8Array or ArrayBuffer. All options are optional, but the more hints you give the better the format detection:

OptionTypeMeaning
filenamestringBase name of the source file, e.g. "report.docx"
mimeTypestringMedia type without parameters, e.g. "application/pdf"
extensionstringFile extension (normalized to lowercase with a leading dot)
charsetstringIANA charset name for text inputs, e.g. "shift_jis"
keepDataUrisbooleanKeep full data: URIs (HTML) / embed images as data URIs (DOCX)
resultLimitnumberReject results larger than this many bytes with RESULT_TOO_LARGE
ocrobjectRead scanned PDF pages with an OCR engine (below); native binary only

warnings reports what the conversion lost, and is empty when it lost nothing. A conversion that returns warnings still succeeded — the Markdown is usable, it just is not everything the input held.

const { markdown, warnings } = await convert(data, { filename: "scan.pdf" });
for (const w of warnings) {
  // { converter: "pdf", code: "incomplete", location: "page 12", message: "..." }
  console.warn(`${w.code}: ${w.message}`);
}

code is either "incomplete" (content the input held is missing from the output) or "skipped" (a whole unit was never attempted).

OCR for scanned PDFs

Scanned pages hold images, not text, so there is nothing to extract from them. Pass ocr to hand those pages to an OCR engine instead:

const { markdown } = await convert(data, {
  filename: "scan.pdf",
  ocr: { engine: "tesseract", lang: "eng", maxPages: 30 },
});
FieldTypeMeaning
engine"tesseract"Required. The engine to run; it must be installed
binstringRun this executable instead of the one on PATH
langstringLanguage in tesseract's syntax, e.g. "eng" or "eng+deu"
minConfidencenumberDrop words below this, on tesseract's 0–100 scale
policy"textless" | "thin" | "images"Pages with no text of their own (default), also a scan under a typed header, or every page painting an image
minGlyphsnumberWith policy: "thin", the glyphs a page needs to count as typeset; 50 by default
maxPagesnumberOCR at most this many pages per document; 0 for no limit
pageTimeoutMsnumberGive up on one page after this long
timeoutMsnumberGive up on the whole document's OCR after this long

A page can be a scan without being textless: a fax or a signed form carries a typed header — a date stamp, a routing line, a page number — over an image of the body, and extracts as that header alone. policy: "thin" reads those as well, handing the engine any page with fewer than minGlyphs glyphs that paints an image, while leaving pages with a text layer of their own alone. policy: "images" reads every page painting an image, figures in typeset documents included.

downmark ships no OCR engine: engine: "tesseract" runs a tesseract you installed yourself. OCR costs roughly a second a page, which is why it is off unless asked for and why the budgets are there.

Pages OCR filled in are marked in the Markdown with an HTML comment (<!-- downmark: page 1 includes OCR text -->): OCR text is a reading of the ink rather than the document's own characters, and a consumer that cannot tell the two apart cannot weigh them differently.

This needs the native binary — wasm cannot execute a program. Where none is installed, passing ocr rejects with NATIVE_REQUIRED rather than returning a document quietly missing its scanned pages.

binaryPath() → string | null

The native binary the next convert() would run, or null when this host falls back to the wasm. For callers who would rather exec the CLI themselves — it accepts -json and writes the same object this package returns.

canConvert(hints) → Promise<boolean>

Whether a format-specific converter claims the format described by the hints (judged from hints alone, with no content sniffing). false doesn't mean convert() must fail; it may still classify the input by its bytes or fall back to plaintext.

init(source?) → Promise<void>

Optional, and about the wasm implementation only. convert()/canConvert() initialize implicitly; call init() to override where the wasm comes from (see the bundler recipe above), in which case it must run before the first conversion. On a host using the native binary, nothing needs it.

It also accepts an options object:

await init({ wasm: wasmUrl, preferWasm: true });

preferWasm: true makes every conversion use the wasm even where a platform package is installed.

version() → Promise<string>

The downmark version the wasm was built from.

canConvert() and version() answer from the wasm even where the native binary is installed, and so pay for loading it. A caller on the native path that wants neither can skip both: convert() classifies the input itself, and binaryPath() names a binary that answers -version.

Errors

All failures reject with a DownmarkError carrying a code:

CodeMeaning
UNSUPPORTED_FORMATNo converter accepted the input under any interpretation
INPUT_TOO_LARGEA converter's hard input budget was exceeded
RESULT_TOO_LARGEThe result exceeded resultLimit
CONVERSION_FAILEDConverters accepted the input but every attempt failed
NATIVE_REQUIREDThe call needs the native binary and this host has none
INTERNALBad arguments or an unexpected internal failure

CONVERSION_FAILED rejections are ConversionFailedError instances with an attempts array listing each converter that tried and why it failed:

import { convert, ConversionFailedError } from "@giraffesyo/downmark";

try {
  await convert(data, { filename: "broken.pdf" });
} catch (err) {
  if (err instanceof ConversionFailedError) {
    for (const a of err.attempts) console.error(`${a.converter}: ${a.message}`);
  }
}

Notes and limitations

  • On wasm, conversion is CPU-bound and single-threaded. A big PDF blocks the thread it runs on, so in a browser UI, run conversions inside a Web Worker to keep the page responsive. There is no timeout option because a busy wasm instance can't be preempted. The native path does not have this problem: the work happens in another process, and the event loop stays free.
  • Very large XLSX parts: a workbook containing any single internal part larger than 16 MiB triggers the underlying Excel library's spill-to-disk path, which fails on wasm (no filesystem). Such files reject with CONVERSION_FAILED.
  • The wasm instance is shared per process/page. Conversions are safe to issue concurrently, but they execute one at a time. Native conversions are separate processes and do run in parallel.
  • The platform packages are an implementation detail. Depend on @giraffesyo/downmark; never on @giraffesyo/downmark-<platform> directly.

Development

Built from the repo root:

make js-test   # build wasm + TS + the binary, run the Node test suite

make wasm compiles wasm/main.go to js/dist/downmark.wasm and refreshes js/vendor/wasm_exec.js from the local Go toolchain. make js-bin builds cmd/downmark into js/.bin, which is what the native tests run; without it they skip.

The platform packages are built at release time, not committed:

goreleaser build --snapshot --clean            # dist/downmark_<goos>_<goarch>*/
node js/scripts/stage-npm-release.mjs --version 1.2.3

That writes js/npm/<platform>/ from those binaries and stamps the version and the six optionalDependencies into js/package.json. The dependencies are generated rather than committed because npm ci validates package.json against the lockfile, and a release commit names versions that are not published yet — so every clean install would fail. Neither output is meant to be committed; .github/scripts/check-npm-packages.sh runs the same script in CI to keep it honest.

版本与发布记录

@giraffesyo/downmark 共发布 9 个版本,首次发布于 2026/08/19;过去 12 个月发布了 9 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.10.1latest2026/10/2225 天前
0.10.02026/08/252 个月前
0.9.02026/08/242 个月前
0.8.02026/08/222 个月前
0.7.02026/08/222 个月前
0.6.12026/08/222 个月前

关于 @giraffesyo/downmark 的常见问题

@giraffesyo/downmark 是什么?

Convert PDF, DOC, DOCX, XLSX, PPTX, HTML, CSV, ZIP, and plaintext documents to Markdown. Pure WebAssembly; runs in Node and the browser with zero dependencies.

如何安装 @giraffesyo/downmark?

在项目目录运行 npm install @giraffesyo/downmark,或使用 pnpm add / yarn add / bun add。

@giraffesyo/downmark 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@giraffesyo/downmark 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@giraffesyo/downmark 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=18。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@giraffesyo/downmark 可以商用吗?

@giraffesyo/downmark 使用 Apache-2.0 许可。宽松许可:允许商业使用、修改和再分发,并附带明确的专利授权;分发时需保留许可与 NOTICE 文件,修改过的文件要注明改动。以上为概括,不构成法律意见,请以许可原文为准。

@giraffesyo/downmark 的下载量有多少?

根据 npm 官方下载统计,@giraffesyo/downmark 在 2026/10/17 – 2026/11/15 这 30 天内被下载 2,933 次,日均约 98 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@giraffesyo/downmark 还在维护吗?

最新版本 0.10.1 发布于 2026/10/22(25 天前);至今共发布 9 个版本,其中过去 12 个月发布了 9 个;首次发布于 2026/08/19。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。