# py-markitdown

**Repository Path**: john-fields/py-markitdown

## Basic Information

- **Project Name**: py-markitdown
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-23
- **Last Updated**: 2026-06-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# py-markitdown

这个项目用于编写基于
[`markitdown`](https://github.com/microsoft/markitdown)
的文档转换脚本。

主要目标是集中保存文档转 Markdown 的实验脚本和常用工具脚本。

## 环境

使用项目本地虚拟环境：

```powershell
.\.venv\Scripts\python.exe
```

该虚拟环境使用 `pyenv-win` 管理的 Python 3.12.10 创建。

## 安装依赖

在虚拟环境中安装 `markitdown` 及 PDF 转换依赖：

```powershell
.\.venv\Scripts\python.exe -m pip install "markitdown[pdf]"
```

如果需要使用 PyMuPDF 版本脚本，安装：

```powershell
.\.venv\Scripts\python.exe -m pip install PyMuPDF
```

如果后续项目添加了 `requirements.txt`，可以使用下面的命令安装依赖：

```powershell
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
```

## 建议目录结构

```text
scripts/        转换脚本
input/          本地测试用的源文件
output/         生成的 Markdown 文件
```

## 示例

### 使用 markitdown 转换

```powershell
.\.venv\Scripts\python.exe scripts\pdf_to_md.py input\example.pdf output\example.md
```

### 使用 PyMuPDF 转换

```powershell
.\.venv\Scripts\python.exe scripts\pdf_to_md_pymupdf.py input\example.pdf output\example.md
```

## 转换效果说明

PDF 转 Markdown 的效果取决于 PDF 的原始结构。对于接口文档、表格较多、
版式复杂或由扫描图片生成的 PDF，`markitdown` 的转换效果可能不佳，常见问题包括：

- 标题层级识别不准确
- 表格结构丢失
- 换行、缩进和段落顺序混乱
- 图片或扫描内容无法提取为文本

如果 `markitdown` 效果不好，可以尝试 `scripts\pdf_to_md_pymupdf.py`，
再根据具体文档结构定制提取逻辑。

一个基础脚本可以导入 `MarkItDown`，并将文件转换为 Markdown：

```python
from markitdown import MarkItDown

converter = MarkItDown()
result = converter.convert("input/example.docx")

with open("output/example.md", "w", encoding="utf-8") as file:
    file.write(result.text_content)
```

使用项目虚拟环境运行脚本：

```powershell
.\.venv\Scripts\python.exe scripts\convert_example.py
```