Skip to content

GitLab

  • Projects
  • Groups
  • Snippets
  • Help
    • Loading...
  • Help
    • Help
    • Support
    • Community forum
    • Submit feedback
    • Contribute to GitLab
    • Switch to GitLab Next
  • Sign in / Register
Antora
Antora
  • Project overview
    • Project overview
    • Details
    • Activity
    • Releases
  • Repository
    • Repository
    • Files
    • Commits
    • Branches
    • Tags
    • Contributors
    • Graph
    • Compare
    • Locked Files
  • Issues 172
    • Issues 172
    • List
    • Boards
    • Labels
    • Service Desk
    • Milestones
    • Iterations
  • Merge Requests 35
    • Merge Requests 35
  • Requirements
    • Requirements
    • List
  • CI / CD
    • CI / CD
    • Pipelines
    • Jobs
    • Schedules
    • Test Cases
  • Security & Compliance
    • Security & Compliance
    • Dependency List
    • License Compliance
  • Operations
    • Operations
    • Incidents
    • Environments
  • Analytics
    • Analytics
    • CI / CD
    • Code Review
    • Insights
    • Issue
    • Repository
    • Value Stream
  • Snippets
    • Snippets
  • Members
    • Members
  • Collapse sidebar
  • Activity
  • Graph
  • Create a new issue
  • Jobs
  • Commits
  • Issue Boards
  • Antora
  • AntoraAntora
  • Issues
  • #349

Closed
Open
Opened Nov 25, 2018 by Guillem Marpons@gmarpons

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
Assignee
Assign to
M2
Milestone
M2
Assign milestone
Time tracking
None
Due date
None
Reference: antora/antora#349