Integrate a PDF generation facility based on CSS Paged Media
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.