# PrometheusDocs

**Repository Path**: mwdworks/PrometheusDocs

## Basic Information

- **Project Name**: PrometheusDocs
- **Description**: 通用文档站爬虫：自动抓取多目录文档（支持 VitePress/Docusaurus），生成本地 Markdown 与可预览的
HTML 文档站（左侧导航 + 右侧正文）。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2026-05-09
- **Last Updated**: 2026-05-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 通用文档爬虫（Generic Docs Crawler）

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

---

## 功能特性

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

---

## 适用场景

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

---

## 界面截图

### 源网站

![源网站截图](image/1.png)

### 本地预览站

![本地预览截图](image/2.png)

---

## 环境要求

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

---

## 快速开始

### 1) 准备配置

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

```powershell
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）

```powershell
run_crawler.bat
```

菜单：

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

---

### 3) 命令行运行（Python）

```powershell
# 初始化工作目录
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：手动指定单根路径

```json
"docs_root": "/guide"
```

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

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

```json
"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`：展示所有抓取到的文档

示例：

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

---

## 排错建议

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

按顺序执行：

```powershell
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。

---

## 测试

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

---

## 项目定位

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