Short Answer:
Puppeteer controls Chrome or Chromium over the DevTools Protocol.
Chromium uses Skia for PDF generation.
Skia handles the header, set of objects, and footer separately.
Detailed Answer:
From the Puppeteer Documentation:
page.pdf(options)
options <Object> Options object which might have the following properties:
headerTemplate <string> HTML template for the print header. Should be valid HTML markup with following classes used to inject printing values into them:
date formatted print datetitle document titleurl document locationpageNumber current page numbertotalPages total pages in the document
footerTemplate <string> HTML template for the print footer. Should use the same format as the headerTemplate.
- returns: <Promise<Buffer>> Promise which resolves with PDF buffer.
NOTE Generating a pdf is currently only supported in Chrome headless.
NOTE headerTemplate and footerTemplate markup have the following limitations:
- Script tags inside templates are not evaluated.
- Page styles are not visible inside templates.
We can learn from the the Puppeteer source code for page.pdf() that:
- The Chrome DevTools Protocol method
Page.printToPDF (along with the headerTemplate and footerTemplate parameters) are sent to to page._client.
page._client is an instance of page.target().createCDPSession() (a Chrome DevTools Protocol session).
From the Chrome DevTools Protocol Viewer, we can see that Page.printToPDF contains the parameters headerTemplate and footerTemplate:
Page.printToPDF
Print page as PDF.
PARAMETERS
headerTemplate string (optional)
- HTML template for the print header. Should be valid HTML markup with following classes used to inject printing values into them:
date: formatted print datetitle: document titleurl: document locationpageNumber: current page numbertotalPages: total pages in the document
- For example,
<span class=title></span> would generate span containing the title.
footerTemplate string (optional)
- HTML template for the print footer. Should use the same format as the
headerTemplate.
RETURN OBJECT
The Chromium source code for Page.printToPDF shows us that:
- The
Page.printToPDF parameters are passed to the sendDevToolsMessage function, which issues a DevTools protocol command and returns a promise for the results.
After further digging, we can see that Chromium has a concrete implementation of a class called SkDocument that creates PDF files.
SkDocument comes from the Skia Graphics Library, which Chromium uses for PDF generation.
The Skia PDF Theory of Operation, in the PDF Objects and Document Structure section, states that:
Background: The PDF file format has a header, a set of objects and then a footer that contains a table of contents for all of the objects in the document (the cross-reference table). The table of contents lists the specific byte position for each object. The objects may have references to other objects and the ASCII size of those references is dependent on the object number assigned to the referenced object; therefore we can’t calculate the table of contents until the size of objects is known, which requires assignment of object numbers. The document uses SkWStream::bytesWritten() to query the offsets of each object and build the cross-reference table.
The document explains further down:
The PDF backend requires all indirect objects used in a PDF to be added to the SkPDFObjNumMap of the SkPDFDocument. The catalog is responsible for assigning object numbers and generating the table of contents required at the end of PDF files. In some sense, generating a PDF is a three step process. In the first step all the objects and references among them are created (mostly done by SkPDFDevice). In the second step, SkPDFObjNumMap assigns and remembers object numbers. Finally, in the third step, the header is printed, each object is printed, and then the table of contents and trailer are printed. SkPDFDocument takes care of collecting all the objects from the various SkPDFDevice instances, adding them to an SkPDFObjNumMap, iterating through the objects once to set their file positions, and iterating again to generate the final PDF.
