网页转 Markdown 再转 PDF：个人知识库与文档交付的完整方案-平芜编程栈

你有没有过这种经历：收藏夹里躺了几百个教程网页，真到要用的时候却搜不到、打不开，或者被满屏广告和侧边栏干扰得根本没法读。我前几年整理技术笔记时被这个问题折磨得够呛，后来彻底换成了“把教程网页先下载成 Markdown 文档，需要分发阅读时再转成 PDF”的流程，算是把这个问题解决干净了。这篇文章就是我整理出来的完整做法：怎么把几乎任何教程网页转成结构清晰的 md 文档，又怎么在需要的时候变成排版稳定的 PDF，适合正在搭个人知识库的人，也适合需要把网页内容整理成规范文档交付给同事或客户的场景。

整个过程没有高深的门槛，主要用到浏览器插件、命令行工具、编辑器导出和 Pandoc 这几样东西。我会把每个方案的适用场景、操作步骤和踩过的坑都拆开讲，你可以直接照着抄。

1. 存网页这件事，为什么非得转成 Markdown 不可

1.1 直接存网页、截图，到底哪里不舒服

很多人保存教程网页的习惯是“另存为 HTML”或者截图。这个做法不是不行，只是后续维护成本极高。

先说存 HTML 文件。一个完整的网页另存下来，通常伴随一个同名的_files文件夹，里面是图片、脚本、样式表，稍微复杂点的页面会有上百个文件。你把它存进笔记软件，笔记软件不一定能渲染里面的交互组件；你把它放在网盘里，想全文搜索关键词时，搜出来的是一堆压缩过的 JS 代码和 CSS 选择器，根本搜不到正文。更要命的是，很多网站的正文是异步加载的，“另存为”存下来的其实只是页面骨架。

截图就更不用说了。截图最大的问题是信息固化，你截下来的是“当时的像素”，不是“内容”。想复制一段代码？不行，只能照着敲。想改一个错别字？不行，得重新截。想搜一下截图里的某个名词？不行，文字已经变成图片的一部分了。短期应急可以，长期沉淀资料库不行。

1.2 谁是 Markdown 的“舒适区”，PDF 又该什么时候出场

Markdown 在这里的价值，本质上是一种“中间格式”。

它把网页里乱七八糟的结构清洗掉，只保留标题、段落、列表、代码块、表格、图片引用这些有语义的内容。因为它是纯文本，任何平台都能打开，任何编辑器都能编辑，放进 Git 里可以做版本管理，放进 Obsidian、Logseq、工作流里能被全文索引。它不像 Word 那样把排版和内容绑在一起，也不像 HTML 那样有一堆标签干扰阅读。

但 Markdown 不适合直接拿去“交付”。

你整理一份技术方案给不写代码的同事，发一个.md文件过去，对方可能都不知道用什么东西打开。你想打印一份操作手册放机房，或者发给客户存档，Markdown 在不同设备上渲染效果不一样，换台电脑字体、间距全变了。这种时候就需要 PDF 出场——PDF 是“所见即所得”的终态格式，跨设备显示稳定，不可轻易改动，适合打印、归档、走正式流程。

所以我的建议是：Markdown 负责“存储和编辑”，PDF 负责“输出和分发”。两者不是二选一的关系，而是一条流水线上的两个环节：网页 → md → PDF。

2. 网页抓成 md 的三种主流姿势：插件、命令行、在线平台

把网页转成 Markdown，看起来就是个“去标签化”的活，但实际做起来牵扯到正文提取、图片下载、代码块保留、站点反爬等等问题。我试下来，有三种路线比较靠谱，分别对应不同场景。

2.1 浏览器插件路线：最省事的单篇抓取

如果你是偶尔存一两篇文章，强烈建议直接用浏览器插件，不用写任何代码。

我最常用的是 MarkDownload，这是一个开源项目，Chrome 和 Firefox 都能装，Edge 也能直接从商店装。它做的事情很简单：把当前页面的正文提取出来，转成 Markdown，然后下载成一个.md文件。你甚至可以设置快捷键，在页面里按一下Alt + M，文档就直接存到本地了。

安装完建议先改两个地方：

