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.
To upload designs, you'll need to enable LFS and have admin enable hashed storage. More information