mdream

☁️ GitHub 上最快的 HTML 转 Markdown 工具。专为大语言模型优化，并支持流式处理。

[!TIP] 🎉 Mdream v1 已发布！ 请阅读 v1 发布说明。

特性

• 🧠 #1 令牌优化器：与 Turndown、node-html-markdown 和 html-to-markdown 相比，最多可减少 2 倍的令牌消耗（见#benchmarks）。相比原始 HTML，令牌数量减少 70-99%。
• 🚀 #1 最快：纯 JavaScript 和原生 Rust 实现中速度最快的转换工具。相比 Turndown（Rust NAPI 对 JavaScript），速度快达 37 倍；比 htmd（Rust 对 Rust）分别快 4.6 倍和 5 倍。使用 Rust 引擎可在约 5.2 毫秒内转换 1.8MB 的 HTML。
• 🔍 生成 Minimal 风格的 GitHub Flavored Markdown：支持 Frontmatter、嵌套结构及 HTML 标记。
• 🌊 流式处理：内存高效，适合大型文档和实时数据管道。
• ⚡ 体积小巧：压缩后核心 JavaScript 代码仅 10KB，集成 Rust WASM 引擎后为 60KB。无依赖。
• ⚙️ 多平台运行：支持 CLI 爬虫、Docker、GitHub Actions、Vite 等多种方式。

什么是 Mdream？

一个零依赖、专为大语言模型优化的 HTML 转 Markdown 工具。相比 Turndown、node-html-markdown 和 html-to-markdown，Mdream 更快、更轻量，输出经过调优，既节省令牌又易于阅读。

除了核心转换功能外，Mdream 还提供多个包，用于生成 LLM 相关工件，例如为您的网站生成 llms.txt 文件，或为任何项目准备 LLM 上下文。

Mdream 包介绍

Mdream 设计灵活，适用于各种项目和场景，提供以下多个包：

包	描述
mdream	Rust NAPI 引擎 + WASM，适用于边缘计算。性能优先，声明式配置。包含 CLI。
@mdream/js	纯 JavaScript 引擎。完全开放 Hook 接口，无原生依赖。子模块包括：/plugins、/splitter、/parse、/llms-txt、/negotiate。
@mdream/crawl	全站爬虫，可从整个网站生成 llms.txt 工件
Docker	预构建的 Docker 镜像，内置 Playwright Chrome，用于容器化网站爬取
@mdream/vite	自动为您的 Vite 站点生成 .md 文件
@mdream/nuxt	自动为 Nuxt 站点生成 .md 文件及 llms.txt 工件
@mdream/action	从您的静态 .html 输出中生成 .md 和 llms.txt 工件
Browser CDN	无需任何构建步骤，即可通过 unpkg/jsDelivr 在浏览器中直接使用 mdream

Mdream 能做什么？

curl -s https://en.wikipedia.org/wiki/Markdown \
 | npx mdream@beta --origin https://en.wikipedia.org --preset minimal \
  | tee streaming.md

curl -s https://en.wikipedia.org/wiki/Markdown \
 | npx mdream@beta --origin https://en.wikipedia.org --preset minimal \
   | glow

cat index.html \
 | npx mdream@beta --preset minimal \
  | tee streaming.md

cat index.html \
 | npx mdream@beta --preset minimal \
  | glow

# 单页 → Claude
curl -s https://react.dev/learn | npx mdream@beta --origin https://react.dev --preset minimal \
  | claude -p "explain the key concepts on this page"

# 爬取整个文档 → 总结
npx @mdream/crawl@beta "https://nuxt.com/docs/getting-started/**"
cat output/llms-full.txt | claude -p "write a getting started guide from these docs"

