CHM to Markdown Converter

CHM から Markdown への変換ツール

コンパイル済み HTML ヘルプ（.chm）ファイルを、プロファイルシステムによる複数のドキュメントタイプへの組み込みサポート付きで、整った Markdown に変換する Python ユーティリティです。

Autodesk Revit API ドキュメント用に開発されましたが、汎用プロファイルはあらゆる CHM ファイルで使用できます。

特長

• プロファイルベースの変換 — あらゆる CHM に対応する generic プロファイルと、Autodesk Revit API ドキュメント用の revit プロファイル
• エンコーディングの自動検出 — chardet を使用して、UTF-8、GB18030、GBK、GB2312 などに対応
• クロスプラットフォームの 7-Zip 検出 — PATH 上の 7z／7za／7zz を検出（Windows、Linux、macOS）
• 柔軟な CHM 構造への対応 — html/ サブディレクトリ、フラット構造、深くネストされた構造（DirectX SDK など）に対応
• --preserve-structure — すべてを data/ にフラット化する代わりに、出力先で CHM 内部のフォルダー階層を任意で再現
• コードブロックの保持 — クラス名や名前付き div から言語を検出。C#、VB、C++、F#、Python、Java、JS/TS、Bash、SQL、XML、JSON に対応
• テーブルの正規化 — Markdown テーブルを整形し、再フォーマット
• インデックスの生成 — 検索と AI 連携用に file_index.json、id_lookup.json、index.md を生成
• 非同期処理＋バッチ処理 — 同時実行数の制限と定期的な 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 のヘルプビューアーの UI 要素（折りたたみ可能な領域、フィードバックリンク、コードタブのツールバー、定型文）を削除します

カスタムプロファイルはプログラムから作成できます。

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）