下载目录。默认会存到“下载”文件夹，我建议改成专门的资料目录，比如~/Documents/KnowledgeBase/Inbox，后续整理起来方便。
图片处理方式。插件默认会把图片保留成远程 URL。如果你希望离线阅读，可以把“下载图片”选项打开，让插件把图片一并下载到本地，并把 md 里的路径改成相对路径。

实测下来，MarkDownload 对博客、技术文档、Wiki 类网站的识别效果都很好，能正确保留标题层级和代码块。但遇到本身就是单页应用（SPA）的网站，比如某些在线工具文档，正文可能是 JavaScript 动态渲染的，这时候插件抓到的内容可能残缺。遇到这种情况，可以先把网页完整加载后等一等再点击抓取，有时候能抓到。

如果你用 Obsidian 做笔记，还可以考虑 Obsidian 的 Web Clipper 插件，配合官方的 Web Clipper 浏览器扩展，等于把网页内容直接投送进笔记库，自动带上来源 URL 和抓取时间，比先下载再导入少一步。

2.2 命令行路线：适合批量、定时、脚本化的场景

当你要处理的不是一篇文章，而是一个教程频道的几十个页面，浏览器插件一个个点就太累了。这时候上命令行工具。

我对普通用户推荐 trafilatura，这是一个 Python 库，专门做网页正文提取，对新闻、博客、文档站效果极好。安装只需要一条命令：

pip install trafilatura

抓取单个页面并输出 Markdown：

trafilatura --url "https://example.com/tutorial" --output-format markdown > tutorial.md

它会自动识别正文区域，去掉导航、页脚、广告这些干扰内容。比你自己写正则清理 HTML 靠谱得多。

如果你想批量抓取一个站点的多个页面，可以写个简单的 Python 脚本：

import trafilatura urls = [ "https://example.com/docs/page1", "https://example.com/docs/page2", "https://example.com/docs/page3", ] for url in urls: downloaded = trafilatura.fetch_url(url) result = trafilatura.extract(downloaded, output_format="markdown", include_links=True) if result: # 根据 URL 生成文件名，这里只是示例 name = url.rstrip("/").split("/")[-1] or "index" with open(f"{name}.md", "w", encoding="utf-8") as f: f.write(result)

这段代码不建议直接复制就跑，因为真实场景里你需要处理文件名冲突、请求间隔、失败重试。但你完全可以把它作为起点：加上time.sleep(1)做请求间隔，用os.makedirs建目录，就能变成一个稳定的抓取脚本。

另一个不能不提的命令行工具是 Pandoc——它是文档格式转换的瑞士军刀，后面转 PDF 也要靠它。如果你想直接拿一个 HTML 文件转 Markdown，可以：

pandoc input.html -t gfm -o output.md

但说实话，Pandoc 做 HTML 转 Markdown 时，对网页正文的“清洗”能力不如 trafilatura，处理含大量导航和广告的页面时，转出来的 md 会带很多无关内容。所以我通常用 trafilatura 做正文提取，用 Pandoc 做后期转换。

2.3 在线服务和自动化平台：省心但要注意数据隐私

有些人不想装 Python，也不想折腾插件，那在线工具是最直接的。

网上搜“网页转 Markdown”，能搜到不少服务，比如一些免费的 HTML to Markdown 转换站，把网页 URL 粘贴进去就能得到 Markdown 文本。这类工具的优点是没有环境依赖，打开浏览器就能用；缺点也明显：你要把 URL 发给第三方服务，如果网站有登录态或者限流，大概率抓不到内容。对于公开的、不敏感的教程页面，应急用一下可以，但我不建议把公司内网文档、涉及账号信息的页面丢进去。

自动化平台是这两年比较热门的方案。你可以在 Coze 或类似的自动化工作流平台里搭一个“网页转 Markdown 再转 PDF”的流程，用别人做好的插件节点，把 URL 传进去，自动抓取、转换、保存到云盘或知识库。

这种方案适合处理高频、同质化的内容源。比如你每天早上要把几个固定网站的教程摘要汇总成一份 PDF 发到群里，那自动化流程能省不少事。但它的问题在于依赖平台的服务稳定性，一旦某个网站的页面结构改了，或者平台调整了插件策略，你的“机器人”可能就悄悄失效了。而且中间经手的服务越多，出错的环节也越多。

我个人的态度是：在线工具适合“偶尔一次”需求，核心工作流还是本地跑，数据在自己手里，出错了好排查。

