將 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>