Import PDF Pages

In addition to using a PDF page for the front or back cover, you can also insert a PDF page at an arbitrary location in your document. This technique is useful for adding pages that have complex layouts and graphics prepared in a specialized design program, which would otherwise not be achievable using this converter. One such example is an insert for an advertisement or visual interlude.

Import a page

To import the first page from a PDF file, use the block image macro with the PDF filename as the image target.

image::custom-page.pdf[]

The converter will insert the page from the PDF as a dedicated page that matches the size and layout of the page being imported (no matter where the block image occurs). Therefore, there’s no need to put a manual page break (i.e., <<<) around the image macro.

By default, this macro will import the first page of the PDF. To import a different page, specify it as a 1-based index using the page attribute.

image::custom-pages.pdf[page=2]

To learn how to add a TOC entry for imported PDF pages, see Add a TOC entry for an imported PDF.

Import multiple pages

You can import multiple pages either using multiple image macros or using the pages attribute. The pages attribute accepts individual page numbers or page number ranges (two page numbers separated by ..). The values can be separated either by commas or semicolons. (The syntax is similar to the syntax uses for the lines attribute of the AsciiDoc include directive).

image::custom-pages.pdf[pages=3;1..2]

Pages are imported in the order listed.

To see a practical example of how to use this feature, refer to the blog post Importing PDF Pages in asciidoctor-pdf.

An image macro used to import PDF pages should never be nested inside a delimited block or table cell. It should be a direct descendant of the document or a section. That’s because what it imports are entire pages. If it’s used inside a delimited block or table cell, the behavior is unspecified.