Raible Designs

Customizing an Asciidoctor PDF so it looks like an InfoQ Mini-Book

Earlier this month, I finished the rough draft of the JHipster Mini-Book. Since then, I've been working with editors to get it ready for production. I've also been working with InfoQ to try and make the generated PDF look like their current mini-books. I wrote the book using Asciidoctor and I'm using Gradle to generate HTML5, PDF and EPUB versions.

After doing some research on Asciidoctor PDF themes I created an issue in the asciidoctor-pdf project. My reason for was to see if it was possible to customize certain sections of the generated PDF. The main issues I've had in making the PDF look like an InfoQ mini-book are the following:

1. The colophon is not aligned to the bottom of the page.
2. The title page (first one after the cover) and colophon pages should be merged.
3. The dedication and acknowledgement headers are not center-aligned and underlined like InfoQ's format.
4. The main sections don't have whole-page delimiters.
5. The table of contents comes right after the title page, rather than after the dedication and acknowledgement.

After thinking about this a bit more, I thought of a few possible workarounds.

1. I could add a number of line breaks at the beginning of the page to push everything down to the bottom.
2. We could delete the title page (with Preview on a Mac or another PDF editor).
3. We could create new PDF pages that have InfoQ's headers and my content. Then, using a PDF editor, we could delete pages and put the new ones in their place.
4. There might be a way to have no text in a section's title (so it doesn't show up at the top of a page) and do the same copy/paste of an InfoQ section-delimiting page (with large Part One text) before the section. The hard part here might be lining up the table of contents with page numbers.
5. Move pages around in the PDF and renumber pages using a PDF editor.

Even if all these workarounds are possible, this will only work for the PDF. InfoQ has asked me to make similar header customizations for the EPUB/MOBI versions.

I looked at the PDF theming guide and it looks like many things are customizable, but they're global customizations, not per-section customizations. Dedication, Acknowledgement, Preface, and Chapter Titles all live on the same level (level 2). I believe it's possible to customize how they all look, but I haven't figured out how to change an individual title.

The only thing I can think of beyond these workarounds are 1) hiring someone to create a custom theme for InfoQ or 2) forking the project and trying to make customizations to the source code myself.

I haven't had any feedback from the Asciidoctor team, so I'm posting this here to try and reach a wider audience. If you've authored a book in Asciidoctor, did you customize the output to fit your publisher's desired format, or did you just take the out as-is and publish it?