DeepWiki Markdown 转换器¶

概述¶

这是一个专门用于将 DeepWiki 页面转换为 Markdown 格式的工具。该工具的核心功能是正确处理 Mermaid 图表，将其转换为标准的 Markdown fence 格式（```mermaid）。

特性¶

🚀 自动提取 DeepWiki 页面内容
📊 智能识别和转换 Mermaid 图表
📝 生成标准 Markdown 格式
🎯 自动添加 Front Matter 元数据
💻 支持命令行和 API 两种使用方式
⚡ 基于 Puppeteer 的可靠抓取

技术栈¶

Node.js - 运行环境
Puppeteer - 无头浏览器自动化
Turndown - HTML 到 Markdown 转换

目录结构¶

tools/deepwiki-to-markdown/
├── README.md                  # 详细文档
├── package.json               # 项目配置
├── cheerio-converter.js      # 主程序 (基于 Cheerio 的转换器)
├── test-converter.js          # 测试脚本
├── examples.js                # 使用示例
├── .gitignore                 # Git 忽略文件
└── examples/                  # 示例输出目录

快速开始¶

1. 安装依赖¶

cd tools/deepwiki-to-markdown
npm install

2. 基本使用¶

# 转换页面并输出到终端
node cheerio-converter.js https://deepwiki.com/Project-HAMi/HAMi/1-overview

# 转换页面并保存到文件
node cheerio-converter.js https://deepwiki.com/Project-HAMi/HAMi/1-overview output.md

3. 运行测试¶

npm test

4. 查看示例¶

node examples.js

核心功能¶

Mermaid 图表处理¶

工具会自动识别以下类型的 Mermaid 元素：

<pre class="mermaid">
<div class="mermaid">
<code class="language-mermaid">
[data-type="mermaid"]

并将其转换为标准 Markdown 格式：

```mermaid
graph TD
    A[开始] --> B[处理]
    B --> C[结束]
```

内联 Mermaid 插入（位置保留）¶

工具现在会尝试把提取到的 Mermaid 原始代码插入到它们在文章中应该出现的位置，而不是统一追加到文档末尾。实现要点：

首先从页面的 Next.js hydration 脚本中提取包含 Mermaid 代码块的原始 Markdown 文本和上下文（前文/后文片段）。
将 HTML 转换为 Markdown（使用 Turndown）后，使用前文上下文在转换后的 Markdown 中定位插入点，并把对应的 Mermaid 代码块插入到正确位置。
若未能通过上下文准确定位（例如页面内容发生较大变形），脚本会在控制台打印警告并把该图表追加到文档末尾作为回退策略。

这种方式在大多数 Next.js 渲染的 DeepWiki 页面上能准确恢复图表在原文中的位置。

内容提取¶

自动识别主要内容区域
保留文章结构和格式
提取元数据（标题、URL、时间戳）

Markdown 转换¶

标题使用 ATX 风格（#）
代码块使用 fenced 格式（```）
保留图片 alt 和 title 属性
保留链接格式

表格支持 (GFM)¶

DeepWiki 的 HTML 表格现在会被正确转换为 GitHub Flavored Markdown (GFM) 表格。实现要点：

安装并启用了 turndown-plugin-gfm，它为 Turndown 提供了 GFM 表格的转换规则和改进的列表/表格处理。
在 cheerio-converter.js 的构造函数中加入 this.turndownService.use(require('turndown-plugin-gfm').gfm);。

示例输出：

| Vendor | Device Type | Resource Names | Features |
| --- | --- | --- | --- |
| NVIDIA | GPU | `nvidia.com/gpu`, `nvidia.com/gpumem` | MIG support, vGPU, memory scaling |

API 使用¶

作为模块导入使用：

const DeepWikiConverterCheerio = require('./cheerio-converter');

async function convert() {
  const converter = new DeepWikiConverterCheerio();
  const markdown = await converter.convertUrl(
    'https://deepwiki.com/Project-HAMi/HAMi/1-overview',
    'output.md'
  );
  console.log(markdown);
}

convert();

配置选项¶

自定义 Turndown 规则¶

在 cheerio-converter.js 中可以添加自定义转换规则：

this.turndownService.addRule('custom', {
  filter: (node) => {
    return node.nodeName === 'CUSTOM_TAG';
  },
  replacement: (content, node) => {
    return `Custom: ${content}`;
  }
});

调整浏览器参数¶

修改 Puppeteer 启动配置：

const browser = await puppeteer.launch({
  headless: 'new',
  args: [
    '--no-sandbox',
    '--disable-setuid-sandbox',
    '--disable-dev-shm-usage',
  ]
});

故障排除¶

常见问题¶

Mermaid 图表未正确提取
检查页面 HTML 结构
添加适当的选择器到 extractMermaidCode 方法
页面加载超时
增加 timeout 设置
检查网络连接
内容不完整
调整主要内容选择器
增加页面等待时间

依赖 & 安装说明（如果你在本地运行）¶

在 tools/deepwiki-to-markdown 目录下，确保安装如下依赖：

cd tools/deepwiki-to-markdown
npm install
# 如果未安装 gfm 插件
npm install turndown-plugin-gfm

如果遇到表格渲染不正确，先确认 turndown-plugin-gfm 已正确安装并在 cheerio-converter.js 中调用 use()。

已知限制与故障排查¶

