将 Starlight 转换为 PDF：经验和见解

想象一下您收到一项任务：在一周内创建一个新的文档网站。它应该具有视觉吸引力、快速且易于导航。您会收到一堆 *.docs 文件、图像和屏幕截图，以及“完成它”.

的说明

有很多优秀的工具可供选择，例如Docusaurus、Nextra、VitePress、Docus等等。之前，我在使用 Starlight 构建文档网站方面获得了丰富的经验，因此我选择了它来完成这项任务。然而，我发现了一个缺失的功能：从文档生成 PDF 的能力。这是要求之一。 “听起来像是一个不错的副业项目，”我自己想的。

解决任务

起初，这似乎很简单：获取页面，解析 HTML，对内容进行分组，瞧！

星光驱动的网站有一个“下一步”按钮来浏览文档。由于 PDF 本质上是页面数组，因此使用“下一步”按钮逐一解析它们似乎是合乎逻辑的。由于网站生成静态页面，我很快编写了一个脚本来获取 HTML、查询必要的部分，并将所有内容组合在一起。然而，事实证明，生成保留网站样式的 PDF 更为复杂。经过一番头脑风暴，我意识到 Puppeteer 是最好的解决方案。

现在流程变得清晰了：

1. 确定起始页面。这是带有“下一步”按钮的第一页。
2. 浏览页面。从每个页面提取标题和主要内容，同时构建目录。
3. 合并内容。添加分页符和其他样式。
4. 准备最终的 HTML。 重写 包含生成的 HTML 的初始页面。
5. 加载资源。滚动页面至底部加载所有图片。
6. 生成 PDF。Puppeteer 的 Page.pdf() 方法可以解决这个问题。
7. 完成！

这就是starlight-to-pdf 的工作原理。遵循这种模式，您可以为缺乏 PDF 导出功能的其他文档框架构建类似的工具。

后续步骤

基本功能准备就绪后，就该添加一些额外功能了。以下是最有趣和最具挑战性的功能。

添加页眉和页脚

页眉或页脚中包含页码和一些附加信息是很好的。 Puppeteer 的 Page.pdf() 方法接受 headerTemplate 和 footerTemplate 选项。这些选项接受 HTML 字符串。 Puppeteer 自动将值注入到具有特定实用程序类的元素中：

• .date：格式化日期；
• .title：网页的标签值；
• .url: 调用打印函数的页面 URL;
• .pageNumber：当前页码；
• .totalPages: 文档的总页数。

当我们在打印之前将所有内容合并在一页上时，标题和网址对我们来说没有太大价值：插入的值将始终保持不变。然而，其他课程有很大帮​​助。这是页脚模板示例：

<style>
  .footer-container {
    --color: #000;

    display: flex;
    align-items: center;
    justify-content: space-between;
    border-block-start: 1px solid var(--color);
    color: var(--color);
    font-size: 10px;
    font-family: Arial, Helvetica, sans-serif;
    margin-inline: 1.5cm 1cm;
    padding-block: 0.25cm 0.5cm;
    width: 100%;
  }
</style>

<div>



<p>To use this, do not forget to set the displayHeaderFooter property to true:<br>
</p>

<pre class="brush:php;toolbar:false">import puppeteer from 'puppeteer';

const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.goto('https://someUrl');

const footerTemplateStr = '<style>...<style><div>...</style>