WeChat Docs HTML to Markdown

这个仓库包含一组脚本，用于抓取微信开发者文档并转换为清洗后的 Markdown。

• Linux（当前在容器/Codespace 中验证）
• python3
• uv
• wget
• pandoc

安装 pandoc（如果尚未安装）：

apt-get update && DEBIAN_FRONTEND=noninteractive apt-get install -y pandoc

文件：extract_doc_content.py

用途：抓取页面并按 XPath 提取节点，输出 HTML。

示例：

uv run extract_doc_content.py \
  --url "https://developers.weixin.qq.com/doc/service/api/" \
  --xpath '//*[@id="docContent"]' \
  --output docContent.html \
  --save-source source.html

文件：convert_selected_to_markdown.py

用途：从本地 HTML 中按 XPath 选区，调用 pandoc 转 Markdown，并做清洗：

• 移除 HTML 标签（如 div）
• a 转 Markdown 链接
• 清理 data-v-* 等属性
• 链接 URL decode

示例：

uv run convert_selected_to_markdown.py \
  --input source.html \
  --xpath '//*[@id="docContent"]' \
  --selected-html selected.html \
  --output-md docContent.md

文件：wechat_docs_crawl_convert_scheduler.py

用途：

1. 从 https://developers.weixin.qq.com/doc/ 开始用 wget --spider 发现 URL（robots=off）
2. 下载 HTML
3. 提取并清洗 #docContent
4. 批量转换为 Markdown
5. 处理链接：
   • 已抓到的站内页面改为本地相对 .md 路径
   • 未抓到的站内页面回退为绝对 URL

小规模示例：

uv run wechat_docs_crawl_convert_scheduler.py \
  --start-url "https://developers.weixin.qq.com/doc/" \
  --depth 1 \
  --max-urls 20 \
  --workdir crawl_output

较大规模示例：

uv run wechat_docs_crawl_convert_scheduler.py \
  --start-url "https://developers.weixin.qq.com/doc/" \
  --depth 2 \
  --max-urls 500 \
  --workdir crawl_output_full

以 --workdir crawl_output 为例，主要包含：

• crawl_output/spider.log：蜘蛛日志
• crawl_output/html/：下载的原始 HTML
• crawl_output/html_clean/：提取清洗后的 HTML
• crawl_output/md/：最终 Markdown

1. pandoc 未找到

• 先安装 pandoc，并确认 command -v pandoc 可用。

2. 某些页面没有生成 Markdown

• 该页面可能不存在 #docContent，调度脚本会跳过这类页面。

3. 链接仍有站外 URL

• 这是预期行为：仅站内且已抓取到的页面会改写为本地相对 .md。