动态渲染内容：DeepWiki 很多内容（包括 Mermaid 渲染后的 SVG）是在客户端通过 JS 动态生成的，直接抓取静态 HTML 时可能看不到渲染后的元素。因此脚本使用 Next.js 的 hydration 数据和文档上下文来恢复 Mermaid 原始代码并在 Markdown 中插入。
上下文定位失败：若原文经过复杂的 HTML 改写或 Turndown 转换产生较大格式差异，基于前/后文的匹配可能失败。脚本会在控制台打印警告并把该图表追加到文档末尾作为回退策略。
Edge cases：如果页面中存在大量重复段落或标题（相同上下文片段），脚本可能需要更强的指纹（例如同时匹配多处上下文或使用更长的片段）。

调试建议：

打开脚本的调试日志，查看脚本打印的 'before'/'after' 上下文片段和匹配结果。
在浏览器中查看 Next.js hydration 脚本，确认 Mermaid 原始代码是否包含在脚本中。
如需要手动调整，请修改 processMermaid() 中上下文截取长度或匹配策略。

开发指南¶

添加新功能¶

修改 cheerio-converter.js
添加对应的测试用例到 test-converter.js
更新 README.md 文档
运行测试验证功能

批量转换（Batch conversion）¶

如果需要一次性将多个 DeepWiki 页面转换为 Markdown，可以使用仓库中提供的批量脚本 batch-convert.js（位于 tools/deepwiki-to-markdown/ 子目录）。下面说明如何准备 URL 列表、运行脚本、以及脚本输出说明与常见问题处理。

文件：tools/deepwiki-to-markdown/batch-convert.js

主要功能：

根据一个文本文件中的 URL 列表逐个调用转换器并把结果保存为 Markdown 文件。
自动生成一个 conversion-stats.json 统计文件，记录总数/成功/失败及错误信息。

用法示例：

# 进入工具目录（可选）
cd tools/deepwiki-to-markdown

# 运行批量转换脚本
node batch-convert.js urls.txt output/

参数说明：

urls.txt：一行一个 URL 的文本文件，支持使用 # 开头的行作为注释。例如：

# example urls
https://deepwiki.com/Project-HAMi/HAMi/1-overview
https://deepwiki.com/Project-HAMi/HAMi/2-architecture

output/：输出目录，脚本会在该目录下创建或覆盖文件，并将每个 URL 的转换结果保存为独立的 .md 文件。

输出结果与统计：

每个成功转换的页面会生成一个 .md 文件，文件名由 URL 的最后两段生成（非法字符会被替换为下划线）。
转换完成后，脚本会在输出目录写入 conversion-stats.json，包含如下结构：

{
  "total": 10,
  "success": 8,
  "failed": 2,
  "errors": [
    { "url": "https://...", "error": "错误信息" }
  ]
}

运行注意事项与建议：

网络与速率：脚本会在每次请求后等待 2 秒以降低请求速率。根据目标站点的访问限制，可适当调整脚本中的等待时间。
超时与重试：若遇到网络不稳定或页面超时，建议先单独运行出错的 URL（使用 cheerio-converter.js）排查具体原因，然后再重试批量脚本。
文件名冲突：脚本采用 URL 的最后两段生成文件名，但在存在相同结尾的 URL 时可能发生冲突。可在运行后检查输出目录并按需重命名或修改脚本生成规则。
位置保留的 Mermaid：批量脚本依赖转换器（cheerio-converter.js）处理 Mermaid 的内联定位逻辑。若发现某些 Mermaid 未能插入到正确位置，查看控制台警告并手动修正对应的 .md 文件或改进转换器的上下文匹配逻辑。

扩展与自定义：

自定义输出文件名：如果你希望改用其他文件名规则，可以在 batch-convert.js 中修改生成 filename 的逻辑，或将 convertUrl 改为返回转换后的 Markdown，并由外层脚本负责命名与保存。
并发加速：当前脚本为串行处理（每个 URL 之间有延时）。如果你需要更快的批量处理，可以改为有限并发（比如使用 p-limit 或 Promise.allSettled 结合并发限制），但请注意目标站点的访问策略和礼貌速率限制。

示例：检查统计并查看失败列表

# 运行批量转换
node batch-convert.js urls.txt output/

# 查看统计文件
cat output/conversion-stats.json | jq

# 列出失败的 URL
jq -r '.errors[] | .url' output/conversion-stats.json

常见问题排查：

如果 conversion-stats.json 中大量失败，优先查看 errors 字段内的 error 文本。常见问题有访问被限速、目标页面需要认证或转换器选择器失效。
对于需要登录的 DeepWiki 页面，目前脚本不支持自动登录；需要手动抓取 HTML 或在 cheerio-converter.js 中扩展 Puppeteer 登录逻辑。
当输出 Markdown 的某些样式或表格不符合期望时，确认已安装并启用 turndown-plugin-gfm 并在转换器中注册：

// 在 cheerio-converter.js 构造函数内
this.turndownService.use(require('turndown-plugin-gfm').gfm);

小结：

批量脚本 batch-convert.js 提供了一个方便的方式来一次性处理多个 DeepWiki 页面。对于大规模抓取，请结合目标站点的访问策略调整并发与节奏，并在出现错误时优先排查单页问题。

更新日志¶

v1.0.0 (2025-10-10)¶

初始版本发布
支持基本的 DeepWiki 页面转换
Mermaid 图表自动识别和转换
Front Matter 自动生成