Transforming Starlight into PDF: experience and insights

Imagine you are given a task: create a new documentation website in a week. It should be visually appealing, fast, and easy to navigate. You’re handed a pile of *.docs files, images, and screenshots, with the instruction to "get it done".

There are many excellent tools to choose from, such as Docusaurus, Nextra, VitePress, Docus, and others. Previously, I had a great experience building a documentation website with Starlight, so it was my choice for this task. However, I discovered a missing feature: the ability to generate a PDF from the documentation. And it was one of the requirements. "Sounds like a nice side project," I thought for myself.

Tackling the task

At first, it seemed straightforward: fetch the pages, parse the HTML, group the content, and voila!

Starlight powered websites have a Next button to navigate through the documentation. As PDF essentially is an array of pages, it seemed logical to parse them one by one, using this Next button. Since the website generates static pages, I quickly wrote a script to fetch the HTML, query the necessary parts, and combine everything together. However, generating a PDF that retained the website's styles proved to be more complex. After some brainstorming, I realized Puppeteer was the best solution.

Now the process became clear:

1. Identify the starting page. This is the first page with a Next button.
2. Navigate through the pages. Extract the heading and main content from each page and at the same time build a table of contents.
3. Combine the content. Add page breaks and additional styles.
4. Prepare the final HTML. Rewrite the of the initial page with the resulting HTML.
5. Load resources. Scroll the page to the bottom to load all the images.
6. Generate the PDF. Puppeteer's Page.pdf() method nails it.
7. Done!

This is how starlight-to-pdf works. Following this pattern, you can build similar tools for other documentation frameworks lacking PDF export functionality.

Next steps

Once the basic functionality was ready, it was time to add some extras. Below are the most interesting and challenging features.

Adding headers and footers

It's nice to have a page number and some additional information in the header or footer. Puppeteer's Page.pdf() method accepts headerTemplate and footerTemplate options. These options accept HTML strings. Puppeteer automatically injects values into the elements that have specific utility classes:

• .date: formatted date;
• .title: web page's
• .url: page's URL on which printing function was called;
• .pageNumber: current page number;
• .totalPages: total number of pages in the document.

As we combine all the content on one page before printing, title and url don't have much value for us: the inserted value will always remain the same. However, other classes help a lot. Here’s an example footer template:

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