pdf-craft Documentation

PDF craft can convert PDF files into various other formats. This project will focus on processing PDF files of scanned books.

5,802 stars Python Python 1 file · ~6,294 tokens #deepseek-ocr#document#ocr#pdf
RAW Doc

File: README.md

PDF Craft

text
[](https://github.com/oomol-lab/pdf-craft/actions/workflows/merge-build.yml)
[](https://pypi.org/project/pdf-craft/)
[](https://pypi.org/project/pdf-craft/)
[](https://pypi.org/project/pdf-craft/)
[](https://deepwiki.com/oomol-lab/pdf-craft)
[](https://github.com/oomol-lab/pdf-craft/blob/main/LICENSE)


English | 中文

Introduction

pdf-craft converts PDF files into various other formats, with a focus on handling scanned book PDFs.

This project is based on DeepSeek OCR for document recognition. It supports the recognition of complex content such as tables and formulas. With GPU acceleration, pdf-craft can complete the entire conversion process from PDF to Markdown or EPUB locally. During the conversion, pdf-craft automatically identifies document structure, accurately extracts body text, and filters out interfering elements like headers and footers. For academic or technical documents containing footnotes, formulas, and tables, pdf-craft handles them properly, preserving these important elements (including images and other assets within footnotes). When converting to EPUB, the table of contents is automatically generated. The final Markdown or EPUB files maintain the content integrity and readability of the original book.

Lightweight and Fast

Starting from the official v1.0.0 release, pdf-craft fully embraces DeepSeek OCR and no longer relies on an LLM for text correction. Local OCR conversion can run without network requests after models are cached; vendor OCR remains available when a remote backend is preferred.

However, the new version has also removed the LLM text correction feature. If your use case still requires this functionality, you can continue using the old version v0.2.8.

Online Version

If you'd like to explore pdf-craft without setting it up locally, you can try Inkora - PDF Craft, an online app built around the same PDF conversion workflow. It lets you upload PDF files and try the main experience directly in your browser.

Quick Start

Installation

bash
pip install pdf-craft

The default installation supports vendor OCR and does not install the local
model runtime. To actually use PDF conversion, install Poppler for PDF
parsing. For local OCR, install a CUDA-compatible PyTorch build first, then:

bash
pip install "pdf-craft[local]"

Please refer to the Installation Guide for details.

Quick Start

Convert to Markdown

python
from pdf_craft import PDFCraft, PDFOptions

craft = PDFCraft(pdf=PDFOptions())
craft.convert_pdf_to_markdown(
    "input.pdf",
    "output.md",
    package_path="analysing",
    assets_path="images",
)

Convert to EPUB

python
from pdf_craft import BookMeta, PDFCraft, PDFOptions

craft = PDFCraft(pdf=PDFOptions())
craft.convert_pdf_to_epub(
    "input.pdf",
    "output.epub",
    package_path="analysing",
    book_meta=BookMeta(
        title="Book Title",
        authors=["Author"],
    ),
)

The transform_markdown and transform_epub functions remain available as
compatibility convenience wrappers. New integrations should use PDFCraft so
extraction, rendering, and translation workflows share one public facade.

Reuse a DocumentPackage

PDF extraction produces a reusable DocumentPackage directory. It can be
translated without running OCR again, then written back to the matching source
PDF:

python
from pdf_craft import PDFCraft, PDFOptions, SubmitKind

craft = PDFCraft(pdf=PDFOptions())
package = craft.extract_pdf("input.pdf", "package")
translated = craft.translate_package(
    package, "translated-package", translator, submit=SubmitKind.REPLACE
)
craft.patch_pdf_with_package("input.pdf", translated, "translated.pdf")

patch_pdf_with_package patches the existing PDF using the package's page
geometry; it does not perform OCR, translation, or arbitrary PDF re-layout.

Detailed Usage

Convert to Markdown

python
from pdf_craft import DeepSeekOCRLocalConfig, transform_markdown

transform_markdown(
    pdf_path="input.pdf",
    markdown_path="output.md",
    markdown_assets_path="images",
    analysing_path="temp",  # Optional: specify temporary folder
    ocr_size="gundam",  # Optional: tiny, small, base, large, gundam
    ocr=DeepSeekOCRLocalConfig(models_cache_path="models"),
    dpi=300,  # Optional: DPI for rendering PDF pages (default: 300)
    max_page_image_file_size=None,  # Optional: max image file size in bytes, auto-adjust DPI if exceeded
    includes_cover=False,  # Optional: include cover
    includes_footnotes=True,  # Optional: include footnotes
    ignore_pdf_errors=False,  # Optional: continue on PDF rendering errors
    ignore_ocr_errors=False,  # Optional: continue on OCR recognition errors
    generate_plot=False,  # Optional: generate visualization charts
    toc_llm=None,  # Optional: LLM instance for enhanced TOC extraction
    toc_assumed=False,  # Optional: whether to assume TOC pages exist (default: False)
)

Convert to EPUB

python
from pdf_craft import (
    BookMeta,
    LaTeXRender,
    DeepSeekOCRLocalConfig,
    TableRender,
    transform_epub,
)

transform_epub(
    pdf_path="input.pdf",
    epub_path="output.epub",
    analysing_path="temp",  # Optional: specify temporary folder
    ocr_size="gundam",  # Optional: tiny, small, base, large, gundam
    ocr=DeepSeekOCRLocalConfig(models_cache_path="models"),
    dpi=300,  # Optional: DPI for rendering PDF pages (default: 300)
    max_page_image_file_size=None,  # Optional: max image file size in bytes, auto-adjust DPI if exceeded
    includes_cover=True,  # Optional: include cover
    includes_footnotes=True,  # Optional: include footnotes
    ignore_pdf_errors=False,  # Optional: continue on PDF rendering errors
    ignore_ocr_errors=False,  # Optional: continue on OCR recognition errors
    generate_plot=False,  # Optional: generate visualization charts
    toc_llm=None,  # Optional: LLM instance for enhanced TOC extraction
    toc_assumed=True,  # Optional: whether to assume TOC pages exist (default: True for EPUB)
    book_meta=BookMeta(
        title="Book Title",
        authors=["Author 1", "Author 2"],
        publisher="Publisher",
        language="en",
    ),
    lan="en",  # Optional: language (zh/en)
    table_render=TableRender.HTML,  # Optional: table rendering method
    latex_render=LaTeXRender.MATHML,  # Optional: formula rendering method
    inline_latex=True,  # Optional: preserve inline LaTeX expressions
)

OCR Configuration

pdf-craft supports every OCR backend exposed by doc-page-extractor:

  • DeepSeekOCRLocalConfig: local DeepSeek OCR model. Real conversion requires CUDA.
  • DeepSeekOCR2LocalConfig: local DeepSeek OCR 2 model. Real conversion requires CUDA.
  • UnlimitedOCRLocalConfig: local Unlimited OCR model. Real conversion requires CUDA.
  • DeepSeekOCRVendorConfig: DeepSeek OCR through an OpenAI-compatible endpoint.
  • DeepSeekOCR2VendorConfig: DeepSeek OCR 2 through an OpenAI-compatible endpoint.
  • UnlimitedOCRVendorConfig: Unlimited OCR cloud backend.

Pass one of these configs through the ocr parameter. The OCR mode strings are
deepseek-ocr-local, deepseek-ocr2-local, unlimited-ocr-local,
deepseek-ocr-vendor, deepseek-ocr2-vendor, and unlimited-ocr-vendor.
They are used only by this repository's manual scripts through .env; the
library API accepts configuration objects and does not read environment
variables.

python
from pdf_craft import (
    DeepSeekOCR2VendorConfig,
    DeepSeekOCRVendorConfig,
    UnlimitedOCRVendorConfig,
    transform_markdown,
)

transform_markdown(
    pdf_path="input.pdf",
    markdown_path="output.md",
    ocr=DeepSeekOCRVendorConfig(
        base_url="https://example.com",
        api_key="...",
        model="deepseek-ocr",
    ),
)

transform_markdown(
    pdf_path="input.pdf",
    markdown_path="output.md",
    ocr=DeepSeekOCR2VendorConfig(
        base_url="https://example.com",
        api_key="...",
        model="deepseek-ocr2",
    ),
)

transform_markdown(
    pdf_path="input.pdf",
    markdown_path="output.md",
    ocr=UnlimitedOCRVendorConfig(
        ak="...",
        sk="...",
    ),
)

Model Management

Local OCR models are automatically downloaded from Hugging Face on first run
when local_only=False (the default for the library configuration objects).
The repository's manual scripts default DEEPSEEK_LOCAL_ONLY and
UNLIMITED_LOCAL_ONLY to true, so set the relevant variable to false to
allow a missing model to download.
You can control model storage and loading behavior through the local OCR
configs. Unlimited OCR local supports the base and gundam ocr_size
presets. DeepSeek OCR 2 local is validated with the base preset; tiny is
rejected with a clear error because the upstream cached Hugging Face remote
code fails before extraction for that preset.

Pre-download Models

In production environments, it is recommended to download models in advance to avoid downloading on first run:

python
from pdf_craft import DeepSeekOCRLocalConfig, predownload_models

predownload_models(
    ocr=DeepSeekOCRLocalConfig(models_cache_path="models"),
    revision=None,  # Optional: specify model version
)

Specify Model Cache Path

By default, models are downloaded to the system's Hugging Face cache directory. You can customize the cache location through the models_cache_path parameter:

python
from pdf_craft import DeepSeekOCRLocalConfig, transform_markdown

transform_markdown(
    pdf_path="input.pdf",
    markdown_path="output.md",
    ocr=DeepSeekOCRLocalConfig(models_cache_path="./my_models"),
)

Offline Mode

If you have pre-downloaded the models, you can use local_only=True to disable network downloads and ensure only local models are used:

python
from pdf_craft import DeepSeekOCRLocalConfig, transform_markdown

transform_markdown(
    pdf_path="input.pdf",
    markdown_path="output.md",
    ocr=DeepSeekOCRLocalConfig(
        models_cache_path="./my_models",
        local_only=True,
    ),
)

API Reference

OCR Models

The ocr_size parameter accepts a DeepSeekOCRSize type:

  • tiny - Smallest model, fastest speed
  • small - Small model
  • base - Base model
  • large - Large model
  • gundam - Largest model, highest quality (default)

Backend notes: Unlimited OCR local supports only base and gundam.
DeepSeek OCR 2 local should use base; tiny is not treated as a reliable
local preset.

Table Rendering Methods

  • TableRender.HTML - HTML format (default)
  • TableRender.CLIPPING - Clipping format (directly clips table images from the original PDF scan)

Formula Rendering Methods

  • LaTeXRender.MATHML - MathML format (default)
  • LaTeXRender.SVG - SVG format
  • LaTeXRender.CLIPPING - Clipping format (directly clips formula images from the original PDF scan)

Inline LaTeX

The inline_latex parameter (EPUB only, default: True) controls whether to preserve inline LaTeX expressions in the output. When enabled, inline mathematical formulas are preserved as LaTeX code, which can be rendered by compatible EPUB readers.

Table of Contents Detection

The toc_assumed parameter controls how pdf-craft handles table of contents extraction:

  • False (default for Markdown): Assumes no TOC pages exist. The conversion generates TOC based on document headings only, without detecting or processing TOC pages.
  • True (default for EPUB): Assumes TOC pages exist. The conversion uses statistical analysis to detect TOC pages and extract chapter structure.

For books with complex chapter hierarchies, you can configure the optional toc_llm parameter to enable LLM-powered chapter title analysis, which provides more accurate TOC hierarchy detection.

LLM-Enhanced TOC Extraction

To use LLM-enhanced TOC extraction, you need to configure an LLM instance:

python
from pdf_craft import transform_epub, BookMeta, LLM

# Configure LLM for TOC extraction
toc_llm = LLM(
    key="your-api-key",
    url="https://api.openai.com/v1",  # Or your LLM provider URL
    model="gpt-4",
    token_encoding="cl100k_base",
    timeout=60.0,
    retry_times=3,
    retry_interval_seconds=5.0,
)

transform_epub(
    pdf_path="input.pdf",
    epub_path="output.epub",
    toc_assumed=True,  # Enable TOC detection
    toc_llm=toc_llm,  # Enable LLM-powered chapter title analysis
    book_meta=BookMeta(
        title="Book Title",
        authors=["Author"],
    ),
)

Custom PDF Handler

By default, pdf-craft uses Poppler (via pdf2image) for PDF parsing and rendering. If Poppler is not in your system PATH, you can specify a custom path:

python
from pdf_craft import transform_markdown, DefaultPDFHandler

# Specify custom Poppler path
transform_markdown(
    pdf_path="input.pdf",
    markdown_path="output.md",
    pdf_handler=DefaultPDFHandler(poppler_path="/path/to/poppler/bin"),
)

If not specified, pdf-craft will use Poppler from your system PATH. For advanced use cases, you can also implement the PDFHandler protocol to use alternative PDF libraries.

Error Handling

The ignore_pdf_errors and ignore_ocr_errors parameters provide flexible error handling options. You can use them in two ways:

1. Boolean Mode - Simple on/off control:

python
from pdf_craft import transform_markdown

transform_markdown(
    pdf_path="input.pdf",
    markdown_path="output.md",
    ignore_pdf_errors=True,  # Ignore all PDF rendering errors
    ignore_ocr_errors=True,  # Ignore all OCR recognition errors
)

When set to True, processing continues when errors occur on individual pages, inserting a placeholder message instead of stopping the entire conversion.

2. Custom Function Mode - Fine-grained control:

python
from pdf_craft import transform_markdown, OCRError, PDFError

def should_ignore_ocr_error(error: OCRError) -> bool:
    # Only ignore specific types of OCR errors
    return error.kind == "recognition_failed"

def should_ignore_pdf_error(error: PDFError) -> bool:
    # Custom logic to decide which PDF errors to ignore
    return "timeout" in str(error)

transform_markdown(
    pdf_path="input.pdf",
    markdown_path="output.md",
    ignore_ocr_errors=should_ignore_ocr_error,  # Pass custom function
    ignore_pdf_errors=should_ignore_pdf_error,  # Pass custom function
)

This allows you to implement custom logic for deciding which specific errors should be ignored during conversion.

Development

For local contributor setup, validation commands, manual conversion checks, and VGE worktree notes, see the Development Guide.

  • EPUB Translator: If you want to translate the EPUB generated by PDF Craft into a bilingual edition, EPUB Translator preserves the original layout, images, and table of contents. See this demo video for the full scanned PDF to bilingual EPUB workflow.
  • SpineDigest: If you want to distill the converted book into a structured digest, SpineDigest can turn EPUB or Markdown into summaries, chapter topology, and a knowledge graph.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Starting from v1.0.0, pdf-craft has fully migrated to DeepSeek OCR (MIT license), removing the previous AGPL-3.0 dependency, allowing the entire project to be released under the more permissive MIT license. Note that pdf-craft has a transitive dependency on easydict (LGPLv3) via DeepSeek OCR. Thanks to the community for their support and contributions!

Acknowledgments

File: docs/RELEASE.md

Release

Releases are published by the manual GitHub Actions release workflow. Do not publish the package from a local machine.

1. Configure PyPI trusted publishing

This is required once for the PyPI project.

Configure the PyPI trusted publisher for this repository:

  • PyPI project: pdf-craft
  • GitHub owner: oomol-lab
  • GitHub repository: pdf-craft
  • Workflow: release.yml
  • Environment: pypi

2. Prepare a release PR

For a target version such as 2.0.0, prepare and merge a PR that includes:

  • pyproject.toml version set to 2.0.0
  • docs/changelog/v2.0.0.md with the release notes

Use the existing files in docs/changelog/ as the changelog style reference.

3. Run the release workflow

After the release PR is merged to main, open the GitHub Actions Release workflow and run it manually from main.

The workflow reads the version from pyproject.toml, checks that the repository is ready, builds the package, publishes it to PyPI, pushes the matching vX.Y.Z tag, and creates the GitHub Release using docs/changelog/vX.Y.Z.md as the release notes.

File: README_zh-CN.md

PDF Craft

text
[](https://github.com/oomol-lab/pdf-craft/actions/workflows/merge-build.yml)
[](https://pypi.org/project/pdf-craft/)
[](https://pypi.org/project/pdf-craft/)
[](https://pypi.org/project/pdf-craft/)
[](https://deepwiki.com/oomol-lab/pdf-craft)
[](https://github.com/oomol-lab/pdf-craft/blob/main/LICENSE)


English | 中文

pdf-craft 是什么

pdf-craft 面向扫描版书籍，把 PDF 转换为 Markdown、EPUB 或翻译后的 PDF。一次提取
会生成可复用的 DocumentPackage，后续可以继续渲染、翻译或写回 PDF，不必每次重新
OCR。

项目提供三种本地 OCR 和三种 vendor OCR。vendor OCR 通过远程服务识别页面，不要求
本机 CUDA；local OCR 在本机运行模型，需要 CUDA。翻译使用独立的文本 LLM 配置，
与 OCR backend 分开。

核心流程是：

text
PDF → DocumentPackage
DocumentPackage → translated DocumentPackage
原始 PDF + translated DocumentPackage → PDF

安装

项目支持 Python 3.11、3.12 和 3.13。所有 PDF 路径都需要系统安装 Poppler；请参考
安装指南。

默认安装：vendor、渲染和 package 操作

bash
pip install pdf-craft

默认安装包含 vendor OCR、DocumentPackage、Markdown/EPUB 渲染和 PDF patch 所需的
基础依赖，不主动安装 local OCR 的模型运行时。vendor OCR 还需要 endpoint 和凭据；
库 API 通过配置对象接收它们，不读取 .env。

local OCR 安装

bash
pip install "pdf-craft[local]"

local extra 提供 Hugging Face、Transformers 等 local OCR 运行时。真实 local OCR
还需要 CUDA-capable PyTorch、模型缓存和足够显存；没有 CUDA 时请使用 vendor OCR。

快速开始

下面示例使用 vendor OCR。请把 endpoint、模型名和密钥替换成你的服务配置。

python
from pdf_craft import DeepSeekOCRVendorConfig, PDFCraft, PDFOptions

craft = PDFCraft(pdf=PDFOptions(ocr=DeepSeekOCRVendorConfig(
    base_url="https://example.com/v1",
    api_key="your-api-key",
    model="deepseek-ocr",
)))
craft.convert_pdf_to_markdown(
    "input.pdf", "output.md",
    package_path="work/package", assets_path="work/assets",
)

转换为 EPUB：

python
from pdf_craft import (
    BookMeta,
    DeepSeekOCRVendorConfig,
    PDFCraft,
    PDFOptions,
)

ocr_config = DeepSeekOCRVendorConfig(
    base_url="https://example.com/v1",
    api_key="your-api-key",
    model="deepseek-ocr",
)
craft = PDFCraft(pdf=PDFOptions(ocr=ocr_config))
craft.convert_pdf_to_epub(
    "input.pdf", "output.epub",
    package_path="work/package",
    book_meta=BookMeta(title="书名", authors=["作者"]),
)

PDFCraft 是 2.0 的公共 facade。旧的 transform_markdown 和 transform_epub 仍作为
兼容包装保留；新代码建议使用 PDFCraft。

DocumentPackage：可复用的中间文档

DocumentPackage 是一个文件夹，通常包含：

text
package/
├── chapters/       # 章节 XML、文字、结构和页面坐标
├── assets/         # 图片等资源
├── toc.xml         # 可选目录
├── cover.png       # 可选封面
└── document.json   # 页面几何和 package 元数据

库层的原子操作如下：

python
from pdf_craft import PDFCraft, PDFOptions, SubmitKind

# 复用上例中的 OCR 配置
craft = PDFCraft(pdf=PDFOptions(ocr=ocr_config))
package = craft.extract_pdf("input.pdf", "work/package")

# translator 实现 ChapterTransformer；这里不会重新 OCR 或读取 PDF。
translated = craft.translate_package(
    package, "work/translated-package", translator,
    submit=SubmitKind.REPLACE,
)

# 写回只使用原始 PDF 和已有 package，不调用 OCR/LLM。
PDFCraft().patch_pdf_with_package(
    "input.pdf", translated, "translated.pdf",
)

patch_pdf_with_package 使用 package 中的页面几何信息修改匹配的原始 PDF。它不是
通用 PDF 排版器，不能脱离原始 PDF 仅凭 package 生成新页面；package 与原始 PDF
不匹配时会提前失败。

翻译

库 API 的 PDFCraft.translate_pdf 要求调用者先准备好 DocumentPackage；它负责把翻译
package 写回原始 PDF。CLI 的 pdf translate 才会把 PDF 提取、package 翻译和 PDF patch
组合成一条命令。PDF 写回只支持替换式提交；Markdown 和 EPUB 还可以使用 append-block。

python
package = craft.extract_pdf("input.pdf", "work/package")
craft.translate_pdf("input.pdf", package, "translated.pdf", translator)

已有 EPUB 可以直接翻译：

python
from pdf_craft import PDFCraft, SubmitKind

PDFCraft().translate_epub(
    "input.epub", "translated.epub",
    target_language="zh", submit=SubmitKind.REPLACE,
)

OCR 只负责页面识别；章节翻译和可选的目录层级增强需要文本 chat-completion LLM。
不要把 OCR endpoint 当作翻译 LLM 使用。

OCR backend

pdf-craft 支持 doc-page-extractor 提供的六种 backend：

  • DeepSeekOCRLocalConfig：本地 DeepSeek OCR，需要 CUDA。
  • DeepSeekOCR2LocalConfig：本地 DeepSeek OCR 2，需要 CUDA。
  • UnlimitedOCRLocalConfig：本地 Unlimited OCR，需要 CUDA。
  • DeepSeekOCRVendorConfig：OpenAI-compatible DeepSeek OCR endpoint。
  • DeepSeekOCR2VendorConfig：OpenAI-compatible DeepSeek OCR 2 endpoint。
  • UnlimitedOCRVendorConfig：Unlimited OCR vendor backend。

库 API 的 ocr 参数接收配置对象，不读取环境变量。CLI 使用以下 backend 名称：

text
deepseek-ocr-local
deepseek-ocr2-local
unlimited-ocr-local
deepseek-ocr-vendor
deepseek-ocr2-vendor
unlimited-ocr-vendor

这些字符串由 pdf_craft_tool 从 .env 选择；--ocr-mode 只选择本次运行的 backend，
不会修改 .env。六种 backend 的配置可以同时存在。

Unlimited OCR local 仅支持 base 和 gundam；DeepSeek OCR 2 local 的已验证路径使用
base，显式使用 tiny 会快速失败并提示改用 base。

CLI：从命令行复现流程

pdf_craft_tool 是仓库内的本地 CLI，不包含在发布的 pdf-craft Python 包中。它从
仓库根目录运行，并通过 .env.template/.env 配置 OCR backend 和文本 LLM：

shell
poetry run python -m pdf_craft_tool --help
shell
# PDF → 可复用 DocumentPackage
poetry run python -m pdf_craft_tool pdf extract input.pdf \
  --ocr-mode deepseek-ocr-vendor --pages 1 \
  --work-dir pdf-craft-output/extract

# package → 翻译 package
poetry run python -m pdf_craft_tool package translate \
  pdf-craft-output/extract/package zh \
  --output-package pdf-craft-output/translated-package

# package → Markdown（不需要 OCR）
poetry run python -m pdf_craft_tool package render \
  pdf-craft-output/translated-package --format markdown

# 原始 PDF + translated package → patched PDF（不需要 OCR/LLM）
poetry run python -m pdf_craft_tool package patch-pdf \
  input.pdf pdf-craft-output/translated-package \
  --output translated.pdf

# 一键 PDF 翻译
poetry run python -m pdf_craft_tool pdf translate input.pdf zh \
  --format pdf --submit replace --ocr-mode deepseek-ocr-vendor --pages 1

# EPUB → EPUB
poetry run python -m pdf_craft_tool epub translate input.epub zh \
  --submit replace

所有 --pages 都使用从 1 开始的 PDF 页码。--work-dir 用于复用 package、缓存和日志，
也方便中断后恢复。完整 CLI 参数、smoke 矩阵和 .env 字段请看
pdf_craft_tool/README.md。

模型缓存与常用参数

local OCR 默认可以从 Hugging Face 下载模型。生产环境可以先预下载，再使用
local_only=True：

python
from pdf_craft import DeepSeekOCRLocalConfig, predownload_models

predownload_models(
    ocr=DeepSeekOCRLocalConfig(models_cache_path="models"),
    revision=None,
)

ocr_size 可使用 tiny、small、base、large 和 gundam，但不同 backend 的 preset 不完全
相同。Markdown 默认 toc_assumed=False，EPUB 默认 toc_assumed=True；复杂目录可以
传入 toc_llm。

pdf-craft 默认通过 pdf2image 使用系统 PATH 中的 Poppler。也可以向 PDFOptions 传入
自定义 PDFHandler。ignore_pdf_errors 和 ignore_ocr_errors 支持布尔值或自定义判断函数，
用于决定是否跳过单页错误。

兼容 API

transform_markdown、transform_epub 和 predownload_models 仍可从顶层导入。前两个是旧
API 的便利包装；新代码建议使用 PDFCraft facade。DocumentPackage 的正式操作是
extract_pdf、translate_package、render_markdown、render_epub 和 patch_pdf_with_package。

开发

本地贡献者环境、验证命令、手动转换检查和 VGE worktree 说明，请参考开发指南。

在线版本

如果你希望在不进行本地安装的情况下体验 pdf-craft，可以试试 Inkora - PDF Craft，这是一个基于相同 PDF 转换流程构建的在线应用。你可以直接上传 PDF 文件，在浏览器中体验主要功能。

相关项目

  • EPUB Translator：如果你想把 PDF Craft 生成的 EPUB 继续翻译成双语版本，EPUB Translator 可以在保留原始排版、插图和目录的前提下完成转换。完整流程可参考这个演示视频。
  • SpineDigest：如果你想进一步把转换后的书提炼成结构化摘要，SpineDigest 可以基于 EPUB 或 Markdown 生成摘要、章节拓扑和知识图谱。

许可证

本项目采用 MIT 许可证。详见 LICENSE 文件。

自 v1.0.0 起，pdf-craft 全面迁移到 DeepSeek OCR（MIT 协议），移除了原有的 AGPL-3.0 依赖，使得整个项目能够以更宽松的 MIT 协议发布。注意 pdf-craft 通过 DeepSeek OCR 间接依赖了 easydict（LGPLv3 协议）。感谢社区的支持与贡献！

致谢

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

#deepseek-ocr Browse deepseek-ocr catalog → #document Browse document catalog → #ocr Browse ocr catalog → #pdf Browse pdf catalog → ⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →