doc2md-lite

doc2md-lite

免费。无需 API 密钥。在自己的电脑上运行，文件始终留在你这里。

一款可将文本 PDF 或已保存的网页（.html）转换为整洁 Markdown 的工具。表格会保留为真正的 Markdown 表格。 需要 Word 文件、用于 AI 搜索（RAG）的分块、整个文件夹或页面范围？付费版支持这些功能：Gumroad 上的 doc2md

在自己的电脑上运行，文件绝不会上传到任何地方。采用 MIT 许可证。支持 Windows、Mac 和 Linux，需要 Python 3.10 或更高版本。

安装

pip install doc2md-lite

也可以使用 pipx，它会将其安装在独立环境中：

pipx install doc2md-lite

想要直接使用 GitHub 上的最新代码？

pip install git+https://github.com/tidybytetools/doc2md-lite

使用方法

doc2md-lite report.pdf                 # writes report.md
doc2md-lite page.html -o page.md
doc2md-lite report.pdf -o -            # print the Markdown on screen
doc2md-lite report.pdf --tables text   # also find tables with no border lines

运行示例：

Saved: report.md  (4 headings, 1 tables)

PDF 的输出示例：

# Spring Store Report

Our team checked every store in March. Most stores met the new goal...

## Sales by region

| Region | Stores | Sales |
| --- | --- | --- |
| North | 12 | $48,200 |
| South | 9 | $39,950 |

保留的内容：标题（在 PDF 中根据字体大小和粗体识别）、段落、项目符号列表和编号列表、表格；在 HTML 中还会保留粗体、斜体、链接和代码块。处理网页时会删除脚本、样式、菜单和页脚。

在终端中运行时，程序结束前会显示一行关于付费版的简短信息。使用 --quiet 可关闭此信息；输出通过管道传输或重定向时，也不会显示。

已知限制

• 扫描版 PDF。 仅包含图像（没有文本层）的页面会被跳过，工具会告知你具体是哪些页面。
• PDF 标题仅为尽力识别，依据字体大小和粗体判断。特殊版式可能需要快速修正。
• 双栏 PDF（例如科学论文）可能会混合两栏内容。
• 一次只能处理一个文件。 不支持文件夹、页面范围、Word 文件或 RAG 分块。付费版支持这些功能。
• 仅处理文件。 不会下载网页，请先保存网页。

Lite 版与付费版

	lite（免费）	doc2md
将文本 PDF 和 HTML 转换为 Markdown	是	是
表格保留为 Markdown 表格	是	是
Word（.docx），保留粗体、斜体、链接和列表	否	是
RAG 分块（JSONL，包含页面、标题路径、大小和重叠信息）	否	是
整个文件夹，包括子文件夹	否	是
页面范围和受密码保护的 PDF	否	是

其他优秀的免费工具

选择适合你的工具。MarkItDown 支持读取更多文件类型。pandoc 非常适合处理 Word 和 HTML，但无法读取 PDF。pymupdf4llm 处理 PDF 速度很快，但采用 AGPL 许可证。doc2md-lite 体积小巧，采用 MIT 许可证，能将 PDF 表格保留为表格，并内置 MCP 服务。

在 AI 应用中使用（MCP）

内置了一个小巧、免费的 MCP 服务。它为你的 AI 应用提供一个工具：convert_to_markdown。无需 API 密钥或账号。它需要 uv，该工具会提供 uvx 命令。

手动运行，检查它是否启动（它会静静等待应用与其通信）：

uvx --from doc2md-lite doc2md-lite-mcp

更快捷的方式是：uvx doc2md-lite mcp，以启动同一个服务。

在下方选择你的应用并复制代码块。保存后重启应用。

Claude Desktop

打开 Settings > Developer > Edit Config。这会打开 claude_desktop_config.json。添加以下内容：

{
  "mcpServers": {
    "doc2md-lite": {
      "command": "uvx",
      "args": ["--from", "doc2md-lite", "doc2md-lite-mcp"]
    }
  }
}

如果 Claude 提示找不到 uvx，运行 which uvx（Mac/Linux）或 where uvx（Windows），并将完整路径填入 "command"。

Cursor

将相同的代码块放入 ~/.cursor/mcp.json（适用于所有项目）或 .cursor/mcp.json（适用于单个项目）：

{
  "mcpServers": {
    "doc2md-lite": {
      "command": "uvx",
      "args": ["--from", "doc2md-lite", "doc2md-lite-mcp"]
    }
  }
}

VS Code

VS Code 使用 servers，而非 mcpServers。将以下内容放入项目中的 .vscode/mcp.json，或运行 MCP: Open User Configuration 以便在所有项目中使用：

{
  "servers": {
    "doc2md-lite": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "doc2md-lite", "doc2md-lite-mcp"]
    }
  }
}

或者运行一条命令添加：

code --add-mcp '{"name":"doc2md-lite","type":"stdio","command":"uvx","args":["--from","doc2md-lite","doc2md-lite-mcp"]}'

Cline

在 Cline 面板中，点击 MCP Servers 图标，打开 Configure，然后点击 Configure MCP Servers。将以下内容添加到 mcpServers 中：

{
  "mcpServers": {
    "doc2md-lite": {
      "command": "uvx",
      "args": ["--from", "doc2md-lite", "doc2md-lite-mcp"],
      "disabled": false,
      "autoApprove": []
    }
  }
}

Codex

运行一条命令：

codex mcp add doc2md-lite -- uvx --from doc2md-lite doc2md-lite-mcp

或者将以下内容添加到 ~/.codex/config.toml：

[mcp_servers.doc2md-lite]
command = "uvx"
args = ["--from", "doc2md-lite", "doc2md-lite-mcp"]

Gemini CLI

此仓库也提供 Gemini CLI 扩展。使用以下命令安装：

gemini extensions install https://github.com/tidybytetools/doc2md-lite

工具：convert_to_markdown(path, tables="lines", output_path="")。它会返回 Markdown 文本。如果设置了 output_path，则会将文件保存到该路径，并改为返回该路径。

在 GitHub Actions 中使用

每次推送时，将仓库中的 PDF 和网页转换为 Markdown。Markdown 易于搜索、易于在拉取请求中阅读，也便于 AI 工具使用。

name: Docs to Markdown
on: [push, pull_request]
permissions:
  contents: read
jobs:
  markdown:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: tidybytetools/doc2md-lite@v1
        with:
          files: docs/**/*.pdf
          output-dir: markdown
          artifact-name: docs-markdown   # download the .md files from the run page

保持 Markdown 副本同步。 你会在每个 PDF 旁边提交一个 .md 副本吗？使用检查模式。如果副本缺失或已过期，此步骤会针对相应文件失败。检查模式下不会写入任何内容。

      - uses: tidybytetools/doc2md-lite@v1
        with:
          files: docs/**/*.pdf
          check: "true"

要生成副本，可在电脑上运行 doc2md-lite your.pdf，或在不启用 check 的情况下运行此 action，然后提交生成的文件。两处使用相同版本的 doc2md-lite，确保输出一致。此 action 会安装固定版本的 pdfplumber 和 Beautiful Soup，因此同一个文件始终会生成相同的 Markdown。

它会运行你所选标签中的代码。无需 API 密钥或账号，你的文件也不会被发送到 GitHub 以外的任何地方。它支持 Linux、Windows 和 Mac 运行器。对于扫描版 PDF 页面（只有图片、没有文本），会跳过并发出警告。设置 fail-on-scanned: "true" 可在遇到此类页面时改为失败。

输入

输入	默认值	作用
files	**/*.pdf	要转换的文件（.pdf、.html、.htm）。支持 glob 模式，每行一个或用逗号分隔。
exclude	node_modules/**、**/node_modules/**、vendor/**	要跳过的模式。
output-dir	（空）	Markdown 的存放文件夹。会保留文件夹结构。为空时，每个 .md 文件会保存在对应文件旁边。
tables	lines	PDF 表格：lines（带边框）、text（也会用空格对齐）或 off。
check	false	仅检查。若 Markdown 副本缺失或已过期，则失败。
fail-on-scanned	false	PDF 包含没有文本的扫描页面时失败。
fail-if-no-files	true	没有匹配文件时失败。
artifact-name	（空）	设置后，会使用此名称将 Markdown 上传为构建产物。需要设置 output-dir。
python-version	（空）	要设置的 Python 版本。为空时使用运行器自带的 Python（3.10 或更高版本）。

输出

输出	含义
files	匹配的 PDF 和 HTML 文件数量。
converted	无错误地转换（或检查）的文件数量。
changed	新增或已更改的 Markdown 文件数量。在检查模式下，表示缺失或已过期的文件数量。
scanned-files	包含扫描页面的 PDF 数量。
output-dir	输出文件夹。

运行页面还会显示一份简短报告，每个文件占一行：Markdown 的输出位置，以及找到的标题和表格数量。

适用于 AI Agent

• **适用场景：**你有一个包含真实文本（可以选中其中的文字）的本地 PDF，或一个已保存的 HTML 文件，并且希望将其转换为 Markdown 以供阅读或存储。
• **不适用场景：**PDF 是扫描件、文件是 .docx，或你需要处理大量文件或按页码拆分的内容。此类情况请使用付费版本。
• **输入：**文件路径，以及可选的 tables（lines、text、off）。
• **输出：**Markdown 文本。表格为 Markdown 表格，首行为表头。
• CLI 成功时的退出代码为 0，出错时为 1（错误消息会输出到 stderr；使用 --json 时则输出 {"ok": false, "error": ...}）。另请参阅 llms.txt。

Python

from doc2md_lite import convert
md, info = convert("report.pdf")   # info: type, tables, headings, scanned_pages

测试

pip install pdfplumber beautifulsoup4 reportlab "mcp<2"
python3 -m unittest discover tests

许可证

MIT。参见 LICENSE。