= 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.

[#page]
== 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.

[,asciidoc]
----
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.

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

TIP: To learn how to add a TOC entry for imported PDF pages, see xref:notitle.adoc#imported[Add a TOC entry for an imported PDF].

[#multiple-pages]
== 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).

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

Pages are imported in the order listed.

CAUTION: 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.