3. 从 md 到 PDF：方案选不好，导出白忙活

很多人到这一步觉得“不就导出个 PDF 吗”，结果一操作发现：中文乱码、代码没有高亮、表格超出页面、目录缺失…… 其实在动手之前，先想清楚 PDF 拿去哪里用，比选什么工具更重要。

3.1 先想清楚：你的 PDF 是拿来干嘛的

我把常见的输出场景分成三类：

个人阅读/同步：自己离线看、导入平板做批注、发到手机上随手翻。这类场景对排版要求不高，能看就行，用编辑器自带的导出功能就够。
团队分享/协作交付：给同事写技术方案、给客户提供操作手册。这类场景要求结构清晰、有目录、代码可读，最好直接用浏览器或专业工具导出，保证字体和样式统一。
打印/正式归档：签字版协议、公告、规范文档。这类场景必须控制页面边距、页眉页脚、目录页码，通常需要 PDF 版式完全固定。

想清楚是哪种，再选下面的方案。

3.2 快速路线：编辑器自带 PDF 导出

如果你用 Typora，那导出 PDF 几乎是零成本。Typora 的“文件 → 导出 → PDF”走的是内置渲染引擎，你在编辑窗口里看到什么样子，导出的 PDF 基本就是什么样子，代码高亮、表格样式都能保留。它有“主题”设置，想要接近论文排版就选 Github 主题，想要清爽就选 Newsprint 主题。

在导出前，建议手动检查这几个设置：

主题里面字体大小，我习惯正文 14px 或 15px，导出后阅读比较舒服；
代码块字体用等宽字体，比如Consolas或JetBrains Mono；
边距设置在“偏好设置 → 导出 → PDF”里，默认边距偏大，打印的话可以缩小一点。

VS Code 上也有不少好用的导出工具，比如“Markdown PDF”插件。安装后在打开的 md 文件上右键，就能看到“Markdown PDF: Export (pdf)”选项。这个插件的默认样式是白色背景、黑色文字，适合技术文档；但它默认不支持自定义中文字体，如果你对中文排版很讲究，还是走下面 Pandoc 的路线更稳。

3.3 专业路线：Pandoc + LaTeX 排版

当文档超过十页、有大量标题层级、需要在目录里体现所有章节，或者你想完全控制页边距、字体、页眉页脚，那 Pandoc 是绕不开的。

Pandoc 本身不带 PDF 引擎，它负责把 Markdown 转成 PDF 中间需要的格式，实际生成 PDF 可以走 LaTeX、wkhtmltopdf 或 WeasyPrint。最常见的是 LaTeX 引擎，我用的是 XeLaTeX，因为它在处理中文字体方面比默认的 pdflatex 省心得多。

一个最简单的转换命令：

pandoc input.md -o output.pdf --pdf-engine=xelatex

但如果你直接跑上面这条命令，中文内容很可能会变成“方块”或者直接报错。原因很简单：XeLaTeX 默认字体不包含中文字形，你需要显式指定一个系统中文字体。比如在 Linux 上：

pandoc input.md -o output.pdf \ --pdf-engine=xelatex \ -V CJKmainfont="Noto Serif CJK SC" \ -V geometry:margin=2.5cm

在 macOS 上可以把CJKmainfont换成"PingFang SC"或"Songti SC"，在 Windows 上可以换成"SimSun"或"Microsoft YaHei"。

如果你的文档里有代码块，最好加上代码高亮和草稿样式：

pandoc input.md -o output.pdf \ --pdf-engine=xelatex \ --highlight-style=espresso \ -V CJKmainfont="Noto Serif CJK SC" \ -V geometry:margin=2.5cm

Pandoc 默认还会生成 PDF 书签，也就是“PDF 目录”，在阅读器侧边栏可以直接跳转章节。这是它在正式文档场景下比编辑器导出强很多的地方。

缺点也很明显：LaTeX 的生态比较重，第一次装环境可能劝退一部分人；报错信息像天书，一个标点符号问题都可能让你折腾半天。所以我的建议是，只负责写 Markdown，不要花太多时间调 LaTeX 细节，记住上面这条命令就够用。真遇到复杂需求，再去查 Pandoc 变量说明。

3.4 网页化路线：先转 HTML 再打印