# 比较两个框架
diff <(curl -s https://vuejs.org/guide/introduction | npx mdream@beta --preset minimal) \
     <(curl -s https://react.dev/learn | npx mdream@beta --preset minimal) \
  | claude -p "compare these two frameworks based on their intro docs"

# JavaScript/SPA 站点（React、Vue、Angular）
npx @mdream/crawl@beta https://spa-site.com --driver playwright
cat output/llms-full.txt | claude -p "what features does this app have"

# 静态网站
npx @mdream/crawl@beta https://yoursite.com

# JavaScript/SPA 站点（React、Vue、Angular）
npx -p playwright -p @mdream/crawl@beta crawl https://spa-site.com --driver playwright

import { crawlAndGenerate } from '@mdream/crawl'
import { withMinimalPreset } from '@mdream/js/preset/minimal'
import { htmlToMarkdownSplitChunks } from '@mdream/js/splitter'
import { embed } from 'ai'

const { createTransformersJS } = await import('@built-in-ai/transformers-js')
const embeddingModel = createTransformersJS().textEmbeddingModel('Xenova/bge-base-en-v1.5')

const embeddings = []

await crawlAndGenerate({
  urls: ['https://example.com'],
  onPage: async ({ url, html, title, origin }) => {
    const chunks = htmlToMarkdownSplitChunks(html, withMinimalPreset({
      chunkSize: 1000,
      chunkOverlap: 200,
      origin,
    }))

    for (const chunk of chunks) {
      const { embedding } = await embed({ model: embeddingModel, value: chunk.content })
      embeddings.push({ url, title, content: chunk.content, embedding })
    }
  },
})

// 保存到向量数据库：await saveToVectorDB(embeddings)

import { htmlToMarkdown } from 'mdream'

const headers = []
const images = []

htmlToMarkdown(html, {
  extraction: {
    'h1, h2, h3': el => headers.push(el.textContent),
    'img[src]': el => images.push({ src: el.attributes.src, alt: el.attributes.alt }),
  },
})

import { htmlToMarkdown } from 'mdream'

// 启用所有 Clean 功能
htmlToMarkdown(html, { clean: true })

// 或选择性功能
htmlToMarkdown(html, {
  clean: {
    emptyLinks: true, // 去除 #、javascript: 链接
    emptyLinkText: true, // 移除没有文本的 [](url) 链接
    emptyImages: true, // 移除没有替代文本的 ![](url)
    redundantLinks: true, // [url](url) → url
    selfLinkHeadings: true, // ## [Title](#title) → ## Title
    fragments: true, // 移除损坏的 #anchor 链接
    urls: true, // 移除 utm_*、fbclid 等跟踪参数
  }
})

Mdream 的使用

安装

pnpm add mdream@beta

[!TIP] 使用 skilld 为此包生成 Agent Skill：

npx skilld add mdream

打包工具兼容性

mdream 包使用原生 Node.js 绑定（NAPI-RS），无法静态打包。如果您的打包工具无法解析 mdream，请将其标记为外部依赖：

Next.js / Turbopack：

// next.config.js
const nextConfig = {
  serverExternalPackages: ['mdream'],
}

Webpack / 其他打包工具：

externals: ['mdream']

[!TIP] @mdream/js 没有原生依赖，可在所有打包工具中无需配置即可使用。

[!TIP] 使用 Vite？@mdream/vite 会自动处理这个问题。

基本用法

import { htmlToMarkdown } from 'mdream'

// Rust NAPI 引擎在 Node.js 中，WASM 在边缘/浏览器运行时中
const markdown = htmlToMarkdown('<h1>Hello World</h1>')
console.log(markdown) // # Hello World

import { streamHtmlToMarkdown } from 'mdream'

const response = await fetch('https://en.wikipedia.org/wiki/Markdown')
for await (const chunk of streamHtmlToMarkdown(response.body, {
  origin: 'https://en.wikipedia.org',
  minimal: true,
})) {
  process.stdout.write(chunk)
}

完整详情请参阅 mdream 文档。

Mdream Crawl

需要在浏览器或边缘运行时中使用吗？请使用 Mdream。

@mdream/crawl 包使用 mdream 进行 Markdown 转换，爬取整个网站并生成 LLM 相关文件。

• llms.txt：针对 LLM 使用优化的整合文本文件。
• llms-full.txt：包含全面元数据和完整内容的扩展格式。
• 单独的 Markdown 文件：每个被抓取的页面都会保存为 md/ 目录中的单独 Markdown 文件。

使用方法

# 交互式
npx @mdream/crawl@beta
# 简单模式
npx @mdream/crawl@beta https://harlanzw.com

# 全局模式
npx @mdream/crawl@beta "https://nuxt.com/docs/getting-started/**"
# 获取帮助
npx @mdream/crawl@beta -h

Docker

在容器化环境中运行预装了 Playwright Chrome 的 @mdream/crawl，用于网站爬取。

# 快速启动
docker run harlanzw/mdream:latest site.com/docs/**

# 交互模式
docker run -it harlanzw/mdream:latest

# 使用 Playwright 处理 JavaScript 网站
docker run harlanzw/mdream:latest spa-site.com --driver playwright

可用镜像：

• harlanzw/mdream:latest - 最新稳定版
• ghcr.io/harlan-zw/mdream:latest - GitHub 容器注册表

完整用法、配置及构建说明请参阅 DOCKER.md。

GitHub Actions 集成

安装

pnpm add @mdream/action@beta

使用和配置方法请参阅 GitHub Actions README。

Vite 集成

安装

pnpm install @mdream/vite@beta

使用和配置方法请参阅 Vite README。

Nuxt 集成

安装

pnpm add @mdream/nuxt@beta

使用和配置方法请参阅 Nuxt 模块 README。

浏览器 CDN 使用

无需构建步骤，即可通过 CDN 直接使用 mdream。只需调用一次 init() 加载 WASM 二进制文件，然后同步使用 htmlToMarkdown()：

<script src="https://unpkg.com/mdream/dist/iife.js"></script>
<script>
  await window.mdream.init()
  const markdown = window.mdream.htmlToMarkdown('<h1>Hello</h1><p>World</p>')
  console.log(markdown) // # Hello\n\nWorld
</script>

CDN 选项：

• unpkg: https://unpkg.com/mdream/dist/iife.js
• jsDelivr: https://cdn.jsdelivr.net/npm/mdream/dist/iife.js

基准测试

JavaScript (Node.js)

纯 JS 对比。mdream 不使用任何插件，而 Turndown 使用 GFM 插件以实现等效的表格和删除线支持。

Rust（原生，release + LTO）

所有 crate 均使用 opt-level=3、LTO 和单代码生成单元编译。

Rust NAPI（Node.js 绑定）

适用于需要原生速度的 Node.js 应用程序。包含 N-API 开销。

CLI（跨语言，包含进程启动）

通过 hyperfine 进行端到端 cat file | tool > /dev/null 测试。包含进程启动开销（Node.js 约 20ms，Go/Rust 约 1ms）。

mdream 的 Rust CLI 比 Go 的 html2markdown 快 2.6 至 7.5 倍。在 1.8MB 文件上，即使是带有约 20ms 启动开销的 Node.js CLI，也比 Go 快 2.2 倍。若不考虑启动开销，原始转换速度可参考上述 JS 和 Rust 表格。

流式处理

mdream 是唯一支持流式处理的 JavaScript HTML 到 Markdown 转换器。在 Go 生态系统中，JohannesKaufmann/html-to-markdown 通过 io.Reader 支持流式处理。其他任何 JS、Rust 或 Python 转换器都不支持流式 HTML 输入。

令牌效率

启用 minimal: true 后，mdream 生成的令牌数量比原始 HTML 少多达 92%，比竞争库少多达 2 倍。

基准测试基于真实世界的 HTML，使用 Vitest bench 运行。完整的方法论和复现步骤请参阅 bench/README.md。

致谢

• ultrahtml: HTML 解析的灵感来源

许可证

根据 MIT 许可证授权。

mdream 快速上手指南

mdream 是 GitHub 上最快的 HTML 转 Markdown 转换器，专为大语言模型（LLM）优化。它支持流式处理，生成的 Markdown 标记更少（Token 效率更高），且速度远超传统工具（如 Turndown）。

环境准备

• 操作系统：Windows、macOS 或 Linux
• 运行时环境：
  • Node.js (推荐 v18+)
  • 若使用 Rust 原生版本需安装 Rust 工具链（通常 npx 会自动处理预编译二进制）
• 包管理器：npm、pnpm 或 yarn

提示：国内开发者如遇网络问题，可配置国内镜像源加速安装：

# pnpm
pnpm config set registry https://registry.npmmirror.com
# npm
npm config set registry https://registry.npmmirror.com

安装步骤

方式一：作为依赖包安装（推荐用于项目集成）

pnpm add mdream@beta
# 或
npm install mdream@beta

注意：mdream 核心包包含 Native Rust 绑定。如果你的构建工具（如 Next.js/Turbopack, Webpack）报错无法解析，请将其标记为外部依赖：

Next.js (next.config.js):

const nextConfig = {
  serverExternalPackages: ['mdream'],
}

Webpack:

externals: ['mdream']

若希望完全避免原生依赖，可安装纯 JS 版本：pnpm add @mdream/js

方式二：命令行直接使用（无需安装）

你可以直接通过 npx 运行，无需本地安装：

npx mdream@beta --help

基本使用

1. 命令行转换 (CLI)

将本地 HTML 文件转换为 Markdown：

cat index.html | npx mdream@beta --preset minimal | tee output.md

将网页 URL 转换为 Markdown（自动修复相对路径）：

curl -s https://en.wikipedia.org/wiki/Markdown \
 | npx mdream@beta --origin https://en.wikipedia.org --preset minimal \
 | tee streaming.md

提示：配合 glow 可在终端美化输出效果。

2. 代码集成 (Node.js)

在项目中导入并使用，开启 clean 模式以优化 Token 用量：

import { htmlToMarkdown } from 'mdream'

const html = '<h1>Hello</h1><p>World</p>'

// 基础用法
const markdown = htmlToMarkdown(html)

// 优化模式：自动清理无用链接、追踪参数等，减少 Token 消耗
const optimized = htmlToMarkdown(html, { 
  clean: true 
})

console.log(optimized)

3. 高级场景：提取特定内容

在转换过程中提取标题或图片信息：

import { htmlToMarkdown } from 'mdream'

const headers = []
const images = []

htmlToMarkdown(html, {
  extraction: {
    'h1, h2, h3': el => headers.push(el.textContent),
    'img[src]': el => images.push({ 
      src: el.attributes.src, 
      alt: el.attributes.alt 
    }),
  },
})

4. 为 LLM 生成上下文 (llms.txt)

使用爬虫包为整个网站生成适合 AI 阅读的文档：

# 静态站点
npx @mdream/crawl@beta https://yoursite.com

# 动态站点 (React/Vue 等，需 Playwright)
npx -p playwright -p @mdream/crawl@beta crawl https://spa-site.com --driver playwright

执行后将在 output/ 目录生成 llms.txt 及分块的 Markdown 文件。