wcp2web

wcp2web 是 WinCHM WCP 项目编译器：读取 .wcp 目录结构、HTML 页面、静态资源和 WebHelp 模板，生成可直接部署的 UTF-8 静态站点，并同步生成搜索索引与构建报告。

项目说明

WinCHM 项目通常由三部分组成：WCP 工程文件保存目录树和默认页，源目录保存 HTML 与图片/CSS/JavaScript 等资源，模板目录保存 WebHelp 框架页。本项目把三部分重新组装为现代静态输出，适合把历史 CHM/WebHelp 内容迁移到普通 Web 服务器或静态托管平台。

构建流程：

1. 解析 WCP 的主题层级、页面路径和默认主题。
2. 扫描源目录，识别 UTF-8、UTF-16、GBK/GB18030 等历史编码，统一输出 UTF-8 HTML。
3. 复制静态资源，规范化本地链接，检查危险路径、缺失文件、重复 URL、断链和多余页面。
4. 渲染 WebHelp 模板，生成导航、入口页和搜索数据。
5. 校验输出结构，写入构建、编码、缺失文件和断链报告。

主要能力：

• 保留 WCP 原始目录顺序和页面标题，支持中文文件名与 URL 编码。
• 支持增量缓存、多线程页面处理和可选严格模式。
• 生成带 UTF-8 BOM 的 contents 三元组 data.js，兼容现有搜索页。
• 自动注入 webhelp-content-bridge.js，让 file:// 打开的内容页也能接收搜索高亮和跳转消息。
• 可选把后端搜索页复制进站点，并替换 ($SEARCH_API_BASE$) 为配置的 API 地址。
• publish 只同步文件，不执行 Git 操作。

安装

要求 Python 3.11 或更高版本。

python -m pip install -e ".[dev]"

依赖：lxml、charset-normalizer；开发测试额外使用 pytest。

快速开始

复制并编辑示例配置：

cp wcp2web.example.toml wcp2web.toml

至少填写 [project] 中的 wcp、source_root、template_root。所有相对路径都相对配置文件所在目录解析。

安装后使用 wcp2web 命令；未安装时可在仓库根目录加上 PYTHONPATH=src python -m：

wcp2web build --config wcp2web.toml
wcp2web scan-encodings --config wcp2web.toml
wcp2web inspect-wcp path/to/project.wcp
wcp2web validate --config wcp2web.toml
wcp2web publish --config wcp2web.toml

未安装版本示例：

PYTHONPATH=src python -m wcp2web build --config wcp2web.toml

CLI 命令

• build：解析 WCP、渲染模板、转换页面、生成搜索索引并验证输出。
• scan-encodings：扫描源目录中的 HTML，输出检测到的编码、检测来源和声明编码。
• inspect-wcp：只解析 WCP，输出标题、默认页、目录节点、页面节点及警告，不写入输出目录。
• validate：验证已有构建结果；发现错误时返回退出码 1。
• publish：把 site_dir 同步到 publish.site_repository，把 search_data 复制到 publish.search_repository。

配置

完整示例见 wcp2web.example.toml。常用字段：

• [project]：wcp、source_root、template_root、title。
• [output]：站点目录 site_dir、搜索数据 search_data、报告目录 report_dir。
• [webhelp]：搜索 API search_api_base、可选搜索模板 search_template、默认页 default_page、导航宽度 nav_width、背景色 back_color。
• [encoding]：回退编码 default_fallback；strict = true 时，WCP 警告/错误、页面解码失败和未解析模板变量会使构建停止；危险路径会被拒绝并记录。
• [build]：并发数 jobs、增量缓存 incremental、构建前清理 clean。
• [publish]：目标仓库 site_repository、search_repository，以及不覆盖的 preserve 文件名列表。

输出目录

• dist/site/topics/：转换后的 HTML 和源静态资源。
• dist/site/index.htm、index.html、webhelpframe.htm、webhelpcontents.htm：WebHelp 框架页。
• dist/site/data.js：站点模板使用的搜索数据兼容副本。
• dist/site/webhelp-content-bridge.js：内容页搜索通信桥。
• dist/search/data.js：搜索服务使用的 UTF-8 BOM contents 三元组数据。
• dist/reports/：build-report.json、encoding-report.json、missing-files.json、broken-links.json。
• dist/.wcp2web-cache.json：增量构建缓存，记录文件大小、mtime_ns、源编码和输出路径。

严格模式与常见问题

非严格模式会保留可恢复问题并写入报告；WCP 无法解析、模板入口缺失、默认页缺失、输出写入失败或 data.js 无效仍会失败。

• template root missing：检查 template_root 是否相对配置文件目录。
• default page missing：检查 WCP 的 WebHelpDefault/DefaultTopic，或设置 [webhelp].default_page；值相对 topics/。
• data.js path missing：确认源页面已复制到 dist/site/topics/，再重新运行 build。
• 搜索服务读取了其他数据文件：设置 DATA_JS_PATH=/path/to/data.js 后重启 Node 服务。

开发与测试

源码位于 src/wcp2web/，测试和夹具位于 tests/。运行完整测试：

pytest -q

也可直接调用 Python API：

from wcp2web import build, load_config

report = build(load_config("wcp2web.toml"))
print(report.as_dict())