Adding a custom page to a PDF document

Use page insertion to control document structure in generated PDFs.

Common use cases include:

  • Inserting invoice cover pages
  • Adding divider pages between legal sections
  • Appending signature pages to forms
  • Inserting note pages in educational documents
  • Adding title or section pages in generated reports

This guide shows how to:

  • Insert pages at specific positions (zero-based index)
  • Define custom page dimensions in points (1 inch = 72 points)
  • Export the final document as PDF
Download sample

How Nutrient helps

Nutrient Java SDK handles page collection management, insertion, and format conversion.

The SDK handles:

  • PDF page structure and internal page tree dictionaries
  • Page dimensions and coordinate transformations for different page sizes
  • Document format conversion from Word, Excel, and PowerPoint to PDF
  • Complex page indexing and insertion position validation

Complete implementation

This example inserts a custom page and exports the result as PDF:

package io.nutrient.Sample;


import io.nutrient.sdk.Document;
import io.nutrient.sdk.exceptions.NutrientException;
import io.nutrient.sdk.editors.PdfEditor;
import io.nutrient.sdk.editors.pdf.pages.PdfPageCollection;

Create the main class and entry point:

public class PDFEditor {
    public static void main(String[] args) throws NutrientException {

Opening a document

Open the source document with try-with-resources so Java closes resources after processing.

In this sample, you open a Word file (.docx). The SDK also supports:

  • PDF files
  • Word binary files (.doc)
  • PowerPoint files (.pptx) and PowerPoint binary files (.ppt)
  • Excel files (.xlsx) and Excel binary files (.xls)
  • Input streams
        try (Document document = Document.open("input.docx")) {

Creating a PDF editor instance

Create a PdfEditor to enable page operations on the opened document:

            PdfEditor editor = PdfEditor.edit(document);

Adding custom pages

Get the page collection and insert a page with pages.insert(index, width, height).

Parameters:

  • index: zero-based insertion point
  • width: page width in points
  • height: page height in points

In this sample:

  • pages.insert(4, 500.0f, 800.0f) inserts a page at index 4 (fifth position).
  • 500.0f × 800.0f points is a custom page size.

Common page sizes:

  • US Letter: 612 × 792 points
  • A4: 595 × 842 points
  • Legal: 612 × 1008 points
            PdfPageCollection pages = editor.getPageCollection();
            pages.insert(4, 500.0f, 800.0f);

Saving and exporting

Save changes, close the editor, and export the document as PDF:

            editor.save();
            editor.close();


            document.exportAsPdf("output.pdf");
        }
    }
}

Error handling

The Java SDK throws NutrientException when document operations fail.

Common failure scenarios include:

  • The input file can’t be read due to file system permissions, path errors, or file locking by another process
  • Document data is corrupted or uses an unsupported file format, preventing proper parsing
  • Insufficient system memory for loading large documents or performing format conversion
  • Invalid page insertion index (negative or beyond document bounds) causing index out of range errors
  • Invalid page dimensions (zero or negative width/height values) preventing page creation
  • PDF export failures due to incompatible document features or encoding issues

In production code:

  • Catch NutrientException.
  • Return a clear error message.
  • Log failure details for debugging.

Conclusion

Use this workflow to add custom pages:

  1. Open the source document using try-with-resources for automatic resource cleanup.
  2. The SDK supports opening documents from file paths or input streams for different integration scenarios.
  3. Supported input formats include Word (.docx, .doc), PowerPoint (.pptx, .ppt), Excel (.xlsx, .xls), and existing PDF documents.
  4. Create a PDF editor instance with PdfEditor.edit() to enable document manipulation operations.
  5. The editor maintains document state throughout the editing session until changes are saved.
  6. Retrieve the page collection with editor.getPageCollection() to access all document pages.
  7. Insert a custom page with pages.insert() using three parameters: position index (zero-based), width in points, and height in points.
  8. Page dimensions are specified in points where 1 inch = 72 points (e.g. 500 points ≈ 6.94 inches).
  9. Standard page sizes include US Letter (612 × 792 points), A4 (595 × 842 points), and Legal (612 × 1008 points).
  10. Zero-based indexing means index 0 inserts before the first page, and index 4 becomes the fifth page position.
  11. Save editor modifications with editor.save() to persist page insertions to the document structure.
  12. Close the editor with editor.close() to release resources, including memory buffers and temporary data.
  13. Export the document as PDF with document.exportAsPdf(), which converts the source format with inserted pages.
  14. Handle NutrientException errors for robust error recovery including invalid indices, dimensions, or file format issues.

For related document workflows, refer to the Java SDK guides.

Download this ready-to-use sample package, fully configured to help you explore the page manipulation capabilities.