Mengubah Starlight kepada PDF: pengalaman dan cerapan

Bayangkan anda diberi tugas: buat tapak web dokumentasi baharu dalam masa seminggu. Ia mestilah menarik secara visual, pantas dan mudah dinavigasi. Anda telah menyerahkan timbunan *.docs fail, imej dan tangkapan skrin, dengan arahan untuk "selesaikannya".

Terdapat banyak alatan hebat untuk dipilih, seperti Docusaurus, Nextra, VitePress, Docus dan lain-lain. Sebelum ini, saya mempunyai pengalaman hebat membina tapak web dokumentasi dengan Starlight, jadi ia adalah pilihan saya untuk tugasan ini. Walau bagaimanapun, saya menemui ciri yang hilang: keupayaan untuk menjana PDF daripada dokumentasi. Dan ia adalah salah satu keperluan. "Kedengarannya seperti projek sampingan yang bagus," Saya fikir sendiri.

Menangani tugas

Pada mulanya, ia kelihatan mudah: ambil halaman, huraikan HTML, kumpulkan kandungan dan voila!

Tapak web berkuasa Starlight mempunyai butang Seterusnya untuk menavigasi dokumentasi. Memandangkan PDF pada asasnya adalah pelbagai halaman, nampaknya logik untuk menghuraikannya satu demi satu, menggunakan butang Seterusnya ini. Memandangkan tapak web menjana halaman statik, saya dengan cepat menulis skrip untuk mengambil HTML, menanyakan bahagian yang diperlukan dan menggabungkan semuanya bersama-sama. Walau bagaimanapun, menjana PDF yang mengekalkan gaya tapak web terbukti lebih kompleks. Selepas beberapa sumbang saran, saya menyedari Puppeteer adalah penyelesaian terbaik.

Kini proses menjadi jelas:

1. Kenal pasti halaman permulaan. Ini ialah halaman pertama dengan butang Seterusnya.
2. Navigasi melalui halaman. Ekstrak tajuk dan kandungan utama daripada setiap halaman dan pada masa yang sama bina jadual kandungan.
3. Gabungkan kandungan. Tambah pemisah halaman dan gaya tambahan.
4. Sediakan HTML akhir. Tulis semula halaman awal dengan HTML yang terhasil.
5. Muat sumber. Tatal halaman ke bawah untuk memuatkan semua imej.
6. Jana PDF. Kaedah Puppeteer's Page.pdf() memakukannya.
7. Selesai!

Beginilah cara starlight-to-pdf berfungsi. Mengikut corak ini, anda boleh membina alatan serupa untuk rangka kerja dokumentasi lain yang tidak mempunyai fungsi eksport PDF.

Langkah seterusnya

Setelah kefungsian asas sedia, tiba masanya untuk menambah beberapa tambahan. Di bawah ialah ciri yang paling menarik dan mencabar.

Menambah pengepala dan pengaki

Memang bagus untuk mempunyai nombor halaman dan beberapa maklumat tambahan dalam pengepala atau pengaki. Kaedah Puppeteer's Page.pdf() menerima pilihan headerTemplate dan footerTemplate. Pilihan ini menerima rentetan HTML. Puppeteer secara automatik menyuntik nilai ke dalam elemen yang mempunyai kelas utiliti tertentu:

• .tarikh: tarikh diformat;
• .title: halaman web nilai tag;
• .url: URL halaman yang mana fungsi pencetakan dipanggil;
• .Nombor halaman: nombor halaman semasa;
• .totalPages: jumlah bilangan halaman dalam dokumen.

Apabila kami menggabungkan semua kandungan pada satu halaman sebelum mencetak, tajuk dan url tidak mempunyai banyak nilai untuk kami: nilai yang dimasukkan akan sentiasa kekal sama. Walau bagaimanapun, kelas lain banyak membantu. Berikut ialah contoh templat pengaki:

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