Transforming Starlight into PDF: experience and insights

Alexei — Tue, 14 Jan 2025 20:44:44 +0000

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:

Identify the starting page. This is the first page with a Next button.
Navigate through the pages. Extract the heading and main content from each page and at the same time build a table of contents.
Combine the content. Add page breaks and additional styles.
Prepare the final HTML. Rewrite the <body> of the initial page with the resulting HTML.
Load resources. Scroll the page to the bottom to load all the images.
Generate the PDF. Puppeteer's Page.pdf() method nails it.
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 <title> tag value;
.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 class="footer-container">
  <div>Awesome docs</div>
  <div>
    <!-- Numbers inside the elements with `.pageNumber` and `.totalPages` classes are injected automatically by Puppeteer -->
    <span class="pageNumber"></span> / <span class="totalPages"></span>
  </div>
  <!-- Same for the `.date` class value -->
  <div class="date"></div>
</div>

To use this, do not forget to set the displayHeaderFooter property to true:

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

Here are some findings that you should keep in mind:

The template must be a valid HTML structure.
Define font-size CSS property as Puppeteer's default value is 0.
Use inline <style> tag to define your styles. Website styles are not available inside the templates.
Images should be encoded as base64 strings.
Use Puppeteer's margin option to achieve the desired layout.

What about CLI styles?

Everything works fine, the resulting PDF looks great, but the terminal messages feel bland. Attention to details separates the good from the great, isn’t it? Let's make our messages more colorful and easier to read.

Here comes the magic of ANSI escape sequences. I decided that 4-bit colours would be enough for the job. Let's say you want to have a white text on red background (that's what I used for my [ERROR]: prefix before error messages). Here is how you can achieve this look:

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

Let's break it down:

\x1b[ is a hexadecimal escape code (you may also use \u001b as the Unicode alternative);
37 is a foreground white color, where 3 stands for foreground and 7 for the white color;
41 is a background red color, where 4 stands for background and 1 for the red color.

Everything is working, but now all of our console.log() output will be styled in this manner. To reset the style back to default, simply add the reset sequence \x1b[0m at the end:

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

Much better. What if we want bold cyan text on a gray background (bright black in the names of 4-bit colors)? It's easy:

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

Here’s what each part does:

1 after the escape code applies the bold effect;
36 sets the text color to cyan;
100 changes the background to bright black color, where 10 means bright and 0 is a code for black.

Using this knowledge, you can make your CLI tool visually appealing. For example, I styled all URLs and file paths as underlined blue text in my project:

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

Check out this cheatsheet to learn more on the topic.

Wrapping up

You never know when a routine task might inspire a rewarding side project. Development of starlight-to-pdf provided valuable experience with Puppeteer and CLI styling, and a new tool emerged in the open source community. Here’s a quick demonstration: