GitLab

This feature request aims at integrating into the regular static site generation process a facility to create a PDF file given the following inputs:

• A regular Antora component or module.
• An extra Asciidoc file describing the contents of the PDF file: which Asciidoc files to include, in which order, with what leveloffset, and maybe some extra information like what text to show in the cover or the preamble pages, etc.
• Some CSS files defining the presentation properties of the document, like page layout, fonts, formatting styles, running header/footers, etc.
• (Optionally) Some configuration variables defined either in the Antora Playbook (it makes sense that all the PDF files generated for a site share some properties) or the antora.yml file of the component.

CSS Paged Media is a W3C draft extending CSS to specify all the presentation elements necessary for paged documents (margins, page numbers, page breaking behavior, headers/footers, etc).

Even if there are other possible Asciidoc to PDF toolchains (and arguably more mature and feature-complete), and without detriment of trying other routes in parallel, this feature is specifically about an Asciidoc -> HTML + CSS -> PDF workflow. The advantages of such a toolchain in the case of Antora would be that:

• CSS has full access to Asciidoc roles, making styling very flexible. Asciidoctor-pdf support for styling is far less flexible. A DocBook based toolchain can probably provide a very powerful styling (and better pagination algorithms at time being), but creating and maintaining two completely different style specifications (based on different technologies) for Web and PDF seems onerous.
• All the site/document-specific tweaks done for the HTML generation (via Asciidoctor.js extensions or via web templating) can be reused for the PDF.