wehub/alchaincyf--huashu-md-html

Fork 0

Files

T

wehub-resource-sync 42139b9974 chore: import upstream snapshot with attribution

2026-07-13 12:33:19 +08:00

5.2 KiB

Raw Permalink Blame History

markitdown cookbook — 各文件类型的转换最佳实践

这个 cookbook 是能力1（万物→md）的实战参考。脚本 scripts/any_to_md.py 包装了下面所有用法。

安装

# 推荐：一次到位
pip install 'markitdown[all]'

# 可选 extras（按需选）
# pdf docx pptx xlsx xls outlook audio-transcription youtube-transcription az-doc-intel
pip install 'markitdown[pdf,docx,pptx,xlsx]'

需要 Python ≥ 3.10。

各类型 cookbook

PDF

python scripts/any_to_md.py file.pdf -o out.md

适用场景：原生PDF（含可选文本层）。

坑与降级：

扫描PDF（图片PDF）→ 默认输出几乎为空，必须挂 LLM 或 Azure Document Intelligence
复杂表格（合并单元格、嵌套）→ 单元格语义可能丢失
带图表/图片的PDF → 图片不会被OCR，只保留文件名

降级路径：

# 挂 LLM 描述图片（要 OPENAI_API_KEY）
python scripts/any_to_md.py file.pdf --llm-describe

# 挂 Azure Document Intelligence（高保真扫描件）
python scripts/any_to_md.py file.pdf \
  --azure-doc-intel "https://xxx.cognitiveservices.azure.com/"

DOCX

python scripts/any_to_md.py document.docx -o out.md

质量：对纯文本/标准排版的Word文档接近无损。Heading 1/2/3 能正确映射成 # ## ###。

坑：

文本框、SmartArt、复杂浮动布局 → 会被扁平化或丢失
修订标记、批注 → 默认不保留
嵌入的图片 → 提取出文件名占位，不内嵌

PPTX

python scripts/any_to_md.py deck.pptx -o out.md

输出结构：每张幻灯片 = 一个 ## Slide N 段落，包含文字 + speaker notes。

坑：

动画、过渡、布局完全丢失
图表数据丢失（只保留chart的标题）
用作"AI消化PPT内容"OK，用作"还原幻灯片"则不够

XLSX / XLS

python scripts/any_to_md.py spreadsheet.xlsx -o out.md

输出：每个worksheet 转成 markdown table。

坑：

公式不会被evaluate，只看cell的当前值
合并单元格 → 拆开
数据透视表、图表 → 丢失

替代：复杂Excel分析用 xlsx skill 或 pandas 直接处理，这里只用于"提取干净文本喂AI"。

HTML

python scripts/any_to_md.py page.html -o out.md

质量：对简单HTML（带article/section/p/h1-6/ul/ol）很好。复杂页面（带nav/aside/广告）会保留所有HTML结构产生噪声。

推荐：HTML转md优先用能力3（html_to_md.py），它有 trafilatura 做正文提取，自动去噪。

图片（jpg/png/gif）

# 不挂LLM：只提取EXIF和文件名
python scripts/any_to_md.py photo.jpg

# 挂LLM：让模型描述图片内容
python scripts/any_to_md.py photo.jpg --llm-describe

需要 OPENAI_API_KEY 和 pip install openai。

音频（mp3/wav/m4a）

# 需要先装 audio-transcription extra
pip install 'markitdown[audio-transcription]'

python scripts/any_to_md.py recording.mp3 -o transcript.md

底层用 pydub + speech_recognition，离线可用，但准确度随音质变化大。

替代方案：花叔的工作流里更高质量的方案是 huashu-subtitle skill（豆包Audio API），准确度更高，特别是中文长音频。

YouTube URL

# 需要先装 youtube-transcription extra
pip install 'markitdown[youtube-transcription]'

python scripts/any_to_md.py "https://www.youtube.com/watch?v=xxx" -o video.md

会自动抓取YouTube字幕（如有）。没有字幕的视频会失败，需要降级到 gemini-video skill。

EPub

python scripts/any_to_md.py book.epub -o book.md

按章节切分输出，每章一个 H1/H2。封面图、文内插图丢失。

ZIP

python scripts/any_to_md.py archive.zip -o archive.md

行为：递归解包，每个内部文件按其类型转md，按目录结构组织。

Outlook .msg

pip install 'markitdown[outlook]'
python scripts/any_to_md.py email.msg -o email.md

提取主题/发件人/收件人/正文/附件名。附件本身不会被转换。

一条龙工作流

# PDF白皮书 → md → 精美阅读html
python scripts/any_to_md.py whitepaper.pdf -o wp.md
python scripts/md_to_html.py wp.md --theme report -o wp.html

# YouTube视频 → md脚本 → 文章博客
python scripts/any_to_md.py "https://youtube.com/watch?v=xxx" -o talk.md
# 编辑 talk.md，改写成文章...
python scripts/md_to_html.py talk.md --theme article -o blog.html

何时不用 markitdown

任务	用什么
需要保留布局精度（不只是文本）	直接用 PDF reader / docx 库 / pptx skill
需要OCR扫描件	挂 LLM 或 Azure DocIntel；或专门 OCR 工具（Tesseract/PaddleOCR）
需要分析数据（不是提取文本）	xlsx skill 或 pandas
中文音视频转写	`huashu-subtitle`（豆包API）或 `gemini-video`
HTML 网页（带噪声）	直接用本skill的能力3（`html_to_md.py`）

已知的版本变化

v0.1.5（2026-02-20）：内存内转换、PDF表格对齐改善、插件架构开放
v0.1.x 之前：表格还原差，建议升级到最新

# 检查当前版本
pip show markitdown | grep Version

# 升级
pip install -U 'markitdown[all]'

5.2 KiB Raw Permalink Blame History Unescape Escape