首页 > 文章 > 前端

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

来源：dev.to

时间：2025-01-15 23:00:50 410浏览收藏

哈喽！大家好，很高兴又见面了，我是golang学习网的一名作者，今天由我给大家带来一篇《将 Starlight 转换为 PDF：经验和见解》，本文主要会讲到等等知识点，希望大家一起学习进步，也欢迎大家关注、点赞、收藏、转发! 下面就一起来看看吧！

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

的说明

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

解决任务

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

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

现在流程变得清晰了：

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

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

后续步骤

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

添加页眉和页脚

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

.date：格式化日期；
.title：网页的<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 class="footer-container">
  <div>awesome docs</div>
  <div>
    <!-- numbers inside the elements with `.pagenumber` and `.totalpages` classes are injected automatically by puppeteer -->
    <span class="pagenumber"></span> / <span class="totalpages"></span>
  </div>
  <!-- same for the `.date` class value -->
  <div class="date"></div>
</div>

要使用此功能，请不要忘记将 displayheaderfooter 属性设置为 true：

import puppeteer from 'puppeteer';

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

const footertemplatestr = '<style>...<style><div>...</div>' // replace with the html string from the example above
await page.pdf({
    displayheaderfooter: true,
    footertemplate: footertemplatestr
})

以下是您应该牢记的一些发现：

模板必须是有效的 html 结构。
定义 font-size css 属性，puppeteer 的默认值为 0。
使用内联 <style> 标签来定义您的样式。网站样式在模板内不可用。
图像应编码为 base64 字符串。
使用 puppeteer 的边距选项来实现所需的布局。

cli 样式怎么样？

一切正常，生成的 pdf 看起来很棒，但终端消息感觉平淡无奇。对细节的关注将好与伟大区分开来，不是吗？让我们的消息更加丰富多彩、更易于阅读。

这就是 ansi 转义序列的魔力。我认为 4 位颜色足以完成这项工作。假设您想要红色背景上的白色文本（这就是我用于[错误]：错误消息之前的前缀）。以下是实现这种外观的方法：

console.log('\x1b[37;41m', 'white on red message');

让我们来分解一下：

x1b[ 是十六进制转义码（您也可以使用 u001b 作为 unicode 替代）；
37 是前景色白色，其中 3 代表前景色，7 代表白色；
41 是背景红色，其中 4 代表背景，1 代表红色。

一切正常，但现在我们所有的 console.log() 输出都将以这种方式设置样式。要将样式重置回默认值，只需在末尾添加重置序列 x1b[0m：

console.log('\x1b[37;41m', 'white on red message', '\x1b[0m');

好多了。如果我们想要在灰色背景上显示粗体青色文本（4 位颜色名称中的亮黑色），该怎么办？很简单：

982623155363

以下是每个部分的作用：

1 转义码后应用粗体效果；
36 设置文本颜色为青色；
100 将背景更改为亮黑色，其中 10 表示明亮，0 是黑色的代码。

利用这些知识，您可以使您的 cli 工具在视觉上更具吸引力。例如，我在项目中将所有 url 和文件路径设置为带下划线的蓝色文本：

console.log('\x1b[4;34m', './underlined/blue', '\x1b[0m')

查看此备忘单以了解有关该主题的更多信息。

总结

你永远不知道日常任务什么时候可能会激发出有益的副业项目。 starlight-to-pdf 的开发为 puppeteer 和 cli 样式提供了宝贵的经验，并且开源社区中出现了一种新工具。这是一个快速演示：

starlight-to-pdf usage demo

本篇关于《将 Starlight 转换为 PDF：经验和见解》的介绍就到此结束啦，但是学无止境，想要了解学习更多关于文章的相关知识，请关注golang学习网公众号！

声明：本文转载于：dev.to 如有侵犯，请联系study_golang@163.com删除