还有一种场景你可能经常碰到：网页上没有提供“另存为 Markdown”的插件，但你用浏览器打开这个页面已经很完美了，只是想把当前页面存成 PDF。

这种场景根本不用经过 Markdown，直接用浏览器打印功能就行。在 Chrome 或 Edge 里按Ctrl + P（macOS 是Cmd + P），打印机选择“另存为 PDF”，就能把当前网页截图式地输出成 PDF。

但这个做法有几个关键选项，不设置好效果会很差：

背景图形：默认不勾选，网页里的深色代码块会变成白底黑字，某些文字在白底下可能看不清，建议在“更多设置”里勾上“背景图形”。
页眉和页脚：默认会带上 URL 和日期，显得很乱，建议关闭。
边距：可以选“无”或“默认”，如果是打印，选“默认”；如果是电子存档，选“无”更美观。

如果你想把 Markdown 转成 HTML，再通过浏览器打印，可以先用 Pandoc 把 md 转成带样式的 HTML：

pandoc input.md -o output.html --standalone --embed-resources --metadata title="文档标题"

加上--embed-resources的意思是 CSS、图片都内嵌进 HTML，变成一个单文件，发出去也不会因为图片路径丢失而裂图。

3.5 四个方案怎么选

方案	适合场景	优点	缺点
Typora/编辑器导出	短文档、个人阅读	所见即所得、零配置	排版自由度低
VS Code Markdown PDF 插件	短文档、极客习惯	可直接在编辑器里操作	中文字体控制一般
Pandoc + XeLaTeX	长文档、正式交付、打印	排版精细、有目录、可定制性强	环境配置复杂
浏览器打印转 PDF	网页快照、已转 HTML 的场景	傻瓜式、能保留页面渲染效果	无法精确控制分页和页眉

4. 最容易翻车的四个地方：图片、代码、表格、数学公式

网页转 Markdown 再怎么成熟，也不是所有内容都能原样平移。我用了这么多年，最常翻车的地方就四个：图片、代码、表格、数学公式。这块只能一个个解，不能指望一个工具全解决。

4.1 图片：外链离线失效问题与相对路径改造

网页转出来的 md 默认图片是远程 URL，比如：

