How Does It Work?

Asciidoctor Web PDF converts an AsciiDoc document to a PDF file in a few steps:

  1. Asciidoctor converts the .adoc document to a single, self-contained HTML 5 page. This page inlines the base stylesheets, the syntax-highlighted source blocks (highlighted server-side by highlight.js), and any STEM expressions (rendered server-side by MathJax 4 into CHTML markup). There is no client-side JavaScript in this page.

  2. The HTML is written to a temporary .html file.

  3. Puppeteer opens the Vivliostyle Viewer, a standalone application, and points it at that file as its source document.

  4. The viewer paginates the document according to the CSS Paged Media specification, laying it out page by page.

  5. Puppeteer waits until the viewer reports that every page has been rendered, then prints the paginated result to a PDF using page.pdf().

  6. pdf-lib post-processes the generated PDF to add the document outline (bookmarks) and metadata (title, authors, subject, keywords, etc.).

Custom layouts

A custom layout (template.js) defines how each AsciiDoc node is converted to HTML 5 in the first step of the pipeline above — everything downstream (pagination and PDF generation) stays the same regardless of the layout used.