@giraffesyo/downmark

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

将 PDF, DOC, DOCX, XLSX, PPTX, HTML, CSV, ZIP, 和纯文本文档转换为Markdown. 纯WebAssembly;在节点和浏览器中运行,依赖度为零.

中文使用文档
文档目录14 节
  1. 安装
  2. 两次执行,一次API
  3. 用法(节点)
  4. 用法 (浏览器)
  5. API 密码
  6. convert(data, options?) → Promise<{ markdown, title, warnin…
  7. 扫描的 PDF OCR
  8. binaryPath() → string | null
  9. canConvert(hints) → Promise<boolean>
  10. init(source?) → Promise<void>
  11. version() → Promise<string>
  12. 错误
  13. 说明和限制
  14. 发展

@giraffesyo/ 下标记

在Node.js和浏览器中将文档转换为Markdown:PDF,DOCX,XLSX,PPTX,DOC(Word 97–2003),HTML,CSV,ZIP档案,和Plaintext. 这是纯粹的去 下标记 库,用一个小的 TypeScript API 包裹。 一切都在当地运行,没有网络呼叫.

安装

npm install @giraffesyo/downmark

需要18号节点或任何现代浏览器.

两次执行,一次API

convert() 运行相同的 Go 代码 无论是哪种方式, 但有两个建筑它 和包之间选择每个主机 :

  • 本地二进制,每平面包件内装船 (单位:千美元)@giraffesyo/downmark-linux-x64 5个兄弟姐妹) 宣布为可选依赖。 npm 只安装一个匹配 主办单位 os编号 :cpu 并跳过其余。 没有下载步骤也没有 邮购脚本: 二进制在柏油球内,所以 npm install 在一个代理 和一个空中集束, pnpm deploy 携带 锁被钉住.
  • 网络大会建设,捆绑在这个包中,在没有的情况下使用 应用平台软件包——浏览器,未列出的平台,安装器 运行与 --omit=optional。 。 。 .

他们也一样回来 { markdown, title, warnings } 对于相同的输入。 这个 本地路径更快, 运行转换到另一个进程而不是打开 事件循环,是唯一可以做到的 OCR (英语)。 。 。 . 没有其他关于你的代码改变.

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

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

所支持的平台:linux,darwin,并使用x64和arm64的win32. 前进 二进制是静态的,所以Linux包覆盖了glibc和musl(高山) 一样.

设定 DOWNMARK_FORCE_WASM=1,或打电话 init({ preferWasm: true }),忽略 一个已安装的二进制——用于比较两者. DOWNMARK_BIN=/path/to/downmark 在您自己的二进制中点出; 如果不存在, 调用比方 而不是悄悄地掉下来.

用法(节点)

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);

通用JS同样工作:

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

在原生路径上,每次转换都产出二进制(约5-10 ms of ),而没有任何内容被载入您的进程。 在原地的道路上 模块在第一次呼叫时被懒散地装入并被缓存,所以随后 调用重复使用同一实例.

用法 (浏览器)

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 });

浏览器没有产入过程,所以这总是被堆积而成.

浏览器构建抓取 downmark.wasm 相对于通过 new URL("./downmark.wasm", import.meta.url). Bundlers 了解该模式的 (Vite, Webpack 5, Rollup with the url 插件) 自动将被体复制到构建输出中.

如果你的捆绑者不这样做,指 init() 在第一次通话前

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

await init(wasmUrl);

init() 接受字符串 URL/ path, a URL,一个 ArrayBuffer编号 :Uint8Array页:1 Response,或预编译 WebAssembly.Module。 。 。 .

没有捆绑? 见 example/browser.html 为平地 <script type="module"> 页 次.

服务提示 : 原为~12 MB 未压缩。 给它服务 Content-Encoding: br 或者说 gzip (≈-4-6 MB过线)和a Content-Type: application/wasm 标题如此 WebAssembly.instantiateStreaming 踢入( 如果MIME 类型错误, 包会回到缓冲) .

API 密码

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

data 是一个 Uint8Array 或者说 ArrayBuffer。所有选项都是可选的,但您给出的提示越多,格式检测就越好:

选项类型含义
filenamestring源文件的基名,例如:. "report.docx"
mimeTypestring无参数的媒体类型,例如:. "application/pdf"
extensionstring文件扩展名( 正常化为小写并带有前缀)
charsetstringIANA 字符集名称用于文本输入, 例如 . "shift_jis"
keepDataUrisboolean饱满 data: URIs (HTML) / 嵌入图像作为数据 URIs (DOCX)
resultLimitnumber拒绝大于此数字节的结果 RESULT_TOO_LARGE
ocrobject使用 OCR 引擎读取扫描的 PDF 页面(下级; 仅本地二进制

warnings 报告转换损失,当转换损失时为空 没什么 返回警告的转换仍然成功——Markdown是 有用,但并不是所有的输入.

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 无论是 "incomplete" (所持有的输入内容在 产出)或 "skipped" (整个单位从未尝试).

扫描的 PDF OCR

被扫描的页面持有图像,而不是文本,所以从 他们。 过 ocr 将这些页面交给OCR引擎:

const { markdown } = await convert(data, {
  filename: "scan.pdf",
  ocr: { engine: "tesseract", lang: "eng", maxPages: 30 },
});
外地类型含义
engine"tesseract"要求。 要运行的引擎; 必须安装
binstring运行此可执行文件而不是打开 PATH
langstring语法中的语言,例如:. "eng" 或者说 "eng+deu"
minConfidencenumber将单词从此下移, 在 Tesseract 的 0- 100 比例上
policy"textless" | "thin" | "images"没有自己文本的页面( 默认) , 也可以在打字头下扫描, 或者每页画一幅图像
minGlyphsnumber与 policy: "thin",一个页面需要算作排字; 50 默认
maxPagesnumber每个文件最多有这么多页的OCR; 0 无限制
pageTimeoutMsnumber这么长时间后放弃一页
timeoutMsnumber这么长时间之后 放弃整个文件的OCR

页面可以是扫描而不带文本:传真或签名表格 搭载打字头——日期戳,出行行,页码—— 在身体的一幅图上 单独取出那个头像. policy: "thin" 也读这些,将任何页面交给引擎 少于 minGlyphs 画出图像的格言,同时留下页 仅用自己的文本层. policy: "images" 读取每一页 绘制图像,包括类型文档中的数字.

没有 OCR 引擎 : engine: "tesseract" 运行 a 语法 您已安装 你自己来 OCR大约每页花费一秒钟, 这就是为什么它关闭,除非 问及预算为何存在.

填入的页面 OCR 在 Markdown 中标出 HTML 注释 (单位:千美元)<!-- downmark: page 1 includes OCR text -->:OCR文本是读取 墨水而不是文档本身的字符, 以及不能 告诉两者不能有不同的重量.

这需要本地的二进制——dem不能执行一个程序. 没有 已安装, 已通过 ocr 拒绝方式 NATIVE_REQUIRED 而不是说 返回时会悄悄地丢失其扫描页.

binaryPath() → string | null

下一个本地二进制 convert() 会运行,或 null 当此主机 滚回原地去 对于更愿意执行CLI的来电者 他们自己接受 -json 并写入此软件包中相同的对象 返回.

canConvert(hints) → Promise<boolean>

格式特定转换器是否声称提示所描述的格式(仅从提示判断,没有内容嗅取). false 这并不意味着 convert() 必须失败;它可能仍然会按其字节对输入进行分类,或者返回到纯文本中.

init(source?) → Promise<void>

可选性,关于只执行问题. convert()编号 :canConvert() 默认初始化; 调用 init() 以覆盖原点 (见上面的 " 捆绑方 " ),在这种情况下,它必须在第一次谈判之前运行 转换。 在一个使用本地二进制的主机上,没有什么需要它.

它也接受一个选项对象:

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

preferWasm: true 使每一个转换都使用相机,即使有一个平台 软件包已安装.

version() → Promise<string>

下印版的被子从.

canConvert() 财务报告和审定财务报表 version() 从原地回答,即使当地人 安装了二进制, 并支付加载费 。 一个在本土路上的呼叫者 两者都不能跳过: convert() 分类输入本身, 财务报告和审定财务报表 binaryPath() 命名一个回答的二进制 -version。 。 。 .

错误

所有失败均以 DownmarkError 携带 code数字 :

代码含义
UNSUPPORTED_FORMAT没有转换器接受任何解释下的输入
INPUT_TOO_LARGE转换器的硬输入预算被突破
RESULT_TOO_LARGE超过结果 resultLimit
CONVERSION_FAILED转换器接受输入, 但每次尝试都失败
NATIVE_REQUIRED呼叫需要本地二进制, 而这个主机没有
INTERNAL错误的参数或出乎意料的内部失败

CONVERSION_FAILED 拒绝是 ConversionFailedError 实例 attempts 数组列出每个尝试过的转换器及其失败的原因 :

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}`);
  }
}

说明和限制

  • 在tham上,转换为CPU绑定并被单行读取. 一个大的PDF屏蔽了它运行的线程,所以在一个浏览器UI中,在一个Web Worker内部运行转换,以保持页面的响应. 没有 timeout 选项,因为忙碌的原案例不能被预先阻止。 原生路径没有这个问题:工作发生在另一个过程中,事件循环保持自由.
  • 非常大的 XLSX 部件 : 包含大于 16 MiB 的单个内部部件的工作簿会触发 Excel 库的溢出到磁盘路径, 它在 ism( 没有文件系统) 上失败 。 此类文件以 CONVERSION_FAILED。 。 。 .
  • 原物实例按进程/页数共享。 转换可以同时发布,但一次执行一次. 原生转化是独立的过程,确实平行运行.
  • 平台软件包是一个执行细节. 取决于 @giraffesyo/downmark从来没有 @giraffesyo/downmark-<platform> 直接说.

发展

从 repo 根所建 :

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

make wasm 编译 wasm/main.go 改为 js/dist/downmark.wasm 刷新时 js/vendor/wasm_exec.js 从本地的Go工具链. make js-bin 正在建设 cmd/downmark 输入 js/.bin,这是本地测试的结果;没有它,他们跳过.

平台套件在发布时间构建,没有承诺:

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

写着 js/npm/<platform>/ 从这些二进制和邮票的版本 和六个 optionalDependencies 输入 js/package.json。依赖关系 产生而不是承诺,因为 npm ci 验证 package.json 以锁定文件为对象, 并发布名称版本 ——所以每一个干净的安装都会失败. 也没有 产出意在承付; .github/scripts/check-npm-packages.sh 在CI中运行相同的脚本来保持它诚实.

版本与发布记录

@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 是什么?

将 PDF, DOC, DOCX, XLSX, PPTX, HTML, CSV, ZIP, 和纯文本文档转换为Markdown. 纯WebAssembly;在节点和浏览器中运行,依赖度为零.

如何安装 @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 和提交记录判断。