asciidoctor-web-pdf VS paper-css

I've been test-driving the web pdf build tool for Asciidoc, asciidoctor-web-pdf[1], for a few years, which uses Paged.js as the template engine before CSS PMM has its go. I like it - I like it a LOT[2] - but Puppeteer-Chrome bugs breaks the build on the regular, or requires a rework of templates. So the web-pdf team started just releasing docker images that include a tested Chromium version (among other things), so as to keep that from being such a PITA. Which is fine. Howaaaayyyyyyyver . . that shines a spotlight on a problem with this workflow: the dependency on browser rendering kit.

[1] https://github.com/ggrossetie/asciidoctor-web-pdf

https://github.com/ggrossetie/asciidoctor-web-pdf

I encourage everyone to take a look at the documentation; this is the markup language I now use for all my personal and professional projects.

https://github.com/ggrossetie/asciidoctor-web-pdf (this is an implementation of Paged.js +CSS for the Asciidoc markup language, as an alternative to asciidoctor-pdf [Ruby/Prawn] or asciidoctor-fopub [Docbook-XSL].)

We're currently ironing out the bugs for parallel AsciiDoc > PDF generation for downloadable/offline versions anyway, so once that's sorted we can use those for review again. Much as I hated writing book-style PDF help docs, Acrobat's commenting/review features are actually pretty hard to replace.

Asciidoctor-web-pdf https://github.com/Mogztter/asciidoctor-web-pdf for web-based PDF with Paged.JS and CSS.

You'll get extremely consistent output from Asciidoc, but I'm not gonna lie: customizing format is going to be a learning curve no matter what compared to MSO. Tweaking either 1) asciidoctor-pdf's yaml themes, 2) docbook-xsl overrides, or 3) asciidoctor-web-pdf's CSS and JS (via Paged.js Paged Media Module implementation). And if your parent org uses Office365 up and down the chain, Word publishing can be automated . . fairly well. You'll still get some surprises, but it's Word. It's the lingua franca for a reason.

How you turn including files into deliverables, there's a few paths, but HTML is the "natural" output, and PDF can be made with a few different tools depending on what the output format is required to look like. DocBook-XSL is a more complex but configurable processor, while the Ruby-based asciidoctor-pdf is the easier, more Honda-like option. I'm pretty fond of the "web-pdf" method (https://github.com/Mogztter/asciidoctor-web-pdf) which uses Paged.js and CSS to style the print document, but your mileage may vary depending on your CSS comfort level.

Asciidoctor has a web PDF tool that just went alpha a little bit ago, uses the same stack as the OP's thingie.

https://github.com/Mogztter/asciidoctor-web-pdf

The content handoff goes like this: Asciidoc (using defined roles) generates HTML5 (Pagedjs polyfills page areas / pagination stuff), CSS styles stuff, and Puppeteer runs a headless Chromium for the pdf render. It's straight from CSS GCPM W3C spec, a flavor of CSS Paged Media, drafts that have been percolating since frickin' 2006 but have never seen browser implementation.

Just use asciidoc.

E.g.

- https://github.com/Mogztter/asciidoctor-web-pdf/tree/master/...

I appreciated the read, but in real life just link to the css file in Paper-CSS[1].

It may not be a lot of CSS, but it is much easier for me to just include the page and have it deal with my page size than to review articles like this when I want to pint.

[1]: https://github.com/cognitom/paper-css

cognitom/paper-css - Paper CSS for happy printing