很多同学问，网站上的教程能不能下载成PDF离线学习？作为开发者，我理解这种需求——有时网络不稳定，或者想在通勤时随时翻看。今天想和大家聊聊我们团队是如何解决这个问题的，核心是“从技术实现到用户体验”的全链路思考。
一、先解决“能不能做”：技术原理不复杂
我们的教程系统用Markdown写内容，通过GitSite工具生成静态HTML页面。要把这些页面转成PDF，最直接的思路是：先把所有页面合并成一个长页面，再用浏览器打印功能输出PDF。
为什么不直接单页打印？因为多个问题：单页PDF多了会重复首页页脚，几十页教程手动拼接效率太低。合并成“长单页”后，一次打印就能生成完整文档，这是最基础的技术前提。
二、再解决“怎么做”：用工具链实现自动化
手动操作肯定不行，我们需要自动化工具。目前最成熟的方案是用Puppeteer——它相当于在本地“隐形”启动Chrome浏览器，通过API控制页面加载，最后输出PDF。核心代码很简单：
const puppeteer = require('puppeteer');
// 启动无头浏览器
const browser = await puppeteer.launch({ headless: true });
const page = await browser.newPage();
// 加载合并后的长页面
await page.goto('http://localhost:3000/books/python/merged.html', { waitUntil: 'networkidle0' });
// 输出PDF，设置页边距
await page.pdf({
path: 'python.pdf',
margin: { top: 80, left: 50, right: 50, bottom: 80 }
});
await browser.close();
三、关键体验优化：让PDF“好用”才是目的
技术实现后，还要考虑用户体验——目录、页眉页脚、书签、封面这些细节，决定了一个PDF文件的实用性。
1. 目录：让读者快速定位
在合并的长页面顶端加一个目录。每个章节标题用 <a href="#chapter-1"> 链接到对应章节的 <h1 id="chapter-1"> 标签。这样生成的PDF里，点击目录能直接跳转到对应位置，比翻页方便多了。
2. 页眉页脚：提升文档规范感
Puppeteer支持给每页添加页眉页脚，通过 displayHeaderFooter: true 启用，用HTML片段定义内容。比如：
headerTemplate: '<div style="font-size:12px;">Python教程 | 2025最新版</div>',
footerTemplate: '<div style="font-size:10px; margin:0 auto;">第 <span class="pageNumber"></span> 页 / 共 <span class="totalPages"></span> 页</div>'
注意这里的 pageNumber 和 totalPages 是Puppeteer自动填充的特殊变量，显示当前页码和总页数。
3. 书签：像“书架”一样管理内容
PDF阅读器的书签功能能帮用户快速导航。Puppeteer本身不支持生成书签，我们用了一个小技巧：先解析HTML里的章节ID，通过 pdf-lib 库获取每个章节在PDF中的页码，再生成一个 bookmark.txt 文件（符合PDF书签格式），最后用 pdftk 工具把书签合并到PDF里。
4. 封面和封底：给文档“仪式感”
封面和封底其实就是两个简单的HTML页面，分别生成单页PDF，再用 pdf-lib 把封面、合并后的主文档、封底三个PDF合并成一个完整文件。
四、总结：技术服务于需求，细节决定体验
从技术角度看，网页转PDF的核心是“页面合并+浏览器打印”，但要做好用户体验，需要处理好目录、页眉页脚、书签、封面这些细节。我们团队用Puppeteer、pdf-lib、pdftk这些工具链，把原本需要手动操作的步骤自动化，最终让用户拿到的不仅是一个PDF文件，更是一个“能快速阅读、方便导航”的学习资料。
其实技术本身不难，难的是从用户角度思考：他们需要的不是一个“能生成PDF的工具”，而是一个“真正能用起来的离线文档”。这也是我们一直追求的目标——让技术更懂人的需求。
