[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-80936":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":14,"subscribersCount":14,"size":14,"stars1d":14,"stars7d":12,"stars30d":15,"stars90d":14,"forks30d":14,"starsTrendScore":16,"compositeScore":17,"rankGlobal":9,"rankLanguage":9,"license":18,"archived":19,"fork":19,"defaultBranch":20,"hasWiki":21,"hasPages":19,"topics":22,"createdAt":9,"pushedAt":9,"updatedAt":23,"readmeContent":24,"aiSummary":25,"trendingCount":14,"starSnapshotCount":14,"syncStatus":26,"lastSyncTime":27,"discoverSource":28},80936,"minerupress","aronnaxlin\u002Fminerupress","aronnaxlin","AI-friendly MinerU to MkDocs Material book pipeline",null,"Python",51,11,32,0,19,6,3.24,"Apache License 2.0",false,"main",true,[],"2026-06-12 02:04:08","# MineruPress\n\n把 MinerU 解析结果整理成可以发布的 MkDocs Material 图书站点。\n\nMineruPress 适合处理扫描教材、课程讲义、内部手册和长 PDF 知识库迁移：输入 MinerU 生成的 `content_list.json` 与图片，输出按章节拆分的 Markdown、图片资源和可直接部署的静态站点。\n\n![《软件测试方法和技术》示例站点](docs\u002Fassets\u002Fsoftware-testing-methods-site.png)\n\n英文 README：[docs\u002FREADME_EN.md](docs\u002FREADME_EN.md)\n\n## 快速开始\n\n先安装发布包，再用内置模板创建一本独立的新书工作区：\n\n```bash\npip install \"minerupress[all]\"\npip install mkdocs mkdocs-material\nminerupress init my-book\ncd my-book\nmkdocs serve\n```\n\n模板默认使用 `source: uploaded_result`，也就是你已经有 MinerU 解析结果。把解析结果放到 `resources\u002Fmineru\u002F` 后运行：\n\n```bash\nminerupress export book.yml\n```\n\n如果你是从 PDF 开始，推荐在 `book.yml` 里选择 `source: official_api`，配置 `api.sources`，然后运行：\n\n```bash\nminerupress fetch book.yml\n```\n\n标准链路如下：\n\n```text\nPDF \u002F Office \u002F 图片\n        |\n        v\nMinerU 官方 API \u002F 外部安装的本地 MinerU CLI \u002F 已上传解析结果\n        |\n        v\nresources\u002Fmineru\u002F*_content_list.json 与图片\n        |\n        v\ndocs\u002Fchapters\u002F*.md 与 docs\u002Fimages\u002F\n        |\n        v\nMkDocs Material 图书站点\n```\n\n## 解决什么问题\n\n- 长 PDF 经 MinerU 解析后，结果通常是一堆 JSON、图片和松散文本；MineruPress 把它们整理成稳定的图书工程。\n- 一本书可以被拆成多个 PDF 分片，导出时仍按同一个逻辑分册连续匹配章节。\n- 章节边界优先由标题自动推导，减少手写正则；遇到目录页、附录、项目制教材和中英文标题时也能更稳。\n- 导出过程可重复执行，每次重建章节 Markdown 和图片目录，避免旧文件混进新站点。\n- 插件系统负责二维码过滤、中西文间距、导出后部署等差异化工作，不把某本书的规则写死进核心代码。\n\n## 安装\n\n要求 Python `>=3.11`。\n\n普通使用推荐直接安装 PyPI 发布包：\n\n```bash\npip install \"minerupress[all]\"\npip install mkdocs mkdocs-material\n```\n\n如果你更希望把 CLI 隔离到独立环境，推荐使用 `pipx`：\n\n```bash\npipx install 'minerupress[all]'\npipx inject minerupress mkdocs mkdocs-material\n```\n\n升级时分别使用：\n\n```bash\npip install -U \"minerupress[all]\"\n```\n\n或：\n\n```bash\npipx upgrade minerupress\npipx inject minerupress mkdocs mkdocs-material --include-apps\n```\n\n如果你是在开发或修改工具链本身，而不是普通使用，请看后面的“贡献者开发”。\n\n可选依赖：\n\n| 依赖组 | 依赖 | 用途 |\n|---|---|---|\n| `qr` | `opencv-python` | `qr_filter` 二维码图片过滤 |\n| `cjk` | `pangu` | `cjk_spacing` 中西文间距处理 |\n| `all` | 上面两组 | 常见完整环境 |\n\n## 新书工作区\n\n建议每本书使用独立目录，不要直接把某本书的生成物放进工具链仓库。pip 安装后模板不在当前目录里，直接用 `minerupress init` 生成工作区即可：\n\n```bash\nminerupress init ~\u002Fdev\u002Fmy-book\u002F\ncd ~\u002Fdev\u002Fmy-book\u002F\n```\n\n模板里已经包含：\n\n- `book.yml`：书籍配置、章节列表、来源选择、MinerU API \u002F 本地工具链和部署配置。\n- `mkdocs.yml`：MkDocs Material 站点配置。\n- `.env.example`：敏感环境变量示例。\n- `Makefile`：常用导出、校验、构建命令。\n\n常见工作区结构：\n\n```text\nmy-book\u002F\n  book.yml\n  mkdocs.yml\n  resources\u002Fmineru\u002F\n  docs\u002F\n  site\u002F\n```\n\n`resources\u002F`、`docs\u002F`、`site\u002F` 通常是某本书自己的输入和输出，不应提交到 MineruPress 工具链仓库；如果你在独立图书仓库中维护成品站点，再按那个仓库的规则决定是否纳入版本控制。\n\n## 推荐工作流\n\n新项目只选一种来源模式，不要混用：\n\n| 起点 | `source` | 命令 | 说明 |\n|---|---|---|---|\n| 已有 MinerU 解析结果 | `uploaded_result` | `minerupress export book.yml` | 模板默认模式，把结果目录放进 `resources\u002Fmineru\u002F` |\n| 只有 PDF，想走云端 | `official_api` | `minerupress fetch book.yml` | 使用 MinerU 官方 API，抓取后会自动导出 |\n| 只有 PDF，想本机解析 | `local_toolchain` | `minerupress fetch book.yml` | 调用你单独安装的 `mineru` CLI，MineruPress 不内置 MinerU |\n\n稳定跑书通常分两轮：\n\n1. 先准备来源，拿到 `resources\u002Fmineru\u002F`。\n2. 用 `minerupress headings` 看真实标题结构，修好 `chapters`。\n3. 再执行 `minerupress export book.yml` 和 `mkdocs build --strict`。\n\n## 常用命令\n\n已有 MinerU 解析结果，直接导出：\n\n```bash\nminerupress export book.yml\n```\n\n按 `source` 准备来源后导出：\n\n```bash\nminerupress fetch book.yml\n```\n\n用导出命令先准备来源再导出：\n\n```bash\nminerupress export --fetch book.yml\n```\n\n分析 MinerU 输出中的正文大标题，生成章节配置草稿：\n\n```bash\nminerupress headings resources\u002Fmineru --volume-uid javaweb --format yaml --body-only\n```\n\n严格构建站点：\n\n```bash\nmkdocs build --strict\n```\n\n生成或比对文档指纹：\n\n```bash\nminerupress fingerprint --docs-dir docs --out reports\u002Ffingerprints.json\n```\n\n## `book.yml` 示例\n\n```yaml\nsource: uploaded_result\nmineru_root: resources\u002Fmineru\ndocs_out: docs\nvolume_uid: javaweb\ntoc_max_page: 10\nallow_missing_boundaries: false\n\nplugins:\n  - qr_filter\n  - cjk_spacing\n\nchapters:\n  - slug: ch01-overview\n    title: 第1章 Web开发概述\n  - slug: appendix-a\n    title: 附录A 部分习题的解答\n```\n\n来源选择：\n\n- `uploaded_result`：直接读取 `mineru_root` 下已有的 MinerU 结果目录。新模板默认使用这个模式，因为它不会触发上传、下载或本机解析。\n- `official_api`：使用 `api:` 配置走 MinerU 官方 API，适合从 PDF 开始。\n- `local_toolchain`：调用你单独安装的 `mineru` CLI。MineruPress 不内置 MinerU 依赖，只做外部适配。\n\n如果你选择 `local_toolchain`，请先按 MinerU 官方说明单独安装。常见方式是：\n\n```bash\nuv pip install -U \"mineru[all]\"\n```\n\n本地 MinerU 是可选外部工具，不会随 MineruPress 安装。按需扩展、轻量客户端、CLI 参数和源码开发方式请以 MinerU 官方文档为准：\n\n- [Quick Start](https:\u002F\u002Fopendatalab.github.io\u002FMinerU\u002Fquick_start\u002F)\n- [Extension Modules Installation Guide](https:\u002F\u002Fopendatalab.github.io\u002FMinerU\u002Fquick_start\u002Fextension_modules\u002F)\n- [CLI Tools Usage Instructions](https:\u002F\u002Fopendatalab.github.io\u002FMinerU\u002Fusage\u002Fcli_tools\u002F)\n\n边界匹配建议：\n\n- 优先只写 `title`。\n- MinerU 标题存在别名时加 `aliases`。\n- 必须手工控制正则时再写 `start_pattern` 或 `start_patterns`。\n- 正式导出保持 `allow_missing_boundaries: false`，避免章节错位后继续生成。\n\n所有相对路径都以 `book.yml` 所在目录为基准解析，所以可以从任意目录执行：\n\n```bash\nminerupress export \u002Fpath\u002Fto\u002Fmy-book\u002Fbook.yml\n```\n\nCLI 现已统一为 `minerupress \u003Csubcommand>`，例如：\n\n- `minerupress export`\n- `minerupress fetch`\n- `minerupress headings`\n- `minerupress fingerprint`\n\n旧入口 `minerupress-export`、`minerupress-fetch`、`minerupress-headings` 以及 `mineru-export`、`mineru-fetch` 仍然保留，便于旧项目平滑迁移。\n\n## 内置插件\n\n- `qr_filter`：使用 OpenCV 检测并过滤小尺寸二维码图片。\n- `cjk_spacing`：使用 `pangu` 为中西文混排补空格，并保护 LaTeX 公式片段。\n- `cf_pages`：执行 `mkdocs build --strict` 后部署到 Cloudflare Pages；项目不存在时会自动创建后重试。\n\n自定义插件继承 `ExportPlugin`：\n\n```python\nfrom pathlib import Path\nfrom minerupress import ExportPlugin\n\n\nclass MyPlugin(ExportPlugin):\n    def on_image(self, item: dict, img_path: Path | None) -> bool:\n        return True\n\n    def on_text(self, item: dict, text: str) -> str:\n        return text\n\n    def on_chapter_done(self, slug: str, lines: list[str]) -> list[str]:\n        return lines\n\n    def on_export_done(self, docs_out: Path) -> None:\n        pass\n```\n\n然后在 `book.yml` 中引用：\n\n```yaml\nplugins:\n  - mypackage.mymodule.MyPlugin\n```\n\n## 贡献者开发\n\n如果你要修改 MineruPress 自身，而不是只用它跑书，再 clone 仓库并做开发安装：\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Faronnaxlin\u002Fminerupress.git\ncd minerupress\npip install -e \".[dev]\"\n```\n\n本地验证：\n\n```bash\npytest\npython -m compileall minerupress\n```\n\n仓库已配置 GitHub Actions，在 Python 3.11 和 3.12 上运行 `compileall` 与 `pytest`。如果你只是使用工具链，优先安装发布包；如果你要参与开发，再使用 GitHub 开发安装。\n\n## 文档\n\n- [总览与术语](docs\u002Findex.md)\n- [快速开始](docs\u002Fguide\u002Fgetting-started.md)\n- [安装与升级](docs\u002Fguide\u002Finstall-and-upgrade.md)\n- [实战工作流](docs\u002Fguide\u002Fworkflow-run-a-book.md)\n- [配置详解](docs\u002Fguide\u002Fconfiguration.md)\n- [导出流程](docs\u002Fguide\u002Fexport-pipeline.md)\n- [插件系统](docs\u002Fguide\u002Fplugins.md)\n- [云端抓取与部署](docs\u002Fguide\u002Fcloud-api-and-deploy.md)\n- [校验、指纹与排障](docs\u002Fguide\u002Fvalidation-and-troubleshooting.md)\n- [发布与分发](docs\u002Fguide\u002Frelease.md)\n\n## Agent Skill 安装\n\n仓库内置了可给外部 agent 安装的 Skill：\n\n```text\nskills\u002Fminerupress\u002F\n```\n\n使用者可以从这个仓库获取：\n\n```bash\nnpx skills add aronnaxlin\u002Fminerupress --skill minerupress\n```\n\n安装后，agent 可以按同一套流程处理图书配置、MinerU 抓取、章节导出、构建校验、排障和 Cloudflare Pages 部署。维护工具链时，如果流程行为改变，也要同步更新 `skills\u002Fminerupress\u002F`。\n\n## 仓库边界\n\n这个仓库是通用工具链，`docs\u002F` 用来放项目文档，`book_template\u002F` 用来放新书模板。某本书的本地工作区、MinerU 输出、站点构建结果和敏感配置应保持隔离，不要提交到这里。\n\n通常不要提交：\n\n- 本地图书工作区目录\n- `resources\u002F`\n- `site\u002F`\n- `reports\u002F`\n- `.env`\n- `.wrangler\u002F`\n\n## 致谢\n\n- [MinerU](https:\u002F\u002Fgithub.com\u002Fopendatalab\u002FMinerU)\n- [MkDocs](https:\u002F\u002Fwww.mkdocs.org\u002F)\n- [Material for MkDocs](https:\u002F\u002Fsquidfunk.github.io\u002Fmkdocs-material\u002F)\n- [Cloudflare Pages](https:\u002F\u002Fpages.cloudflare.com\u002F)\n- [Vercel Agent Skills](https:\u002F\u002Fvercel.com\u002Fdocs\u002Fagent-resources\u002Fskills)\n\n## 许可证\n\nApache License 2.0，见 [LICENSE](LICENSE)。\n","MineruPress 是一个将MinerU解析结果整理成可发布的MkDocs Material图书站点的工具。其核心功能包括处理扫描教材、课程讲义、内部手册和长PDF知识库，通过输入`content_list.json`与图片，输出按章节拆分的Markdown文件、图片资源及静态站点。该工具支持多种数据源（如官方API、本地CLI或已上传解析结果），并提供插件系统以应对二维码过滤、中西文间距等差异化需求。适用于需要将纸质文档或PDF格式的教学资料转换为在线可读形式的场景，特别适合教育机构、企业培训部门或个人知识管理。使用Python编写，要求版本不低于3.11，并依赖于MkDocs和MkDocs Material来构建最终站点。",2,"2026-06-11 04:02:55","CREATED_QUERY"]