Importing PDF Pages in asciidoctor-pdf

After spending what felt like a good number of days searching for a way to add full-bleed Part and Chapter separation pages to my book, and reading through the documentation for PDFBox, pyPDF2, and Asciidoctor looking for ways to render content all the way to the edge of a single page (100vw didn’t do it), I finally stumbled upon the solution which I should have just guessed from the start.

The answer isn’t (yet) in the official asciidoctor-pdf documentation, but it was part of an enhancement made over 4 years ago.

So first off, let me explain what I was looking for…

Books Do It Better

As I’ve been running through the final editing and stylization phases of my book, I noticed that the separation between certain Parts and Chapters was less clear than I had hoped.

This is something that print books do really well. They ensure that there are visual demarcations between content sections. It’s not something that the web focused as much on because of the format itself. Others have described this issue with Asciidoc as well, though the solutions are a bit less palatable for me.

So here is what I saw, between the end of one chapter and the beginning of the next chapter:

Essentially, even though there is a huge contextual break between these two pages, it is essentially left 100% implied. There is no stylistic or visual indication that the reader is moving from one part of the book to the next.

To fix this, I looked at writing scripts to find-and-replace single pages containing unique hash strings (like “6dd5a82af1feb402”, etc.) in the PDF. But neither PDFBox nor pyPDF2 would really have been a great way to do this, and there was the question of whether this would affect cross-references or even potentially corrupt the files, which are very large.

The Solution

Eventually, I stumbled onto the solution:

It is possible to import the first page of a fully-styled, completely separately-designed PDF file into a PDF generated by asciidoctor-pdf.

Here’s how you do it:

:imagesdir: ./

Using the image::[] macro to import a PDF will automatically add a page break before and after the imported page. I usually set the imagesdir attribute as well, since this value can change a lot over the course of a large document.

Here’s what the output looks like after doing this (with a draft Part separation page that uses full-bleed color):


This actually opens up a bunch of possibilities, as it means that you can design the bulk of a document using an Asciidoctor PDF theme configuration, and then tune individual pages which simply cannot ever be generated directly from .asciidoc files, using something like Adobe Illustrator or Inkscape.

Again, the reason I chose to use Asciidoc for the book was because of its ability to let me focus on the substance before having to worry about the style. This is the opposite of using something like Microsoft Word, for example.

Now that I’m looking at the style, the pain points of Asciidoc for this become clear, and certain workarounds like this become necessary.

I am convinced that it is possible to get a good-looking final output, but I am also sure it’s going to require quite a number of these tweaks.

Featured image: “Splitting log, tie-cutting camp, Pie Town, New Mexico”, Russell Lee, June 1940 (Source: Library of Congress)