通用文档爬虫（Generic Docs Crawler）

一个面向文档站离线化的 Python 工具：
抓取源站文档 → 输出 Markdown → 构建本地 HTML 文档站（左侧导航 + 右侧正文）。

---

功能特性

• 支持抓取常见文档站（VitePress / Docusaurus 结构）
• 支持多文档根路径自动识别（如 /guide、/components）
• 支持“根路径 404，但叶子文档可访问”的站点结构
• 导航结构尽量贴近源站层级（一级/二级）
• 详细日志与保活输出（当前阶段、URL、进度、速率、ETA）
• 一键预览本地 HTML 文档站
• 输出标准 Markdown 目录，便于后续二次加工

---

适用场景

• 文档站离线备份
• 内网镜像阅读
• 文档迁移与归档
• 导航结构和正文内容对照审查

---

界面截图

源网站

本地预览站

---

环境要求

• Python 3.10+
• Windows PowerShell（推荐）或 CMD

---

快速开始

1) 准备配置

仓库内提供模板配置：crawler_config.template.json。

Copy-Item crawler_config.template.json crawler_config.json

编辑 crawler_config.json（关键字段）：

• target.base_url：目标站点域名（例如 https://docs.example.com）
• target.seed_path：入口路径（通常留空）
• target.docs_root：文档根路径（可留空）

crawler_config.json 已加入 .gitignore，默认不提交到仓库。

---

2) 一键运行（BAT）

run_crawler.bat

菜单：

• 1 抓取并构建站点
• 2 预览本地站点
• 3 查看状态
• 0 退出

---

3) 命令行运行（Python）

# 初始化工作目录
python docs_crawler.py --config crawler_config.json init

# 仅抓取
python docs_crawler.py --config crawler_config.json crawl

# 仅构建本地站点
python docs_crawler.py --config crawler_config.json build-site --menu-mode nav

# 抓取 + 构建（推荐）
python docs_crawler.py --config crawler_config.json run

# 本地预览
python docs_crawler.py --config crawler_config.json preview --port 8777

---

docs_root 配置说明（重要）

方案 A：手动指定单根路径

"docs_root": "/guide"

适合你明确知道文档主路径时使用。

方案 B：留空自动识别（推荐）

"docs_root": ""

程序会自动探测多个文档根路径并合并抓取。
也兼容如下情况：

• /components/ 返回 404
• 但 /components/xxx.html 可访问（会自动纳入抓取）

---

输出目录结构

默认输出到 .site_sync/：

• source_md/：抓取后的 Markdown 源文件
• manifests/source_manifest.json：抓取清单
• source_site/index.html：本地预览入口
• source_site/docs/...：预览站点引用的 md 文件
• reports/：抓取/构建报告

---

常用参数

• --max-docs N：仅抓取前 N 篇（调试时非常有用）
• --menu-mode nav：仅保留导航中出现的文档（推荐）
• --menu-mode all：展示所有抓取到的文档

示例：

python docs_crawler.py --config crawler_config.json run --max-docs 20

---

排错建议

1) 预览页面空白/无正文

按顺序执行：

python docs_crawler.py --config crawler_config.json run
python docs_crawler.py --config crawler_config.json preview --port 8777

浏览器使用 Ctrl + F5 强制刷新。

2) 导航层级不对或标题异常

• 先执行一次完整 run，不要只 preview
• 确认使用了最新构建产物（source_site/index.html）

3) 控制台中文乱码

Windows 下建议在 UTF-8 终端运行，或使用 PowerShell 7。

---

测试

python -m unittest discover -s tests -p "test_*.py" -v

---

项目定位

本项目聚焦于“文档抓取 + 本地文档站生成”两件事，
不绑定特定产品，不依赖登录态，适合作为通用文档镜像工具的基础版本。