Skip to content
GitLab
    • GitLab: the DevOps platform
    • Explore GitLab
    • Install GitLab
    • How GitLab compares
    • Get started
    • GitLab docs
    • GitLab Learn
  • Pricing
  • Talk to an expert
  • /
  • Help
    • Help
    • Support
    • Community forum
    • Submit feedback
    • Contribute to GitLab
    • Switch to GitLab Next
    Projects Groups Snippets
  • Sign up now
  • Login
  • Sign in / Register
  • Antora Antora
  • Project information
    • Project information
    • Activity
    • Labels
    • Members
  • Repository
    • Repository
    • Files
    • Commits
    • Branches
    • Tags
    • Contributors
    • Graph
    • Compare
    • Locked Files
  • Issues 139
    • Issues 139
    • List
    • Boards
    • Service Desk
    • Milestones
    • Iterations
    • Requirements
  • Merge requests 20
    • Merge requests 20
  • CI/CD
    • CI/CD
    • Pipelines
    • Jobs
    • Schedules
    • Test Cases
  • Deployments
    • Deployments
    • Environments
    • Releases
  • Monitor
    • Monitor
    • Incidents
  • Analytics
    • Analytics
    • Value stream
    • CI/CD
    • Code review
    • Insights
    • Issue
    • Repository
  • Snippets
    • Snippets
  • Activity
  • Graph
  • Create a new issue
  • Jobs
  • Commits
  • Issue Boards
Collapse sidebar
  • AntoraAntora
  • AntoraAntora
  • Issues
  • #349
Closed
Open
Issue created 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 an admin enable hashed storage. More information
Assignee
Assign to
Time tracking