快速开始

环境要求

必需依赖

• Python 3.11-3.13 - 运行时环境（由于 onnxruntime 限制，暂不支持 3.14）
• uv - 包管理器（推荐）

可选依赖

以下依赖用于特定功能：

依赖	用途	安装方式
Playwright	--playwright（SPA 渲染）	包随 markitai 安装，浏览器需运行 uv run playwright install chromium
FFmpeg	音视频处理	apt install ffmpeg (Linux) / brew install ffmpeg (macOS)
Jina API 密钥	--jina（URL 转换）	设置 JINA_API_KEY 环境变量
LLM API 密钥	--llm（AI 增强）	设置 OPENAI_API_KEY 或对应提供商的密钥。订阅制提供商（chatgpt/、gemini-cli/、claude-agent/、copilot/）使用 CLI/OAuth 认证
Cloudflare	--cloudflare（云端渲染与转换）	设置 CLOUDFLARE_API_TOKEN 和 CLOUDFLARE_ACCOUNT_ID 环境变量

浏览器自动化

对于 SPA 网站（Twitter、React 应用等），会自动使用 Playwright。首次使用前需安装浏览器：

uv run playwright install chromium
# Linux 还需安装系统依赖：
uv run playwright install-deps chromium

然后使用 --playwright 参数强制启用浏览器渲染。

安装

一键安装（推荐）

运行安装脚本，自动安装 Python、UV 和 markitai：

Linux/macOS

curl -fsSL https://raw.githubusercontent.com/Ynewtime/markitai/main/scripts/setup.sh | sh

Windows

powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/Ynewtime/markitai/main/scripts/setup.ps1 | iex"

安全提示

• 以 root/管理员 身份运行时脚本会发出警告
• 所有安装操作都需要明确确认（默认: 否）
• 远程脚本执行需要两步确认

脚本会：

• 检测 Python 3.11-3.13
• 安装 uv 包管理器（需要确认）
• 安装 markitai 及所有可选依赖

版本固定

使用环境变量固定特定版本：

Linux/macOS

export MARKITAI_VERSION="0.11.2"
export UV_VERSION="0.9.27"
curl -fsSL https://raw.githubusercontent.com/Ynewtime/markitai/main/scripts/setup.sh | sh

Windows

$env:MARKITAI_VERSION = "0.10.0"
$env:UV_VERSION = "0.9.27"
powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/Ynewtime/markitai/main/scripts/setup.ps1 | iex"

手动安装

# 使用 uv（推荐）
uv tool install markitai

# 或使用 uv pip（用于虚拟环境）
uv pip install markitai

快速上手

首次运行

新用户推荐使用交互模式，引导完成初始设置：

markitai -I

或使用配置向导初始化：

# 交互式配置向导
markitai init

# 快速模式（生成默认配置）
markitai init --yes

基础转换

将单个文档转换为 Markdown：

markitai document.docx

不指定 -o 时，输出打印到 stdout。使用 -o 可指定输出目录：

markitai document.docx -o output/

URL 转换

直接转换网页：

markitai https://example.com/article -o output/

LLM 增强

启用 AI 驱动的格式清洗和优化：

markitai document.docx --llm

这需要设置 API 密钥（参见配置说明）。

使用预设

Markitai 提供三种预设，适用于常见场景：

# Rich: LLM + alt 文本 + 描述 + 截图
markitai document.pdf --preset rich

# Standard: LLM + alt 文本 + 描述
markitai document.pdf --preset standard

# Minimal: 仅基础转换
markitai document.pdf --preset minimal

批量处理

转换目录中的多个文件：

markitai ./docs -o ./output

恢复中断的批量处理：

markitai ./docs -o ./output --resume

系统检查

验证所有依赖项，自动修复缺失组件：

# 检查系统状态
markitai doctor

# 自动修复缺失组件
markitai doctor --fix

输出结构

output/
├── document.docx.md        # 基础 Markdown（--llm 模式下默认跳过，除非加 --keep-base）
├── document.docx.llm.md    # LLM 增强版本（使用 --llm 时）
├── .markitai/               # 元数据命名空间
│   ├── assets/
│   │   ├── document.docx.0001.jpg
│   │   └── images.json     # 图片描述
│   ├── screenshots/         # 页面截图（使用 --screenshot 时）
│   │   └── document.docx.0001.png
│   ├── reports/             # 转换报告（JSON）
│   └── states/              # 批处理状态文件（用于 --resume）

TIP

在 --llm 模式下，默认只写入 .llm.md。使用 --keep-base 可以同时写入基础 .md 文件。

支持的格式

格式	扩展名
Word	.docx, .doc
PowerPoint	.pptx, .ppt
Excel	.xlsx, .xls
PDF	.pdf
文本	.txt, .md, .markdown
图片	.jpg, .jpeg, .png, .webp
URL	http://, https://

平台特定功能

部分功能在不同平台上有差异：

Windows

功能	支持	说明
旧版 Office（.doc、.xls、.ppt）	✅ 完全支持	使用 COM 自动化
PPTX 幻灯片渲染	✅ 完全支持	优先使用 MS Office，LibreOffice 备选
EMF/WMF 图片	✅ 完全支持	原生支持
浏览器自动化	✅ 完全支持	隐藏窗口模式

Linux

功能	支持	说明
旧版 Office（.doc、.xls、.ppt）	✅ 完全支持	需要 LibreOffice（Windows 使用 COM，LibreOffice 作为备选）
PPTX 幻灯片渲染	✅ 完全支持	需要 LibreOffice
EMF/WMF 图片	❌ 不支持	Windows 专有格式
浏览器自动化	✅ 完全支持	需要系统依赖

安装 LibreOffice：

# Ubuntu/Debian
sudo apt-get install libreoffice

# Fedora/RHEL
sudo dnf install libreoffice

安装 Playwright 浏览器：

uv run playwright install chromium
uv run playwright install-deps chromium  # 安装系统依赖

macOS

功能	支持	说明
旧版 Office（.doc、.xls、.ppt）	✅ 完全支持	需要 LibreOffice
PPTX 幻灯片渲染	✅ 完全支持	需要 LibreOffice
EMF/WMF 图片	❌ 不支持	Windows 专有格式
浏览器自动化	✅ 完全支持	-

安装 LibreOffice：

brew install --cask libreoffice

下一步

• 配置说明 - 配置 LLM 提供商和其他设置
• CLI 命令 - 完整命令参考