Adding a custom page to a PDF document

Use page insertion to control document structure in generated PDFs.

Common use cases include:

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

This guide shows how to:

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

How Nutrient helps

Nutrient Python SDK handles page collection management, insertion, and document conversion.

The SDK handles:

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

Complete implementation

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

from nutrient_sdk import Document
from nutrient_sdk import PdfEditor
from nutrient_sdk import NutrientException

Opening a document

Open the input document in a context manager(opens in a new tab) so Python 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
def main():
    try:
        with Document.open("input.docx") as document:

Creating a PDF editor and accessing pages

Create a PdfEditor and get the page collection.

Use this object to insert, remove, or reorder pages:

            editor = PdfEditor.edit(document)
            pages = editor.get_page_collection()

Adding custom pages

Insert a page with pages.insert(index, width, height).

Parameters:

  • index: zero-based insertion point (0 inserts before the first page)
  • width: page width in points
  • height: page height in points

In this example:

  • pages.insert(0, 500.0, 800.0) inserts the page at the beginning.
  • 500.0 × 800.0 points is a custom page size.

Common page sizes:

  • US Letter: 612 × 792 points
  • A4: 595 × 842 points
  • Legal: 612 × 1008 points
            pages.insert(0, 500.0, 800.0)

Saving and exporting

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

The except block catches NutrientException for processing failures:

            editor.save()
            editor.close()


            document.export_as_pdf("output.pdf")
            print("Successfully added page and exported PDF")
    except NutrientException as e:
        print(f"Error: {e}")




if __name__ == "__main__":
    main()

Error handling

The SDK raises NutrientException when an operation fails.

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 exception details for debugging.

Conclusion

To add custom pages to a PDF workflow:

  1. Open the source document with a context manager(opens in a new tab).
  2. Create an editor with PdfEditor.edit(document).
  3. Get pages with editor.get_page_collection().
  4. Insert a page with pages.insert(index, width, height).
  5. Save and close the editor.
  6. Export the result with document.export_as_pdf().
  7. Catch NutrientException to handle failures.

For broader document workflows, refer to the Python SDK guides for format conversion and advanced editing.

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