CHM to Markdown Converter

CHM 转 Markdown 转换器

一个 Python 工具，可将已编译 HTML 帮助（.chm）文件转换为简洁的 Markdown，并通过配置文件系统内置支持多种文档类型。

最初为 Autodesk Revit API 文档开发；通用配置文件适用于任何 CHM 文件。

功能

• 基于配置文件的转换 — generic 配置文件适用于任何 CHM，revit 配置文件适用于 Autodesk Revit API 文档
• 自动检测编码 — 通过 chardet 处理 UTF-8、GB18030、GBK、GB2312 等编码
• 跨平台检测 7-Zip — 可在 PATH 中查找 7z/7za/7zz（Windows、Linux、macOS）
• 灵活支持 CHM 结构 — 支持 html/ 子目录、扁平结构和深层嵌套结构（例如 DirectX SDK）
• --preserve-structure — 可选择在输出中保留 CHM 内部文件夹层级，而不是将所有内容扁平化到 data/ 中
• 保留代码块 — 根据类名和命名 div 检测语言；支持 C#、VB、C++、F#、Python、Java、JS/TS、Bash、SQL、XML、JSON
• 表格规范化 — 清理并重新格式化 Markdown 表格
• 生成索引 — 生成 file_index.json、id_lookup.json 和 index.md，用于搜索和 AI 集成
• 异步与批处理 — 有界并发和定期 GC 可防止处理大型 CHM 文件（6 000 多个页面）时内存溢出

项目结构

chm_converter/           # Core package
├── config.py            # ConversionConfig dataclass + built-in profiles
├── encoding.py          # Encoding detection (chardet + CJK fallbacks)
├── extractor.py         # CHM extraction via 7-Zip; HTML folder detection
├── html_processor.py    # HTML cleaning, link rewriting, code block extraction
├── md_converter.py      # HTML → Markdown conversion + post-processing
├── indexer.py           # File dictionary building + index file generation
└── pipeline.py          # High-level async pipeline (process_chm_file, process_all_chm_files)

chm_to_markdown.py       # CLI entry point
resources/               # Place CHM files here
output/                  # Generated Markdown (created automatically)

输出布局

output/
└── <name>/
    ├── core/
    │   ├── file_index.json   # id → {title, filename, version}
    │   ├── id_lookup.json    # lowercase id → {title, filename, keywords, version}
    │   └── index.md          # alphabetical navigation page
    └── data/
        ├── Topic1.md
        ├── Topic2.md
        └── ...

要求

• Python 3.10+
• 7-Zip — 7z 必须可通过默认安装路径或 PATH 访问
  • Windows：默认安装到 C:\Program Files\7-Zip\7z.exe，也可将其添加到 PATH
  • Linux：sudo apt install p7zip-full
  • macOS：brew install p7zip

安装

git clone https://github.com/DTDucas/chm-converter.git
cd chm-converter
pip install -r requirements.txt

使用方法

将 .chm 文件放入 resources/ 文件夹，然后运行：

# Interactive menu (lists available CHM files)
python chm_to_markdown.py

# Convert a single file
python chm_to_markdown.py --single resources/docs.chm

# Convert all CHM files in resources/
python chm_to_markdown.py --all

# Use the Revit API profile (strips Revit help-viewer boilerplate)
python chm_to_markdown.py --all --profile revit

# Preserve the original folder hierarchy inside data/ (e.g. for DirectX SDK)
python chm_to_markdown.py --single resources/directx_sdk.chm --preserve-structure

# Keep extracted HTML for debugging
python chm_to_markdown.py --single resources/docs.chm --keep-html

# Tune performance
python chm_to_markdown.py --all --workers 4 --batch-size 25 --semaphore 10

CLI 参数

参数	短选项	默认值	说明
--single FILE	-s	—	转换单个 CHM 文件
--all	-a	—	转换 resources/ 中的所有 CHM 文件
--profile	-p	generic	转换配置文件：generic 或 revit
--keep-html	-k	关闭	转换后保留提取的 HTML
--workers N	-w	8	用于受 CPU 限制的转换任务的线程池大小
--batch-size N	-b	50	每个异步批次处理的文件数
--semaphore N	—	20	最大并发 I/O 操作数
--preserve-structure	—	关闭	在 data/ 中保留 CHM 文件夹层级；保留相对链接

配置文件

配置文件	说明
generic	仅进行最基本的清理 — 适用于任何 CHM 文件
revit	移除 Autodesk Revit 帮助查看器界面元素（可折叠区域、反馈链接、代码选项卡工具栏、样板文本）

可通过编程方式创建自定义配置文件：

from chm_converter.config import ConversionConfig
from chm_converter.pipeline import process_chm_file
import asyncio

cfg = ConversionConfig(
    classes_to_remove=["my-nav-bar", "site-footer"],
    ids_to_remove=["cookie-banner"],
    cleanup_patterns=[
        (r"Rate this article.*?---", "---"),
    ],
)

asyncio.run(process_chm_file("docs.chm", "extracted", "output", cfg=cfg))

AI 集成

core/ 文件夹专为 RAG 和 AI 搜索工作流设计：

• file_index.json — 将每个文件 ID 映射到其标题、文件名和版本
• id_lookup.json — 使用小写键，并附带提取的关键词列表，用于全文搜索
• index.md — 带有锚点链接、按字母顺序排列的易读索引

故障排除

问题	解决方案
7z not found	安装 7-Zip 并确保它位于 PATH 中；参见上文的“要求”
输出为空 / No HTML files found	CHM 使用嵌套文件夹结构 — 添加 --preserve-structure 以启用递归遍历
Revit 2025+ 页面仅包含标题，没有正文	已在当前版本中修复：Revit 配置文件不再剥离 TopicContent
CJK 文本乱码	工具通过 chardet 自动检测编码；如果问题仍然存在，请尝试使用 --profile generic
处理大型 CHM 时发生内存错误	降低 --workers 和 --batch-size
权限错误	使用管理员 / sudo 权限运行终端

许可证

MIT 许可证

作者

Duong Tran Quang (DTDucas) [email protected] github.com/DTDucas 作者：dtducas.com

贡献者

• Jiangxumin — 中文编码支持、跨平台 7-Zip 检测、安全的内存批处理（PR #11）