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

Berikut ialah beberapa penemuan yang perlu anda ingat:

• Templat mestilah struktur HTML yang sah.
• Tentukan sifat CSS saiz fon sebagai nilai lalai Puppeteer ialah 0.
• Gunakan tag untuk menentukan gaya anda. Gaya tapak web tidak tersedia dalam templat.
• Imej hendaklah dikodkan sebagai rentetan base64.
• Gunakan pilihan margin Puppeteer untuk mencapai reka letak yang diingini.

Bagaimana pula dengan gaya CLI?

Semuanya berfungsi dengan baik, PDF yang terhasil kelihatan hebat, tetapi mesej terminal terasa hambar. Perhatian kepada butiran memisahkan yang baik daripada yang hebat, bukan? Mari jadikan mesej kami lebih berwarna dan lebih mudah dibaca.

Inilah keajaiban urutan pelarian ANSI. Saya memutuskan bahawa warna 4-bit akan mencukupi untuk kerja itu. Katakan anda ingin mempunyai teks putih pada latar belakang merah (itulah yang saya gunakan untuk [ERROR] saya: awalan sebelum mesej ralat). Berikut ialah cara anda boleh mencapai rupa ini:

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

Jom pecahkan:

• x1b[ ialah kod pelarian heksadesimal (anda juga boleh menggunakan u001b sebagai alternatif Unicode);
• 37 ialah warna putih latar depan, dengan 3 bermaksud latar depan dan 7 untuk warna putih;
• 41 ialah warna merah latar belakang, dengan 4 bermaksud latar belakang dan 1 untuk warna merah.

Semuanya berfungsi, tetapi kini semua keluaran console.log() kami akan digayakan dengan cara ini. Untuk menetapkan semula gaya kembali kepada lalai, cuma tambahkan jujukan tetapan semula x1b[0m di penghujung:

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

Lebih baik. Bagaimana jika kita mahu teks sian tebal pada latar belakang kelabu (hitam terang dalam nama warna 4-bit)? Mudah sahaja:

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

Inilah yang dilakukan oleh setiap bahagian:

• 1 selepas kod melarikan diri menggunakan kesan tebal;
• 36 menetapkan warna teks kepada cyan;
• 100 menukar latar belakang kepada warna hitam terang, dengan 10 bermaksud terang dan 0 ialah kod untuk hitam.

Menggunakan pengetahuan ini, anda boleh menjadikan alat CLI anda menarik secara visual. Sebagai contoh, saya menggayakan semua URL dan laluan fail sebagai teks biru bergaris dalam projek saya:

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

Lihat helaian tipu ini untuk mengetahui lebih lanjut tentang topik tersebut.

Membungkus

Anda tidak pernah tahu bila tugas rutin mungkin memberi inspirasi kepada projek sampingan yang bermanfaat. Pembangunan starlight-to-pdf memberikan pengalaman berharga dengan penggayaan Puppeteer dan CLI, dan alat baharu muncul dalam komuniti sumber terbuka. Berikut ialah demonstrasi pantas:

Atas ialah kandungan terperinci Mengubah Starlight kepada PDF: pengalaman dan cerapan. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!