![示意图](https://example.com/images/architecture.png)

文档打开时，Markdown 编辑器会实时去加载这个图片。问题在于：

网站可能做防盗链，你在本地打开时图片加载不出来；
网站可能过段时间就删图，或者整站下线；
你把 md 文件发给别人，对方那里没有外网，图片直接变成“裂图”。

解决办法有两个方向。

第一个方向是“下载图片到本地”。MarkDownload 插件有这个选项，但如果你已经用命令行抓了，就得自己补一步。可以用一个简单的 Python 脚本：

import os import re import urllib.request from pathlib import Path def download_images(md_path, output_dir="images"): md_path = Path(md_path) text = md_path.read_text(encoding="utf-8") images = re.findall(r"!\[.*?\]\((https?://[^)]+)\)", text) os.makedirs(md_path.parent / output_dir, exist_ok=True) for url in images: name = os.path.basename(url.split("?")[0]) dest = md_path.parent / output_dir / name try: urllib.request.urlretrieve(url, dest) # 把 md 里的远程 URL 替换成相对路径 text = text.replace(url, f"{output_dir}/{name}") except Exception as e: print(f"下载失败: {url}, error: {e}") md_path.write_text(text, encoding="utf-8")

脚本的思路很直接：用正则把 md 里所有远程图片 URL 找出来，逐个下载到images目录，再把 md 里的链接替换成相对路径。注意正则只匹配https?://，如果你遇到其他协议（比如data:图片），得单独处理。

第二个方向是“保留一段 HTML 原始结构”。如果你只是想把图片位置在 PDF 里占住，不一定要本地化，那直接用<img src="...">标签嵌在 Markdown 里，Pandoc 转 PDF 时通常也能识别。不过我还是建议核心资料走本地化路线，毕竟长期运维最怕外链失效。

4.2 代码块：语言标记、缩进与渲染还原

网页转成 Markdown 后，代码块最容易出现两个问题。

第一个问题是语言标记丢失。原网页的代码高亮是网页渲染时靠 JavaScript 实时计算的，Markdown 代码块本身只存文本，不会自动带上python、javascript这类语言标记。如果你不手动加，导出的 PDF 里代码也不会自动高亮。所以抓下来后，我一般会扫一遍全文，给关键代码块补上语言标记：

```python print("hello") ```

第二个问题是缩进被网页样式破坏。有些网页在代码区块里用的是全角空格或制表符，复制下来后在 Markdown 编辑器里看起来对齐，但转 PDF 就对不齐了。遇到这种情况，我有个笨办法：把代码块内容粘到一个临时文件里，用编辑器统一把空格替换成真正的 Tab，或者固定为 4 空格缩进。在 VS Code 里直接按Shift + Alt + F（前提是安装了对语言的格式化扩展）也能自动整理。

如果你抓的是带行号的代码教程，还要注意“行号是不是代码的一部分”。网页上所谓行号其实是独立的 DOM 元素，MarkDownload 或 trafilatura 通常能识别并去掉，但偶尔会有残留。发现行号混进代码里，直接在文本里删掉就好了，没必要纠结。

4.3 表格：复杂表格别硬刚 md

Markdown 表格是出了名的“能力有限”：不支持单元格合并，不支持嵌套，列宽全靠空格对齐。网页上常见的复杂表格，比如有多级表头、单元格跨行跨列的那种，转成 Markdown 后经常直接变成惨不忍睹的拼合单元格。

我的经验是：遇到复杂表格，别强转成 Markdown 语法。

有两个替代方案。

第一个方案是把表格保留成 HTML 片段。Pandoc 支持混合内容，在 Markdown 里直接写<table>标签，Pandoc 转 PDF 或 HTML 时能完美保留表格结构。比如：

## 参数表 <table> <thead> <tr><th>名称</th><th>作用</th></tr> </thead> <tbody> <tr><td>timeout</td><td>请求超时时间（秒）</td></tr> <tr><td>retry</td><td>失败重试次数</td></tr> </tbody> </table>

这样做的好处是既能在编辑阶段看清结构，又能在导出阶段正确渲染。缺点是在纯文本工具里阅读这段内容时会看到标签，但这比表格乱掉更能接受。

第二个方案是“表格转 Excel”。很多人不知道，Markdown 表格是可以直接粘进 Excel 的。你把表格区域复制成 CSV 格式，再用 Excel 的数据导入功能打开，能快速变成可筛选、可排序的表格。这个场景有点反向：你不是要用 Markdown 做表格，而是要把网页上的表格先用插件导成 CSV，再转回 Excel 分析。但如果你手里已经有一个乱掉的 md 表格，最快的方式其实是把它粘贴到一个支持 CSV 导入的在线工具里，重新格式化。

4.4 数学公式：渲染引擎与转义冲突

数学公式是另一个重灾区。

Markdown 对数学公式的支持，通常依赖 MathJax 或 KaTeX 这些 JavaScript 库。网页本身公式渲染没问题，问题出在“从 HTML 转 Markdown”时公式的表达方式不一致。

有些网页用 MathML，有些用 LaTeX 字符串，有些是图片公式。转到 Markdown 后，你看到的可能是这样的乱码：

\[ f(x) = \frac{d}{dx}\left( \int_0^x f(u)\,du\right) \]

也可能是渲染失败的$ ... $和\$ ... \$混在一起。我的处理建议分两种情况：如果只是纯阅读，不必纠结公式源码，直接保留原样；如果你要在自己的文档里引用这个公式，最好手动统一成 $...$ 或$$...$$格式，并确保在同一个编辑器里渲染正常。

Pandoc 转 PDF 时处理数学公式比较省心，它天然支持 LaTeX 数学语法，只要你的 Markdown 里公式格式正确，XeLaTeX 就能直接编译。但要注意，Markdown 的转义可能影响公式里的_、*等符号，比如 $x_i$ 里的下划线可能被解释为斜体标记。遇到这种问题，一个技巧是把公式放在两个美元符号之间，并把_写成\_，或者在代码块内放公式。

如果你主要用 Typora，我建议开启“Markdown 扩展语法”中的“数学公式”选项，并选择“行间公式”使用$$包裹，这样导出 PDF 时兼容性最好。

5. 我现在实际在用的这套流程（含踩坑记录）

讲完各个模块，我把我自己现在跑通的流程完整写一遍，你可以对照搭建。

5.1 单篇知识采集流程

我的个人资料库分三层：Inbox（待整理）、Literature（精读文章）、Vault（正式笔记）。

单篇采集时，我用 MarkDownload 直接把网页存成 md 文件到Inbox目录，图片选项设置为“下载到本地”。存下来后，我会在 Obsidian 里打开，做三件事：

补上文章元信息：来源、作者、日期、标签；
把折叠的正文展开，检查是否抓到所有标题层级；
如果文档里有核心结论，我会单独写一段“摘要”，方便日后检索。

这一套流程只需要一分钟，但是让资料库保持可用的关键。

5.2 批量整站教程的抓取与合并

当我要把一个完整教程系列抓下来做离线文档时，我用 Python 脚本 + trafilatura 批量抓取。脚本会做三件事：

按 URL 列表抓取正文并清洗；
把多篇文章按顺序合并成一个 Markdown 文件；
在每一篇开头用 H1 标题标记原始 URL，方便溯源。

合并命令本质上是把几个 md 文件拼接在一起，但要注意在文件之间加---分隔线，否则 Pandoc 会把相邻文章的标题层级搞混。合并后的文件再走 Pandoc 导出 PDF，就是一本可以离线翻看的“教程合集”。

一个我常用的小技巧：在合并文件时，用toc变量开启目录：

pandoc combined.md -o tutorial.pdf \ --pdf-engine=xelatex \ --toc \ --toc-depth=2 \ -V CJKmainfont="Noto Serif CJK SC"

--toc-depth=2的意思是目录只显示到二级标题，避免教程里三四级标题太多让目录显得杂乱。

5.3 踩坑与补救记录

踩过的坑不少，挑四个最有代表性的说。

第一个坑是本地图片目录名带空格导致加载失败。MarkDownload 下载图片时，如果原网页图片文件名里有空格，生成的相对路径可能没有做 URL 编码，在 Obsidian 里显示正常，但 Pandoc 转 PDF 时会报“找不到图片”的错误。这个问题的处理方式是写脚本时统一把图片重命名为“文档名-序号”的格式，彻底绕开空格问题。

第二个坑是抓取后代码块里多了行号。有一次抓某个含有大量示例代码的教程，每个代码块前面都多了几位行号文本。后来在脚本里加了一步，用正则匹配“数字 + 竖线”开头的行并删除，才解决问题。这个坑提醒我，任何网页转 md 工具都做不到百分之百精准，总要预留一手手动清理时间。

第三个坑是Pandoc 导出中文 PDF 全是方块字。这个问题前面提到过，根源就是没指定 CJK 字体。Google 搜“pandoc 中文乱码”能搜到一堆帖子，绝大多数都是这个原因。我现在习惯把CJKmainfont写进一个固定的环境变量或者配置文件里，而不是每次命令行手敲。

第四个坑是HTML 转 md 后表格列宽失控。有些网页的表格用固定px宽度控制，转成 Markdown 后列宽完全依赖内容和空白对齐，在手机上阅读经常错位。所以我现在碰到大表格，就直接在 md 里保留 HTML 表格片段，不转了。

5.4 工具组合建议

最后聊一下组合。

我给不同人群的推荐组合：

人群	推荐组合
偶尔存几篇文章的普通用户	MarkDownload + Typora 导出 PDF
常写技术文档、需要交付给团队的开发者	VS Code + Markdown PDF 插件 + Pandoc
需要批量抓取整套教程做知识库的人	Python + trafilatura + Pandoc + Obsidian
不想碰代码的办公室用户	在线网页转 md 站 + 浏览器 Ctrl+P 打印另存 PDF

工具不在多，顺手最重要。我之前很长一段时间只用 Typora，后来因为要做批量导出，才慢慢把 Pandoc 和 trafilatura 加进工作流。你不需要一上来就把整套方案装齐，先解决当前最痛的问题，先把“网页存成本地 md”这件事跑起来，后面再补充 PDF 输出就顺理成章了。

我现在最常用的组合就是：MarkDownload 抓单篇，trafilatura 抓批量，Pandoc 出 PDF，复杂表格直接保留 HTML 块。每次看到有人还在用截图存教程，我都会说，趁早换掉。前两周可能不习惯，用顺了之后你会发现自己的资料库从一堆“死图”变成了可以跟写作、思考、发布无缝衔接的资产。