將 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>...</div>' // replace with the HTML string from the example above
await page.pdf({
    displayHeaderFooter: true,
    footerTemplate: footerTemplateStr
})

以下是您應該牢記的一些發現：

• 模板必須是有效的 HTML 結構。
• 定義 font-size CSS 屬性，Puppeteer 的預設值為 0。
• 使用內嵌
• 影像應編碼為 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 位元顏色名稱中的亮黑色），該怎麼辦？很簡單：

console.log('\x1b[1;36;100m', 'Cyan on gray message in bold', '\x1b[0m');

以下是每個部位的作用：

• 1 轉義碼後塗抹粗體效果；
• 36 設定文字顏色為青色；
• 100 將背景改為亮黑色，其中 10 表示明亮，0 是黑色的程式碼。

利用這些知識，您可以讓您的 CLI 工具在視覺上更具吸引力。例如，我在專案中將所有 URL 和檔案路徑設定為帶下劃線的藍色文字：

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

查看此備忘單以了解有關該主題的更多資訊。

總結

你永遠不知道什麼時候日常任務可能會激發出有益的副業項目。 starlight-to-pdf 的開發為 Puppeteer 和 CLI 樣式提供了寶貴的經驗，並且在開源社群中出現了一種新工具。這是一個快速示範：

以上是將 Starlight 轉換為 PDF：經驗和見解的詳細內容。更多資訊請關注PHP中文網其他相關文章！