第 1 课
装好 MarkItDown，用命令行转换 Office、PDF、ZIP 和网页
在虚拟环境里装 markitdown[all]==0.1.9，下载官方测试文件，用 markitdown 命令把 Word、Excel、PowerPoint、PDF 转成 Markdown 并检查标题和表格，用 -x 从管道读入，转换 ZIP 和网址，再看看图片默认只输出元数据的原因。
课程目录第 1 / 3 课
学习位置仅保存在当前浏览器，有效期 180 天。
图文教材
本课对照的官方页面：MarkItDown GitHub 仓库 README 、PyPI：markitdown 0.1.9 。测试环境：2026-11-05，Linux x86_64 云主机，Python 3.13.5，markitdown 0.1.9。下面的「对照结果」都是这台机器的真实输出，只做了节选。
MarkItDown 是微软开源（MIT 许可证）的一个 Python 工具，作用只有一个：把 PDF、Word、Excel、PowerPoint、图片、音频、HTML、ZIP 等文件转成 Markdown，方便交给大模型或放进知识库。它保留标题、列表、表格、链接这些结构，不追求排版还原。本课用命令行把官方仓库自带的测试文件逐个转一遍，你会看到每种格式转出来是什么样子。
第 1 步：建虚拟环境并安装
MarkItDown 0.1.9 要求 Python 3.10 到 3.14。官方建议装在虚拟环境里。[all] 会把所有格式的可选依赖一起装上：
mkdir -p ~/markitdown-lab && cd ~/markitdown-lab
python3 -m venv .venv
source .venv/bin/activate
pip install "markitdown[all]==0.1.9"
markitdown --version
对照结果：
markitdown 0.1.9
如果只想处理少数几种格式，可以只装对应的可选依赖，例如 pip install "markitdown[pdf,docx,pptx]"。官方列出的可选项有 pptx、docx、xlsx、xls、pdf、outlook、az-doc-intel、audio-transcription、youtube-transcription。没装依赖的格式转换时会报错，并提示缺什么。
第 2 步：下载官方测试文件
官方仓库的测试目录里有现成的样例文件。用两行变量把地址拼起来，免得一行太长：
mkdir -p ~/markitdown-lab/files && cd ~/markitdown-lab/files
REPO=https://raw.githubusercontent.com/microsoft/markitdown
B=$REPO/main/packages/markitdown/tests/test_files
for f in test.docx test.xlsx test.pptx test.pdf test_files.zip \
test_llm.jpg; do
curl -sSO "$B/$f"
done
ls
对照结果：
test.docx
test.pdf
test.pptx
test.xlsx
test_files.zip
test_llm.jpg
第 3 步：转换 Word 和 Excel
markitdown 文件名 会把结果打印到终端，加 -o 则写入文件。先转 Word，再看看保留下来的标题：
markitdown test.docx -o docx.md
grep '^#' docx.md
grep -c '^| ' docx.md
对照结果：
# Abstract
# Introduction
## d666f1f7-46cb-42bd-9a39-9a39cf2a509f
7
Word 里的「标题 1」「标题 2」变成了 # 和 ##，表格变成了 7 行 Markdown 表格行。
Excel 的每个工作表会变成一个 ## 标题，下面跟一张表：
markitdown test.xlsx | head -4
markitdown test.xlsx | grep '^## '
对照结果：
## Sheet1
| Alpha | Beta | Gamma | Delta |
| --- | --- | --- | --- |
| 89 | 82 | 100 | 12 |
## Sheet1
## 09060124-b5e7-4717-9d07-3c046eb
这个样例文件有两个工作表，所以出现了两个 ## 标题（第二个工作表的名字本身就是一串编号）。
第 4 步：转换 PowerPoint 和 PDF
PowerPoint 每一页前面会加一行 HTML 注释，标明页码；页里的图表会转成表格：
markitdown test.pptx | grep -c 'Slide number'
markitdown test.pptx | grep -A3 'Chart:'
对照结果（第二段只节选前几行）：
6
### Chart: a3f6004b-6f4f-4ea8-bee3-3741f4dc385f
| Category | Series 1 |
|---|---|
PDF 只提取文字。PDF 文件本身不记录「这是标题」，所以转出来基本是纯文本段落：
markitdown test.pdf -o pdf.md
head -3 pdf.md
对照结果：
1
Introduction
如果需要识别扫描件或复杂版面，官方提供 Azure Document Intelligence（-d 加 -e 端点地址）和 Azure Content Understanding（--use-cu）两种云端方式，需要你自己的 Azure 资源。本课没有测试这两种方式（未实测）。
第 5 步：从管道读入，转换 ZIP 和网址
MarkItDown 也能从标准输入读文件。这时它看不到文件名，最好用 -x 告诉它扩展名：
cat test.pdf | markitdown -x pdf | head -3
对照结果和上一步一样：
1
Introduction
ZIP 压缩包会被逐个解开转换，每个文件前加一个 ## File: 标题：
markitdown test_files.zip | grep '^## File'
对照结果：
## File: test.docx
## File: test.jpg
## File: test.pptx
## File: test.xlsx
## File: test_blog.html
## File: test_serp.html
## File: test_wikipedia.html
直接给一个网址，它会下载网页并转换：
markitdown https://example.com/ | cut -c1-50
对照结果：
This domain is for use in documentation examples w
第 6 步：看看图片会怎样
markitdown test_llm.jpg | wc -c
对照结果：
1
图片默认只输出 EXIF 元数据，而读取 EXIF 要靠系统里装好的 exiftool 命令。测试机没装 exiftool，所以只得到一个换行符。要让它「看懂」图片内容，需要接一个视觉大模型，下一课用 Python 演示。
小结
- 安装：
pip install "markitdown[all]"，也可以只装需要的格式。 - 用法：
markitdown 文件 -o 输出.md；从管道读入时用-x 扩展名。 - Word、Excel、PowerPoint 的标题和表格都能保留；PDF 只有文字；ZIP 会逐个转换；网址可以直接转换。
- 图片默认只读元数据，要描述图片内容得接大模型。
