# Markitdown Converter

> 将用户明确指定的本地文件或目录批量规范化为 Markdown，并核验输出，适合知识库入库、检索和后续分析。仅在用户要转换成 Markdown、生成 md 文件或批量归一化时使用；如果只是阅读、总结、编辑或高保真还原 PDF、Word、PPT、Excel，使用相应文档 Skill，不触发本 Skill。

- Skill: `wjjjjjjjjjjj/markitdown-converter` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add wjjjjjjjjjjj/markitdown-converter`
- Raw SKILL.md: https://api.skillmd.com/api/skills/wjjjjjjjjjjj/markitdown-converter/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Data & Analytics
- Author: wjjjjjjjjjjj (https://skillmd.com/u/wjjjjjjjjjjj)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/wjjjjjjjjjjj/markitdown-converter

---


# MarkItDown 文件转换

把用户给出的源文件转换成适合检索、分析、知识库归档和大模型处理的 Markdown。MarkItDown 的目标是保留标题、段落、列表、表格和链接等语义结构，不追求复刻源文件的视觉版式。

已在 Windows PowerShell 5.1+ 与 MarkItDown 0.1.6 上验证。每次运行仍须探测命令版本及目标格式所需的可选依赖，不能把当前环境状态当作永久前提。

## 工作流程

1. 确定输入。
   - 优先使用用户明确给出的文件或目录。
   - 用户说“这些文件”但未给出路径时，先查看当前会话附件或当前工作区中最可能的文件；仍无法唯一确定时，只问一个关键确认问题。
   - 不要在未经用户同意的情况下扫描与任务无关的大目录。

2. 确定输出位置。
   - 用户指定位置时，遵从用户要求。
   - 单个文件且未指定位置时，默认在源文件同目录生成同名 `.md`。
   - 目录批量转换且未指定位置时，默认写入源目录下的 `markdown_output/`，递归转换时保留相对目录结构。
   - 不覆盖已有文件；脚本会自动生成 `-converted` 或数字后缀。只有用户明确要求覆盖时才传入 `-Force`。

3. 执行转换。

   ```powershell
   powershell -NoProfile -ExecutionPolicy Bypass -File "<skill目录>\scripts\convert.ps1" -InputPath "<输入文件或目录>"
   ```

   常见参数：

   ```powershell
   # 指定输出目录
   -OutputDirectory "<输出目录>"

   # 递归转换目录
   -Recurse

   # 用户明确要求时覆盖已有输出
   -Force

   # 用户明确需要第三方 MarkItDown 插件时启用
   -UsePlugins

   # 用户明确要求保留 data URI 时启用
   -KeepDataUris
   ```

4. 校验结果。
   - 读取脚本返回的 JSON 汇总。
   - 成功必须同时满足：命令退出正常、目标 `.md` 存在、文件大小大于 0。
   - 对 Word、PPT、PDF、Excel 等结构化文档，抽查 Markdown 的标题或关键文本，避免只生成空壳文件。
   - 批量转换时报告成功、失败、跳过数量，并列出失败文件及原因。

5. 回报用户。
   - 给出生成文件的可点击绝对路径。
   - 简要说明转换数量与失败项。
   - 如源文件主要由扫描图片构成，说明普通本地转换可能只得到有限文本；需要 OCR/视觉模型时再建议增强方案，不要把低质量结果说成完整提取。

## 安全与边界

- 保留源文件，不删除、不移动、不改写。
- 包装脚本只处理本地文件。URL 应先通过安全的网页获取流程下载到受控工作目录，完成来源与访问边界检查后，再把本地副本交给本 Skill；不要把 URL 直接传给脚本。
- 对不可信 ZIP 或 HTML，先确认输入来源；MarkItDown 会以当前进程权限读取它可访问的资源。
- 如果 `markitdown` 命令或目标格式依赖不可用，脚本必须返回结构化失败 JSON 和非零退出码。不要静默换用另一套转换器；需要重装时向用户说明。
- 所有转换先写入目标同目录的唯一临时文件，校验成功后再原子替换目标。失败时删除临时文件并保留旧 Markdown；不得把半成品留作成功结果。
- MarkItDown 适合内容提取和语义结构保留。用户要求“版式一模一样”“可编辑排版复刻”时，应改用对应的 PDF、Word、PPT 或表格工具。

## 支持范围

脚本批量扫描以下常见扩展名：

`.pdf`、`.docx`、`.pptx`、`.xlsx`、`.xls`、`.html`、`.htm`、`.csv`、`.json`、`.xml`、`.txt`、`.zip`、`.epub`、`.msg`、`.eml`、`.wav`、`.mp3`、`.jpg`、`.jpeg`、`.png`、`.gif`、`.tif`、`.tiff`、`.bmp`

若 MarkItDown 新版本增加格式，可对单个文件直接尝试转换；目录批量扫描前再把新扩展名补入脚本白名单。