Starlight の PDF への変換: 経験と洞察

あなたに、1 週間以内に新しいドキュメント Web サイトを作成するというタスクが与えられたと想像してください。視覚的に魅力的で、高速で、操作が簡単である必要があります。 「やってください」 という指示とともに、大量の *.docs ファイル、画像、スクリーンショットが渡されます。

Docusaurus、Nextra、VitePress、Docus など、選択できる優れたツールが多数あります。以前、Starlight を使用してドキュメント Web サイトを構築した素晴らしい経験があったため、このタスクには Starlight を選択しました。しかし、ドキュメントから PDF を生成する機能という欠けている機能を発見しました。そしてそれは要件の1つでした。 「素敵なサイドプロジェクトですね」 私は自分で考えました。

課題に取り組む

最初は簡単そうに思えました。ページを取得し、HTML を解析し、コンテンツをグループ化すれば、出来上がりです!

Starlight を利用した Web サイトには、ドキュメント内を移動するための「次へ」ボタンがあります。 PDF は本質的にページの配列であるため、この「次へ」ボタンを使用してページを 1 つずつ解析するのが合理的であると思われます。 Web サイトは静的ページを生成するため、HTML をフェッチし、必要な部分をクエリして、すべてを組み合わせるスクリプトをすぐに作成しました。ただし、Web サイトのスタイルを保持した 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: Web ページの
• .url: 印刷機能が呼び出されたページの URL;
• .pageNumber: 現在のページ番号;
• .totalPages: ドキュメント内の総ページ数。

印刷前にすべてのコンテンツを 1 ページに結合するため、タイトルと URL にはあまり意味がありません。挿入された値は常に同じままです。ただし、他のクラスは非常に役立ちます。フッター テンプレートの例を次に示します:

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